The laptop holds the only copy that matters
Every command that touches a box begins by copying your worktree to it with rsync, transferring only the files that changed. The box’s copy is overwritten and never merged back, which is why editing files on the box has no lasting effect, and why removing a box cannot lose anything important: the source is on your laptop, and anything that was installed on the box can be installed again by the manifest’ssetup command. This is what makes it safe
for Tesser to put boxes to sleep and remove them aggressively.
What runs on a box
Each box runs one Tesser process, called boxd, alongside your software. boxd starts the dev server and writes its output to a log file, forwards the dependency ports to wherever the routing table says they should go, reports to the control plane that the box is alive and which ports are listening. It does not restart a crashed server on its own. A crash is recorded, and runningtesser dev again is how you recover, so that every running process can be
traced back to someone who started it.
A workbench is the same kind of machine without a server on it. The
difference is in how the box is used, not in how it is built.
Names rather than addresses
A manifest says5001 = "api", and never says where api is. Each box has
its own small routing table, made of the shared instances (one per
service) with the box owner’s wires applied on top (set with
tesser wire — nothing is ever wired automatically). boxd
listens on the dependency ports and forwards
connections through the org’s private network to the right box. The
application sees a loopback port and does not need an SDK, an environment
variable convention, or DNS.
Shared instances belong to the org rather than to a person, and they cannot
carry wires at all. As a result, the shared instance resolves the
same way for everyone and can never end up connecting to someone’s
in-progress branch.
The laptop participates in the same way. <box_id>.localhost:<port> reaches
any box, and bare localhost:<port> is the box you have focused that has
that port: its own ports, and its dependency ports mirrored locally, so the
browser sees what that box sees, while ports it does not have stay where
they were. Browsers resolve *.localhost to the local machine, so none
of this requires installing anything.
Sleep
The only automated behaviour in the control plane is turning things off. A workbench that has been idle for 10 minutes, or an instance box idle for 2 hours, is powered down, keeping its disk and its id. Anything that targets it afterwards wakes it first, which takes about 40 seconds, and its dev server is started again. A box that has been asleep for 16 hours is removed. Nothing in the cloud starts a named service on its own; every dev server can be traced to a person, an agent, or a CI job that ran a command.Shared instances
tesser make api --ensure-running <sha> checks out one commit on a box, runs
setup and dev, waits for the health check, and points the org’s api at
that box. A new commit starts a new box beside the old one, switches the org
over once the new box is healthy, and removes the old one. Boxes never fetch
from GitHub: the laptop or CI job that runs the command already has the
repository and pushes the commit up, so no git credentials exist on any box.
Security
Each box has its own SSH key pair, generated on the laptop that created it, and the private key never leaves that laptop. Sync,exec, logs, and the
browser tunnels are SSH connections from the laptop to the box. The control
plane receives ids, ports, and states, and authenticates every call with a
per-org API token. Where your code goes lists every
hop and everything the control plane receives.
The boxes of one org sit in their own security group, which allows port 22
from anywhere (sshd accepts only the keys the control plane placed), any traffic between the
org’s own boxes, and nothing from another org. Secret values for shared
instances are held by the control plane and injected when the instance
starts. The complete list of secrets in the system is therefore each
laptop’s key, those env values, and your token.
An org that runs its boxes in its own AWS account adds no
secret to that list, and its boxes have no port 22 at all: laptops reach
them through AWS Session Manager. The control plane reaches the account by presenting a
short-lived OIDC token to an IAM role whose trust policy names that one org,
so there is no key for the account anywhere in Tesser.