Skip to main content
There is no configuration file to edit. tesser login writes the one credential the CLI needs, and everything else is controlled by command-line flags or environment variables.

Environment variables

Files on the laptop

Nothing is installed system-wide, and nothing requires root.

Ports on the laptop

The daemon answers requests from your own machine and from Tailscale peers. It refuses the rest of the LAN unless it is started with --allow-lan. A port a dev run opens without declaring it answers only your own machine (see The daemon).

Timers

The box

Each box is a standard size (2 vCPU, 8 GB of memory) unless --size or the manifest picks small (1 vCPU, 4 GB), large (4 vCPU, 16 GB), or xlarge (8 vCPU, 32 GB), with a 40 GB gp3 disk at the gp3 default throughput of 125 MiB/s, running Ubuntu 24.04 on its LTS kernel (6.8) with Node (22 and 24, via fnm), Bun, uv, mise, rsync, and Docker (with compose and buildx) installed. Use uv for Python and mise for Ruby. mise reads your repo’s .ruby-version and installs only precompiled Ruby builds (ruby.compile = false), so mise install in your worktree gets the Ruby your repo pins without compiling it. mise trusts every mise config under /home/ubuntu, and its shims are on the PATH of every box command and ssh session, so ruby and bundle work without a prompt. Your worktree is at ~/workspace and the dev server’s output is written to ~/.tesser/dev.log. Commands run as the ubuntu user, which has passwordless sudo and is in the docker group. Docker pulls Docker Hub images from Google’s mirror, mirror.gcr.io, and falls back to Docker Hub when the mirror cannot serve an image. The mirror exists because Docker Hub limits anonymous pulls per IP address, and every box behind one address shares that limit, including all the boxes on one fleet host. Images from other registries, such as ghcr.io or ECR, come straight from that registry. A buildx builder on the docker-container driver does not use the mirror. The disk’s speed depends on where the box runs. An EC2 box’s disk is gp3 at the gp3 default throughput of 125 MiB/s. A microVM’s disk reads and writes at up to 60 MiB/s and 1,000 IOPS per vCPU, counting at most 4 vCPUs, so a large or xlarge box gets 240 MiB/s and 4,000 IOPS. The setup and dev commands, snapshot builds, tesser exec, and a command line given to tesser ssh run on the Node version your repo pins. The box looks for .nvmrc, .node-version, or engines.node in package.json, starting in the command’s working directory and walking up, and the nearest pin wins. A service’s commands start in its directory, and tesser exec without --in starts at the repo root. When the pinned version is not installed yet, the box installs it once and prints tesser: installing the node that <dir> pins; the version stays installed while the box sleeps. The box also installs the pinned version in the background for each service’s working directory, one directory at a time, when it starts and again after a pool box is claimed. A dev run whose directory is still being installed waits for that install and first writes tesser: waiting for boxd to install the node that <dir> pins to its log. While it waits, the run reports as running in its setup phase, or its dev phase when the service has no setup. When the run’s pin no longer matches what the background install read, the run does not wait and installs its own version. When there is no pin, the pin names the box’s default Node version, or the pin cannot be installed, the command does not fail and runs on the first node on its PATH. The box puts /usr/local/bin ahead of its default Node, so a node your setup installs into /usr/local/bin wins; otherwise the command runs on the box’s default Node. After a failed install the box waits an hour before it tries that download again; a failed background install does not start that wait. The dev log opens with a tesser: node <version> (<path>) line naming the version it used and where that node lives. The interactive shell that tesser ssh <box_id> opens does not use this lookup. The same commands get a Node heap limit sized to the box. The box adds --max-old-space-size set to three quarters of the box’s memory, in MB, to NODE_OPTIONS, so a large tsc or eslint run can use most of the box instead of Node’s default limit of about a quarter of memory. A NODE_OPTIONS that does not set a heap limit keeps its other options, and the box appends the limit to it. When an env.load file sets a NODE_OPTIONS that already has --max-old-space-size, the box leaves it as it is. A NODE_OPTIONS set inline in the command or in run.dev, such as NODE_OPTIONS=--max-old-space-size=4096 pnpm dev, replaces the box’s value. The run command sees these variables from Tesser: TESSER_BOX_URL sits under anything you set with tesser env set; the other three are fixed per run. A command run with tesser exec, or a command line given to tesser ssh, sees the same variables, with two differences. TESSER_BOX_URL is set only on a service box that one of this laptop’s worktrees started. TESSER_SLOT is set on a shared instance and on a dev box that one of this laptop’s worktrees started, and left out otherwise. The interactive shell that tesser ssh <box_id> opens gets none of them. A service’s setup also runs on the snapshot builder, and the repo’s new boxes start from the disk it leaves behind (unless you pass --no-snapshot). On the builder, setup sees none of these variables. Anything specific to one box, such as its address, its id, or a per-box secret, belongs in dev and never in setup.