Quickstart

From a repo to a running mesh

One service

Declare it, run it, open it:

# .claude/skills/tesser/frontend.toml
ports = [3000]

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

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:

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

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:

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:

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:

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.