Skip to main content
This guide takes one repository from nothing to a dev server running on a box and showing at localhost:3000, which takes about ten minutes.

​
1. Install

The script puts the tesser binary in ~/.tesser/bin and adds that directory to your PATH. Open a new terminal and confirm it is installed:
Running the same install line again upgrades the binary in place. To install a specific version instead of the latest:
Install and update covers the release API and pinning a release by hash in CI.

​
2. Sign in

This opens tesser.sh in your browser. Sign in or create an account, choose an org or create one, and approve the CLI. The CLI receives a token and saves it in the login keychain on macOS, or in ~/.config/tesser/credentials.json elsewhere. There is no other configuration to do. Over ssh, or with tesser login --ssh, the CLI prints the URL instead. Open it in any browser, approve, and paste the code the page shows back into the terminal.

​
3. Run a command on a box

From inside a git repository, run:
The first time you run this, Tesser creates a box for the worktree, which takes about 90 seconds. After that a box is ready in a few seconds. Tesser copies your worktree to the box, runs the command inside the copy, streams the output back to your terminal, and exits with the command’s exit code. Now try it with your project:
This box is the worktree’s workbench. It keeps everything between runs, so node_modules, build caches, and anything else you install are still there the next time.

​
4. Run a dev server

Tesser needs to know how to run your app. You describe each service in a small TOML file named after the service:
Then start it:
This creates a second box for the service, syncs the worktree to it, runs the setup command, starts the dev command, waits until port 3000 answers, and prints the box id. Open http://localhost:3000 to see the dev server. The first tesser dev also starts tesserd, a small proxy on your laptop that gives every box an address (http://<box_id>.localhost:<port>) and serves the box you have focused on bare localhost:<port>. It stays up on its own; tesser daemon install brings it back after a reboot, and --port 3300 moves its own panel if something else has 3000. Box addresses keep their ports either way. When you edit a file locally, push the change with:
The dev server’s hot reload picks up the change in the browser. You only need sync when you have changed files and nothing else, because exec and dev sync before they run. If you changed something the running server cannot pick up on its own, such as an env file or a dependency, use tesser sync <box_id> --restart, which syncs and then starts the server again.
If your app reads a gitignored file such as .env.local, that file is not copied to the box, because sync follows .gitignore. Add [env] files = [".env.local"] to the manifest and every sync will include it. See Services.

​
5. Leave it

You do not need to shut anything down. The workbench goes to sleep after 10 minutes without activity and the dev box after 2 hours. A sleeping box costs a few cents a day and wakes in about 40 seconds the next time a command targets it, with everything still installed. A box that has been asleep for 16 hours is removed. When you are finished with a worktree, tesser rm <box_id> removes its box permanently. tesser ls lists every box you have.

​
Next

To let your agent run these commands for you, read Let your agent drive the boxes. To see two branches side by side in the browser, read localhost. If your app depends on another service, such as a backend or a database, read Connect a frontend to a backend.