> ## 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 Tesserc 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. ```mermaid theme={"theme":"css-variables"} flowchart LR subgraph laptop agent --> cli[tesser CLI] browser --> lh[localhost:3000] end subgraph cloud box["box: ~/workspace, dev server, boxd"] box2[other boxes] cp[control plane] end cli -- "ssh, rsync" --> box lh -- "ssh tunnel" --> box cli -- "https: ids, ports, states" --> cp box -- heartbeats --> cp box <-- "private network" --> box2 ``` ## 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 Tesserc to put boxes to sleep and remove them aggressively. ## What runs on a box Each box runs one Tesserc 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 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 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-.localhost:` reaches any box, and bare `localhost:` 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 Apart from the warm pool, 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 hibernated, keeping its disk, its id, and its memory. Anything that targets it afterwards wakes it first, which takes about a minute, and its dev server carries on where it stopped. A box that cannot hibernate is powered down instead, and its dev server is started again when it wakes. 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. The warm pool is the one thing the control plane launches by itself. After `tesser pool target` sets a count for a size, it keeps that many unclaimed boxes of that size ready for any repo in the org, launches a replacement when one is claimed or dies, and lets the pool lapse once nobody has created a box it could serve for an hour. A pool box runs no service until someone claims it. ## Shared 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 laptop has one SSH key pair, `~/.config/tesser/id_ed25519`, which it uses for every box, 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](https://tesser.sh/docs/where-your-code-goes.md) 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), port 14650 between the org's own boxes for dependency forwarding, 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](https://tesser.sh/docs/self-hosting.md) 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 Tesserc. ## What Tesserc does not do There is no reconciler that restarts a server, 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.