> ## 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.

# Quickstart

> Install the CLI, sign in, run a command on a box, then run a dev server

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

```sh theme={"theme":"css-variables"}
curl -fsSL https://tesser.sh/install | sh
```

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:

```sh theme={"theme":"css-variables"}
tesser version
```

Running the same install line again upgrades the binary in place. To install
a specific version instead of the latest:

```sh theme={"theme":"css-variables"}
curl -fsSL https://tesser.sh/install | sh -s -- v0.2.5
```

## 2. Sign in

```sh theme={"theme":"css-variables"}
tesser login
```

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

```sh theme={"theme":"css-variables"}
tesser 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:

```sh theme={"theme":"css-variables"}
tesser exec -- uname -a
```

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:

```sh theme={"theme":"css-variables"}
tesser exec -- pnpm install
tesser exec -- pnpm test
```

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:

```toml theme={"theme":"css-variables"}
# .claude/skills/tesser/web.toml
ports = [3000]

[run]
setup = "pnpm install"
dev   = "pnpm dev"
```

Then start it:

```sh theme={"theme":"css-variables"}
tesser dev web
```

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](http://localhost:3000) to see the dev server.

When you edit a file locally, push the change with:

```sh theme={"theme":"css-variables"}
tesser sync <box_id>
```

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.

<Note>
  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](/docs/services#env-files).
</Note>

## 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](/docs/agents). To see two branches side by side in the
browser, read [localhost:3000](/docs/localhost). If your app depends on another
service, such as a backend or a database, read
[Wiring services together](/docs/wiring).