Skip to main content
Your worktree moves from your laptop to a box over SSH and nowhere else. The control plane at api.tesser.sh receives ids, ports, and states. It never receives a file, a diff, terminal output, or your app’s traffic. For an org that runs its boxes in its own AWS account, the code exists in two places: your laptops and your account.

​
Every hop

The control plane has no upload endpoint. A box’s only channel to it is a WebSocket whose upward messages are hello, heartbeat, and a short list of events, none of which carries a file.

​
The SSH connection

Each box gets its own ed25519 key pair, generated with ssh-keygen on the laptop that created the box and stored under ~/.local/state/tesser/boxes/<box_id>/. The private half never leaves that directory. The public half goes to the control plane once, which forwards it to boxd over the box’s WebSocket, and boxd appends it to ~/.ssh/authorized_keys. sshd on the box accepts nothing else: no password, no cloud-init key, no key from another laptop. This is why a teammate cannot open your dev box. Every ssh and rsync the CLI runs uses IdentitiesOnly=yes with that key, BatchMode=yes so an agent never hits a prompt, and a per-box known_hosts file with StrictHostKeyChecking=accept-new: the first connection records the box’s host key and every later one must match it. Nothing touches your ~/.ssh. Through Session Manager the host key is filed under the instance id instead of an IP.

​
What sync sends

sync, exec, and dev ship the files git would: tracked files plus untracked files that are not ignored, as one explicit file list to rsync. Ignored paths such as node_modules, .env.local, and build output stay on the laptop unless the manifest’s env.files names them. Removals are exact paths from the previous list rather than --delete, so the box’s own build state survives. The box’s .git comes from a shadow repository the CLI keeps on the laptop, holding only the current HEAD commit and the branch name. The box never fetches from GitHub and has no git credential. A pinned instance works the same way. tesser make api --ensure-running <sha> checks that commit out of your clone into a directory on the laptop and rsyncs it to the box. The control plane is told the sha, not the commit.

​
What the control plane receives

  • Box metadata. Ids, class, service name, size, owner, power state, IP addresses, and the commit sha of a pinned instance.
  • Service manifests. The TOML text of each manifest, which holds ports and the setup and dev commands and is committed to your repository.
  • Your public key, on the way to the box.
  • boxd heartbeats. Whether the dev server is running, its pid, exit code, which ports are listening, and whether the health check passes.
  • Crash snapshots. When a dev server exits, boxd sends the last 40 lines of its output with the exit event so tesser dev can say why. This is the one place program output reaches the control plane. tesser logs reads the log file over SSH.
  • Routing tables and wires. Which box each dependency port points at.
  • Values set with tesser env set for pinned instances, stored in the org and injected when the instance starts. Env files pushed to a dev box go over SSH and are not among them.
  • Usage. Awake seconds per box.
  • API token hashes.
Not on the list: file contents, diffs, commits, the output of exec, ssh, or logs, HTTP traffic to a dev server, and the contents of any env file that was pushed or synced.

​
On the box

The worktree lives at ~/workspace and the dev server’s output at ~/.tesser/dev.log. boxd acts only when told to: start or stop the dev server, rewrite its routing table, add an authorized key, warm package caches from a sibling box, and update itself. It has no message for reading a file. The root volume is EBS encrypted. The box’s credential for the control plane arrives in cloud-init, and the control plane turns off the instance metadata endpoint as soon as boxd first connects, so nothing on the box can read it back afterwards. The boxes of one org sit in a security group that admits port 22 and traffic from the group itself, and nothing from another org. Box-to-box traffic stays on private VPC addresses.

​
In your own AWS account

For a connected org, the instances, the disks, the code, the logs, and the box-to-box traffic are all in your account, and Tesser reaches it with a short-lived OIDC token rather than a stored credential. Boxes launch from Tesser’s public image so that boxd is present. With --private the CLI reaches boxes at their private IP over your VPN. With --ssm there is no inbound port: the SSH stream, still encrypted end to end between your laptop and sshd, rides inside a Session Manager session.