> ## Documentation Index > Fetch the complete documentation index at: https://tesser.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # How it works > What runs on the laptop, what runs on the box, and what the control plane does Tesser has three parts: your laptop, which holds the code, the agent, and the browser; the boxes in the cloud, which hold the running software; and a small control plane, which keeps track of which boxes exist, how their dependencies are routed, and which boxes should be asleep. Files and terminal output move directly between the laptop and the box over SSH, and the control plane never sees them. ```text theme={"theme":"css-variables"} laptop cloud ────── ───── agent ──▶ tesser CLI ──── ssh, rsync ──▶ box: ~/workspace, dev server, boxd browser ──▶ localhost:3000 ── tunnel ──▶ box: the port the service listens on │ boxes reach each other over a private network └──── https ──▶ control plane ◀── heartbeats ── every box who exists, what routes where, what sleeps ``` ## 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's `setup` 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, and tracks activity so the box can be put to sleep when it is really idle. It does not restart a crashed server on its own. A crash is recorded, and running `tesser 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 says `5001 = "api"`, and never says where `api` is. Each box has its own small routing table, made of the org's defaults (the pinned instance of each service) with the box owner's overrides applied on top (the automatic wiring between a worktree's own boxes, plus anything set with `tesser override`). 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. Pinned instances belong to the org rather than to a person, and they cannot carry overrides at all. As a result, the shared copy of `main` 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. `localhost:3000` is the selected box, the selected box's dependency ports are mirrored locally, and `.localhost:` reaches any box directly. 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. ## Pinned instances `tesser make api --ensure-running ` 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. The boxes of one org sit in their own security group, which allows port 22 from anywhere (sshd accepts only the per-box key), any traffic between the org's own boxes, and nothing from another org. The control plane authenticates every call with a per-org API token. Secret values for pinned instances are held by the control plane and injected when the instance starts. The complete list of secrets in the system is therefore the per-box keys, those env values, and your token. ## What Tesser does not do There is no reconciler that restarts things, no per-request routing or identity header, no overlay network, no git credential on any box, and no option to run the agent inside the box. Each of these would make the system larger than it needs to be, and a reconciler in particular would cost money indefinitely the first time it had a bug.