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.