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

# Get a dev server running on a box

> 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.51.0
```

[Install and update](https://tesser.sh/docs/install.md) covers the release API and pinning a release by
hash in CI.

## 2. Sign in

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

This opens tesser.sh in your browser. Sign in, 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 --no-browser`, the CLI prints a link instead
of opening a browser. Open the link in any browser, on any machine, and
approve. The CLI waits for the approval and finishes on its own; the link
works for 10 minutes.

When a coding agent such as Claude Code or Codex runs `tesser login`, the CLI
prints the link and exits. The agent sends you the link, and after you approve
it, the agent runs `tesser login --wait` to collect the token. See
[Let your agent drive the boxes](https://tesser.sh/docs/agents.md#signing-in).

## 3. 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, Tesserc creates a box for the worktree, which
takes about 90 seconds. After that a box is ready in a few seconds. Tesserc
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.

## 4. Run a dev server

Tesserc 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/devboxes/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.

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:

```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](https://tesser.sh/docs/services.md#env-files).

## 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 a minute 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](https://tesser.sh/docs/agents.md). To see two branches side by side in the
browser, read [localhost](https://tesser.sh/docs/localhost.md). If your app depends on another
service, such as a backend or a database, read
[Connect a frontend to a backend](https://tesser.sh/docs/wiring.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.