Open source SDK · Apache-2.0
Pair two devices. No account, no server to trust.
A phone that syncs with a laptop. A desktop app you reach from your phone. Every app like this rebuilds pairing, keys, permissions and revocation.
Tendril is those parts, built once in a Rust core. You show a code, a person compares a check string, and the two devices talk directly.
Using an app built on Tendril? What it means for you
- phone dev_7a91c04e2b6d3f18
- active
- Grants
- none
- notes.sync
- expires in 60 min
- fs.read:/photos/*
- not granted
Example screens. Your app draws its own. Tendril supplies the code, the check string and the result.
Six things every device-to-device app rebuilds.
A socket is the easy part. Apps most often get 02 and 04 wrong.
- 01
Finding each other
Six ways to connect, from a local socket to a relay. Every path is untrusted. It counts only once the peer proves who it is.
- 02
Knowing it is the right device
The code is bound to this one handshake. Then a person compares a 16-character check string on both screens. Machines with no screen enroll with a signed, single-use token instead.
- 03
Where keys live
Files only your user account can read on desktops and servers, wiped from memory after use. Keychain and Android Keystore adapters for mobile.
- 04
Revoking a lost device
Each device is pending, active or revoked. Signed revocation lists also reach sessions that are already open.
- 05
What the link may do
Nothing, until a signed grant (a permission) says so. Grants expire. They can be passed on, but only narrower, and at most four times.
- 06
When the network changes
The pairing belongs to the devices, not the path. A new path needs a new handshake, never a new pairing.
Where it fits.
Apps that link devices one person or one team already owns.
Mac mini and phone
Reach your desktop app from your phone
No open port, no cloud dashboard. The phone gets only what you grant.
laptop, phone, browser
Sync your own devices, with no account
Directly on home Wi-Fi, with no internet needed.
NAS and phone
Appliances without the maker's cloud
The maker runs at most a relay that cannot read what it carries.
server and CI runner
Machines with no screen
A token that works once, instead of a key that lasts for months.
Six ways to connect, nearest first.
Every path is untrusted. A path counts only once the other device proves who it is inside the handshake, so a captive portal or a wrong host that answers never wins.
- 01local same machineother machine
- 02direct home or office LANin use
- 03overlay an existing tailnetnot used
- 04p2p hole punching via irohnot used
- 05relay blind, sealed packetsnot usedrelay
- 06broker WebSocket via a proxynot used
Same network. On one network, the direct path proves the other device first and wins.
The phone and the laptop share a home network. Local does not apply, as they are different machines. The direct path completes the handshake and is in use. Overlay, peer-to-peer, relay and broker are not used.
Across the internet. Away from home, the direct path fails and hole punching through iroh wins.
A phone on mobile data reaches the laptop at home. Local does not apply. On the direct path a wrong host answers and fails the handshake, so it does not count. There is no tailnet. The peer-to-peer path through iroh completes the handshake and is in use.
Strict NAT or firewall. When nothing direct gets through, a relay carries sealed packets it cannot read.
- The relay sees
- IP addresses, timing, sizes, a mailbox key
- It cannot see
- Your data, grants, device names, the pairing code
A phone on an office network reaches the laptop at home. The direct path and the peer-to-peer path are blocked, and there is no tailnet. The relay path is in use. The broker path is not used.
Network changes. The phone leaves Wi-Fi, so the devices handshake again on another path and keep their pairing.
A phone on home Wi-Fi uses the direct path to the laptop. The phone moves to mobile data and the direct path drops. The devices handshake again, and the peer-to-peer path is now in use. The pairing is the same, with no new pairing needed.
In a browser. A browser tab joins only as a client and cannot hole punch, so it always goes through a relay.
- The relay sees
- IP addresses, timing, sizes, a mailbox key
- It cannot see
- Your data, grants, device names, the pairing code
A browser tab reaches the laptop through the relay path, which is in use. Local, direct, overlay and broker are not available in a browser. With the opt-in p2p build, a tab can also take the p2p path, but only through an iroh relay, as a browser cannot open UDP sockets.
Illustrative. Device names, networks and timing are examples.
Built on other projects, not in place of them.
Tendril does not replace iroh, Noise or the platform keystores. It uses them, and adds the layer every app ends up writing itself, everything between your app and the network.
- Your appScreens, and the names of its grants
- TendrilPairing · check string · grants · revocation · choosing a path
- Built oniroh · Noise · ML-KEM · ML-DSA · Argon2id · Ed25519 · Keychain · Android Keystore
Need only a connection, with your own pairing and permissions? Use iroh directly.
Serve, pair, confirm, grant.
The same steps in every language. Your app owns the screens and the names of its grants. Tendril owns everything with a key in it.
uv add tendril-sdkimport json, tendril
host = tendril.Endpoint("./laptop-state", "laptop")
addr = host.serve_direct("127.0.0.1:0")
code = host.issue_code("lan") # show as text or a QR
req = json.loads(host.pair_accept(5000))
host.confirm_peer(req["device_id"], req["sas"]) # after a person compares the check string
grant = host.mint_grant(req["device_id"], ["notes.sync"], ttl_secs=3600)
session = host.accept_session(5000)
session.authorize("notes.sync") # True
npm install @tendril-sdk/nodeimport tendril from "@tendril-sdk/node";
const host = new tendril.Endpoint("./laptop-state", "laptop");
const addr = await host.serveDirect("127.0.0.1:0");
const code = host.issueCode("lan"); // show as text or a QR
const req = JSON.parse(await host.pairAccept(5000));
host.confirmPeer(req.device_id, req.sas); // after a person compares the check string
const grant = host.mintGrant(req.device_id, ["notes.sync"], 3600);
const session = await host.acceptSession(5000);
await session.authorize("notes.sync"); // true
go get github.com/agync/tendril/bindings/goimport tendril "github.com/agync/tendril/bindings/go"
host, err := tendril.NewEndpoint("./laptop-state", "laptop")
if err != nil { return err }
addr, err := host.ServeDirect("127.0.0.1:0")
if err != nil { return err }
code, err := host.IssueCode("lan") // show as text or a QR
if err != nil { return err }
req, err := host.PairAccept(5000)
if err != nil { return err }
// after a person compares the check string
if err := host.ConfirmPeer(req.DeviceID, req.SAS); err != nil { return err }
grant, err := host.MintGrant(req.DeviceID, []string{"notes.sync"}, 3600)
if err != nil { return err }
sess, err := host.AcceptSession(5000)
if err != nil { return err }
ok, err := sess.Authorize("notes.sync") // true
.package(url: "https://github.com/agync/tendril", from: "0.1.0")import Foundation
import Tendril
let host = try TendrilEndpoint(stateDir: "./laptop-state", hostId: "laptop")
let addr = try host.serveDirect(listenAddr: "127.0.0.1:0")
let code = try host.issueCode(kind: "lan") // show as text or a QR
let json = Data(try host.pairAccept(timeoutMs: 5000).utf8)
let req = try JSONSerialization.jsonObject(with: json) as! [String: Any]
let device = req["device_id"] as! String
try host.confirmPeer(peerId: device, sas: req["sas"] as? String) // after a person compares the check string
let grant = try host.mintGrant(peerId: device, capsJson: #"["notes.sync"]"#, ttlSecs: 3600)
let session = try host.acceptSession(timeoutMs: 5000)
let ok = try session.authorize("notes.sync") // true
implementation("dev.agync:tendril-android:0.1.0")import dev.tendril.TendrilEndpoint
import org.json.JSONObject
val host = TendrilEndpoint.create(stateDir = "./laptop-state", hostId = "laptop")
val addr = host.serveDirect("127.0.0.1:0")
val code = host.issueCode("lan") // show as text or a QR
val req = JSONObject(host.pairAccept(5000))
val device = req.getString("device_id")
host.confirmPeer(device, req.getString("sas")) // after a person compares the check string
val grant = host.mintGrant(device, """["notes.sync"]""", 3600)
val session = host.acceptSession(5000)
session.authorize("notes.sync") // true
cargo add tendril-runtime tendril-core// tendril-runtime is the async layer the other bindings wrap; it is lower level.
let store = StateStore::open_or_create("./laptop-state")?;
let identity = store.load_or_generate_identity(Some("laptop"))?;
let roster = Mutex::new(store.load_roster()?);
let pairing = Mutex::new(PairingManager::new(PairingConfig::default()));
let router = InboundRouter::new();
let listener = DirectListener::bind("127.0.0.1:0".parse()?, None).await?;
router.spawn_listener(&Handle::current(), Box::new(listener));
let code = pairing.lock().unwrap().issue_code(PairingCodeKind::Lan2Group, now())?;
let (mut stream, guard) = router.recv_pair(wait).await?.ok_or("closed")?;
let kind = pairing_path_kind_for_provider(stream.provider_id());
let res = drive_pair_responder_with_options(stream.as_mut(), &identity, &pairing, &roster,
kind, now(), Some(router.rate_limiter()), Some(guard), DEFAULT_PRE_AUTH_TIMEOUT).await?;
let PairOutcome::ResponderPending { device_id, pairing_sas, .. } = res.outcome else { bail!() };
// after a person compares the check string
roster.lock().unwrap().confirm_peer(&device_id, Some(&pairing_sas))?;
let grant = roster.lock().unwrap().mint_grant(&identity, &device_id,
vec!["notes.sync".into()], now(), now() + 3600, random_bytes::<16>()?)?;
store.save_roster(&roster.lock().unwrap())?;
cargo install tendril-clitendril --state-dir ./laptop-state init --host-id laptop
tendril --state-dir ./laptop-state serve --listen 127.0.0.1:0 --issue-code lan
# on the host, after a person compares the check string
tendril --state-dir ./laptop-state confirm <device_id> --sas "<check string>"
tendril --state-dir ./laptop-state mint <device_id> --cap notes.sync --ttl-secs 3600
Enroll a servermachine to machine, no check string
# on the Mac mini, accept machines and mint one single-use token
tendril --state-dir ./mac-mini-state serve --listen 0.0.0.0:7000 --allow-enroll
tendril --state-dir ./mac-mini-state enroll-token --target-host mac-mini --out ./token.json
# on the NAS, with the Mac mini's keys from init pinned in advance
tendril --state-dir ./nas-state enroll --endpoint 192.168.1.20:7000 --host-id mac-mini \
--host-static-pub "<static_pub>" --host-signing-pub "<signing_pub_hash>" \
--token-file ./token.json
# on the Mac mini, the NAS joined with no grants
tendril --state-dir ./mac-mini-state mint <device_id> --cap backup.write
Events are polled, not called back, so nothing re-enters your event loop. In the browser, Tendril joins as a client through a relay.
What we borrow, and what we own.
The algorithms are standard and used unchanged. The new parts are named, so review effort can go there. There has been no third-party audit yet.
Borrowed, proven elsewhere
- Key exchange
- X25519 and ML-KEM-768 (NIST FIPS 203)
- Signatures
- Ed25519 and ML-DSA-65 (NIST FIPS 204), used together. Both must verify
- Signed bytes
- Canonical JSON (RFC 8785)
- Code proof
- Argon2id: 64 MiB and 3 passes, or 19 MiB and 2 passes in Wire v2 pairing
- Peer-to-peer path
- QUIC and hole punching, via iroh
New, and ours
- Hybrid handshake
Noise_XXhfs_25519+, in our own Noise code. Checked against a separate Go versionMLKEM768_ChaChaPoly_SHA256 - Code proof
- Works only on the connection it was made for
- Confirm, then grant
- Approving a device and granting it anything are separate steps
- Grants
- Default deny. Exact names or a prefix, no patterns
- Revocation
- Signed lists that only move forward, pushed into live sessions
- Wire v2
- An opt-in privacy mode: hourly mailbox keys, padded sizes, and a decoy reply for strangers who probe a host
A relay cannot see
- Your data
- Which grants exist
- Device names
- The pairing code
A relay can see
- IP addresses
- When devices connect, and how much they send
- The key a waiting device uses as its mailbox. By default it never changes, so a relay can link that device's sessions
Wire v2, an opt-in mode, changes the mailbox key every hour, rounds sizes up to fixed steps and varies the timing of keepalives. Addresses, and when devices send, stay visible. What it hides
One core, thin bindings.
Every security decision is made in one Rust core that forbids unsafe code. Bindings translate types and nothing else.
All bindings check the same shared test vectors.
- Rust
- tendril-core, tendril-runtime
- Go
- cgo
- Python
- PyO3
- Node.js
- N-API
- Browser
- WebAssembly
- Swift
- iOS, macOS
- Kotlin
- Android, JNI
Pair two devices on your own machine.
Found a security problem? Report it privately on GitHub.