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:

​
2. Sign in

This opens tesser.sh in your browser. Sign in or create an account, choose an org or create one (a personal org is fine), and approve the CLI. The CLI receives a token and saves it in ~/.config/tesser/credentials.json. There is no other configuration to do.

​
3. Start the daemon

Leave this running in its own terminal. The daemon serves localhost:3000, which is where your browser will see whichever box you have selected. If another program already uses port 3000, start it with tesser daemon --port 3300 instead.

​
4. 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.

​
5. 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. 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.

​
6. 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 Working with an agent. To see two branches side by side in the browser, read localhost:3000. If your app depends on another service, such as a backend or a database, read Wiring services together.