> ## Documentation Index
> Fetch the complete documentation index at: https://tesser.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From a repo to a running mesh

## One service

Declare it, run it, open it:

```toml theme={null}
# .claude/skills/tesser/frontend.toml
ports = [3000]

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

```sh theme={null}
BOX=$(tesser dev frontend)     # box + sync + setup + dev server, prints box_…
open http://localhost:3000     # the selected viewport target
```

Edit files locally; `tesser sync $BOX` ships the delta and HMR picks it up
(`exec` and `dev` sync implicitly). If you changed something the server
can't hot-absorb — env, config, deps — `tesser sync $BOX --restart`.

## A mesh

Say the architecture is `frontend → backend → worker`. Each service gets a
manifest; deps are the loopback ports the app already uses:

```toml theme={null}
# .claude/skills/tesser/backend.toml
ports = [8080]

[run]
setup = "pnpm install"
dev   = "pnpm dev:backend"

[deps]
5002 = "worker"        # backend's code calls localhost:5002 — unchanged
```

Pin the shared instances once (usually CI does this on every push to main):

```sh theme={null}
tesser make worker  --ensure-running $(git rev-parse origin/main)
tesser make backend --ensure-running $(git rev-parse origin/main)
```

Now work on `backend` in a worktree:

```sh theme={null}
tesser dev backend      # your backend, wired: its worker dep resolves to
                        # the pinned main worker automatically (ensure-on-use
                        # starts or wakes it if needed)
tesser dev frontend     # a cohort sibling — auto-wired to YOUR backend,
                        # because same worktree
open http://localhost:3000
```

Nobody configured a URL. The frontend's `localhost:5001` reaches *your*
backend; your backend's `localhost:5002` reaches the shared worker; the
shared mesh never routes into your dev instances. Switch what any box's
deps point at — or what `localhost:3000` shows — from the panel injected
into every proxied page.

Every box is also directly addressable, no selection involved:

```text theme={null}
http://<box_id>.localhost:3000
```

## Tests and heavy commands

Never on a serving box. `exec` without a box ID targets the worktree's
**workbench** — a synced box with nothing running on it, claimed from the
warm pool on first use:

```sh theme={null}
tesser exec -- pnpm test
tesser exec --in backend -- tsc --noEmit
tesser exec --deps-of backend -- pnpm test:integration   # dep ports wired
```

## Walking away

Do nothing. Idle boxes sleep (workbenches after 10 minutes, instance boxes
after 2 hours) at \~cents/day; boxes asleep 16 hours are removed. Any
command targeting a sleeping box wakes it in \~40 seconds with caches warm.
`tesser rm $BOX` when a worktree is done; `tesser ls` when you've lost
track.