tendril v0.1

Use cases

Where Tendril fits

Tendril is for apps that link devices one person or one team already owns, where an account or a cloud server would add cost and risk but nothing else. Here are four such apps, most common first, and the jobs where something else fits better.

Each case starts with a moment, then the problem and what changes. Open The details for the mechanism and the limits.

01Mac mini and phone

Reach your desktop app from your phone

You are out, and the agent at home needs a yes.

The problem. A coding agent on the Mac mini stops to ask before it acts, and you have only your phone. The usual fixes are an open port, a VPN, or a cloud dashboard that sees your code.

With Tendril. The app on the Mac mini pairs with your phone once: scan a code, compare a check string. After that the phone reaches the Mac mini directly at home, or through hole punching or a relay when away, and it can do only what you granted.

Grantsigned by Mac mini

For
your phone
May
agent.status
agent.approve
logs.read:/builds/*
Until
30 days from now
The phone asks, the Mac mini checks
RequestResult
agent.approveallow
logs.read:/builds/142.logallow
shell.execdeny not granted
logs.read:/etc/hostsdeny outside /builds/
Anything, once you revoke the phonedeny revoked
Illustrative. Your app names its own grants.

For the person using it

  • No account to make and no port to open.
  • The phone can approve and read logs. It can never run a shell.
  • Phone lost? Revoke it on the Mac mini.

For you, building it

  • No sign-in server to run, and no user data on your servers.
  • Pairing, keys, grants and revocation come from one library.
  • You draw the screens. Tendril supplies the code, the check string and the result.
The details

Paths. On the same network the phone can use the direct path. Away from home it can use the p2p path, hole punching through iroh, or a relay that forwards sealed frames it cannot read. In Rust, dial_with_policy tries the paths nearest first and keeps the first one that proves the Mac mini. The other bindings and the CLI dial the one address you give them today.

Changing networks. Reconnecting is up to your app. When the phone leaves Wi-Fi, the app dials again, the devices run a new handshake on another path, and the pairing and grants carry over. Phones suspend background sockets while asleep, so the phone reaches the Mac mini again when it wakes.

A phone asleep. With Wire v2, the Mac mini can send a sleeping phone a wake hint through a push service, such as FCM or an APNs gateway, then dial it once it is back. The hint carries a tag that changes every hour, and no data.

Checks. The Mac mini checks the grant when a session opens, on every rekey and on every authorize call. Plain checks treat a resource as an opaque string. For file paths, the Rust core's authorize_path cleans the path first and matches only at / boundaries.

Revoking. Once the Mac mini marks the phone revoked, its next request is denied, even in a session that is already open, and it cannot open a new one.

02laptop, phone and a browser tab

Keep your own devices in sync, with no account

You write a note on the laptop and want it on your phone, with no sign-up.

The problem. Most notes apps sync through sign-in, a database and cloud storage, and end up holding every user's notes.

With Tendril. The laptop and the phone pair once and sync with each other. On home Wi-Fi they connect directly, with no internet needed. A browser tab on a work computer can join through a relay, with a grant that ends the same evening.

laptop host · keeps the notes phone home Wi-Fi browser tab work computer direct notes.sync relay notes.read ends in 8 hours
Illustrative. Grant names and times are examples.

For the person using it

  • Notes stay on their own devices.
  • Sync works on a home network with no internet.
  • The browser's access ends on its own.

For you, building it

  • No accounts, password resets or user database.
  • No copy of anyone's notes to secure or hand over.
  • The browser needs a relay, and the relay cannot read what it carries.
The details

No internet needed. A pairing QR code carries the laptop's key and its address on the local network, so the phone can pair and connect over the direct path with no outside server.

The browser. A browser joins only as a client, over WebSockets, through a Tendril relay or, with the opt-in p2p build, an iroh relay. It cannot open UDP sockets, so it cannot hole punch, or hold a connection while the browser suspends the tab. Pairing across the internet uses the long code, TND-XXXX-XXXX-XXXX, with 12 random characters. By default, hosts reject the short form on remote paths.

Grants that end. The host sets a lifetime each time it grants something. In Python, for example, host.mint_grant(tab, ["notes.read"], ttl_secs=28800) grants reading for 8 hours.

Merging edits. Tendril carries the bytes and checks the grant. Merging notes edited on two devices is a job for a sync library such as Automerge or Yjs, run over the session in chunks of at most 65,499 bytes, with no second network stack.

What a relay sees. IP addresses, when devices connect and how much they send, and the waiting device's mailbox key. By default that key never changes, so a relay can link that device's sessions. With Wire v2 it changes every hour. A relay cannot see the notes, the grants or the pairing code.

03NAS and phone

Appliances that do not need the maker's cloud

You are away and want the photos on your NAS, not a copy in the maker's cloud.

The problem. A home NAS or camera usually reaches its owner through the maker's cloud. Every byte passes through the maker, often for a monthly fee, and if the service shuts down the box stops working away from home.

With Tendril. The box and the owner's phone pair at setup. At home they talk directly. Away, the maker runs at most a relay, which passes sealed frames it cannot read, and owners can move to another relay without pairing again.

NAS at home phone away maker's relay shut down your relay in use same pairing, same grants either relay passes sealed frames it cannot read
Illustrative. At home, the two talk directly and no relay is used.

For the person using it

  • The maker never holds the files.
  • The box keeps working if the maker's service closes.
  • A friend can get photos.read:/albums/trip/* for a week. It ends on its own.

For you, building it

  • No accounts to run.
  • Your relay can admit only your own devices, and carries sealed traffic only when nothing direct gets through.
  • The Rust core runs on the box, the Swift and Kotlin bindings on the phones.
The details

Pairing needs a screen. The host shows the code and the check string, so pairing by eye fits a box with a small display. A machine with no screen enrolls with a token instead, as in case 04.

Moving relays. Moving from one relay to another changes only the relay address each device keeps on its roster. Keys, pairing and grants stay as they are. A relay can be public, one you run, or one embedded in your app, all on the same protocol.

Who may use the relay. The maker can run tendril-relay so that it admits only its own devices, with a shared secret or with short-lived tickets it signs. With admission on, the relay checks a device before it says whether a mailbox is online. An owner who moves to their own relay sets their own rule.

Peer-to-peer. The p2p path uses iroh, which by default finds peers through the free public relay and discovery servers run by n0. You can point it at an iroh relay you run or a hosted one, pass it a token, or turn discovery off.

Guests. The box grants a friend's phone one album with an end time, after the friend's phone has paired with it. Revoking the friend's phone ends it sooner.

04server and CI runner

Let machines with no screen join, one job at a time

You push a fix, and the deploy needs the server for ten minutes, not a key for months.

The problem. Reaching a production server from CI usually means an SSH key or an API secret stored there, valid for months, and useful to anyone who copies it from a log.

With Tendril. The server trusts your CI's signing key. Each job gets a token that works once and expires in 15 minutes. The runner enrolls with it, joins with no grants, and the server grants it one thing for the length of the deploy.

One deploy job

  1. CI signs a token

    pair.enroll:prod-1

    single use · 15 min

  2. The runner enrolls

    active · 0 grants

    after checking the server's pinned keys

  3. The server grants one thing

    deploy.push:/srv/app/*

    10 min

Illustrative. Names and times are examples.

For the people running it

  • No long-lived deploy key on the server.
  • A token copied from a log is useless once used.
  • One command stops every token a CI key signed.

For you, building it

  • The same roster, grants and revocation as the phone cases.
  • Enrollment works from the CLI and from every binding.
  • Off until the server's owner turns it on.
The details

Trusting the CI. The server registers the CI's signing key as a trust anchor with tendril anchor add and accepts machines with tendril serve --allow-enroll. tendril anchor revoke stops every token that key signed.

The enrollment token. A signed grant for one use that may hold only pair.enroll or pair.enroll:<host_id>. It lasts 900 seconds by default. The CLI host accepts tokens of up to 900 seconds, as do the hosts in the language bindings. The CLI reads the token from a file, standard input or TENDRIL_ENROLL_TOKEN, never from the command line.

Pinning. The runner must hold the server's id and keys in advance. If another host answers, the runner stops before it says anything about itself.

The burn log. The server records the token and saves it before it replies, so a second use fails with token_replayed. The runner joins active with zero grants, and the deploy grant comes from pair.mint, as for any device. A token can never open a session.

Mixed languages? A desktop app in Go, phone apps in Swift and Kotlin, a script in Python: each binding wraps the same Rust core and checks the same test vectors, so pairing and grants behave the same in all of them.

05

When something else fits better

Tendril links two devices that each prove who they are. Some jobs have a different shape.

A public website or API
HTTPS, often behind a CDN
The server is meant to read every request, from anyone.
A group chat with many members
MLS, Messaging Layer Security
Tendril links are between two devices. Group encryption is out of scope for v1.
Hiding who talks to whom
Tor or a mixnet
Relays and networks still see addresses, timing and sizes. Tendril is not an anonymity network.

Need only a connection, with your own pairing and permissions? Use iroh directly.

Go deeper