ZeroByte documentation
ZeroByte moves private data between two paired devices of one app. Every message is sealed on the device that sends it. A relay files the sealed envelope under a mailbox and deletes it once the other device has collected it. The relay never holds a key, so it cannot read, alter or forge what it carries.
Use it for a phone and its companions: a laptop, a tablet, a watch, a browser tab, a desktop app. The two devices agree a 32-byte link key once, when they pair. Every identifier and every key is derived from it on the devices.
This repository is the developer documentation for the open protocol, the open-source relay and the four SDKs. It covers everything you need to run your own relay and build on it.
A mirror of this documentation is published at docs.zerobyte.cloud. This repository is the source; if the two differ, this repository is current.
Contents
Getting started
- Overview: what ZeroByte is, what it is not, and how the parts fit
- Concepts: link, primary and companion, directions, mailbox, app id, sequence numbers
- Quickstart: a local relay and two devices exchanging a message in ten minutes
Protocol
- Protocol overview
- Keys and derivation
- Envelope format
- HTTP API
- Watch WebSocket
- Client behaviour
- Limits
- Test vectors
Running a relay
- Relay overview
- Node
- Docker with automatic HTTPS
- Cloudflare Workers
- Configuration reference
- Operations: TLS, storage, upgrades, monitoring, what the relay keeps
SDKs
- SDK overview: what every SDK has in common
- Swift: iOS, iPadOS, macOS, watchOS, tvOS, visionOS
- Android and JVM: Kotlin
- JavaScript: browsers, Node, Deno, Bun, Workers
- .NET: Windows desktop and services
Guides
- Pairing devices
- Storing the link key
- Designing messages
- Link lifecycle: first claim, unpairing, expiry, recovery
- Testing your integration
- Implementing a new SDK
- Troubleshooting
Project
Repositories
| Repository | Contents | Licence |
|---|---|---|
| zerobyte-protocol | The specification and the test vectors | CC-BY-4.0; vectors also Apache-2.0 |
| zerobyte-relay | The relay: Node server and Cloudflare Worker | AGPL-3.0-only |
| zerobyte-swift-sdk | Swift package | Apache-2.0 |
| zerobyte-android-sdk | Kotlin library | Apache-2.0 |
| zerobyte-js-sdk | JavaScript package | Apache-2.0 |
| zerobyte-dotnet-sdk | .NET library | Apache-2.0 |
| zerobyte-docs | This documentation | CC-BY-4.0; code samples also Apache-2.0 |
The canonical specification is
relay-v1.md in
zerobyte-protocol. Where this documentation and the specification disagree, the specification
wins; please report the difference.
Licence
Text under CC-BY-4.0. Code samples are also available under Apache-2.0, so you can copy them into your app under the same terms as the SDKs. See NOTICE.