readme

README.md

@@ -2,19 +2,21 @@
 
 `zrok` is a next-generation, peer-to-peer sharing platform built on top of [OpenZiti](https://docs.openziti.io/docs/learn/introduction/), a programmable zero-trust network overlay. `zrok` is a _Ziti Native Application_.
 
-`zrok` facilitates sharing resources both publicly and privately, exposing them to an audience you can easily control. Public sharing allows you to share `zrok` resources with non-`zrok` users over the public internet. Private sharing allows you to directly share peer-to-peer with other `zrok` users without changing your security or firewall settings.
+`zrok` facilitates sharing resources both publicly and privately. Public sharing allows you to share `zrok` resources with non-`zrok` users over the public internet. Private sharing allows you to directly share your resources peer-to-peer with other `zrok` users without changing your security or firewall settings.
 
-Like other offerings in this space, `zrok` allows users to create ephemeral reverse proxies ("tunnels") for HTTP, TCP and UDP resources. Additionally:
+Like other offerings in this space, `zrok` allows users to share tunnels for HTTP, TCP and UDP network resources. 
 
-* `zrok` allows users to _privately_ share resources with other `zrok` users; in _private_ usage scenarios, your private resources are not exposed to any public endpoints; all communication is securely and privately transported between `zrok` environments
+![zrok Web Console](/home/michael/Repos/nf/zrok/docs/images/zrok_web_console.png)
-* `zrok` allows sharing other types of resources; rather than just proxying `http` endpoints, `zrok` allows users to easily and rapidly share files and web content
-* `zrok` is ready to be extended to easily support many kinds of decentralized resource sharing; `zrok` provides a framework that makes this kind of peer-to-peer resource sharing simple and secure
 
-![zrok](docs/images/zrok_deployment.png)
+## Extensible
+
+`zrok` allows sharing other types of resources; rather than just proxying HTTP or other network resources, `zrok` allows users to easily and rapidly share files, web content, and custom resources in a peer-to-peer manner.
+
+`zrok` is an extensible platform for sharing.
 
 ## Frictionless
 
-You can be up and sharing using the `zrok.io` service in minutes. Here is a synopsis of what's involved.
+You can be up and sharing using the `zrok.io` service in minutes. Here is a synopsis of what's involved:
 
 ### First-time Setup
 
@@ -28,6 +30,40 @@ You can be up and sharing using the `zrok.io` service in minutes. Here is a syno
 
 See the [Concepts and Getting Started Guide](docs/getting-started.md) for a full overview.
 
+## The `zrok` SDK
+
+`zrok` includes an SDK that allows you to embed `zrok` sharing capabilities into your own applications. If you're familiar with a golang `net.Conn` and `net.Listener`, you'll be right at home with our SDK.
+
+### A Simple `zrok` Sharing Service
+
+```go
+// load enabled zrok environment
+root, err := environment.LoadRoot()
+
+// request a share for your resource
+shr, err := sdk.CreateShare(root, &sdk.ShareRequest{
+    BackendMode: sdk.TcpTunnelBackendMode,
+    ShareMode:   sdk.PrivateShareMode,
+	// ...
+})
+
+// accept requests for your resource
+listener, err := sdk.NewListener(shr.Token, root)
+```
+
+### A Simple `zrok` Client
+
+```go
+// load enabled zrok environment
+root, err := environment.LoadRoot()
+
+// request access to a shared zrok resource
+acc, err := sdk.CreateAccess(root, &sdk.AccessRequest{ShareToken: shrToken})
+
+// establish a connection to the resource directly
+conn, err := sdk.NewDialer(shrToken, root)
+```
+
 ## Self-Hosting
 
 `zrok` is designed to scale up to support extremely large service instances. `zrok.io` is a public service instance operated by NetFoundry using the same code base that is available to self-hosted environments.