Manifests

One TOML file of facts per service

A repo declares its services with one TOML file each, in the tesser skill directory. The filename is the service name:

.claude/skills/tesser/
├── SKILL.md          ← agent-facing workflow guidance
├── frontend.toml     ← service "frontend"
└── backend.toml      ← service "backend"

Service names are org-global. Registering a name another repo already owns fails loudly at registration — a dep reference like "worker" always means exactly one thing across the org.

Manifests declare facts only — where the code lives, what it listens on, how to set it up and run it, how to know it’s healthy, what it needs. Judgments (when to restart, when to test, what else to install) belong to callers, expressed through CLI verbs like sync --restart and exec.

The minimal manifest

Most services need three lines:

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

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

Every field

# .claude/skills/tesser/backend.toml   (service name = filename)

root  = "apps/backend"      # cwd for all recipes, relative to repo root
ports = [8080, 9090]        # loopback ports the service listens on; first = primary

[run]
setup = "pnpm install"      # idempotent; runs at box birth, ensure-running, dev attach
dev   = "pnpm dev"          # the run recipe — dev and pinned instances alike

[health]
path    = "/healthz"        # probed on the primary port
timeout = "90s"             # readiness deadline (dev start and blue/green rollover)

[deps]                      # loopback bindings on this service's box
5001 = "worker"             # localhost:5001 → worker's primary port
5432 = "db"                 # raw TCP — protocol-agnostic
9091 = "search:9090"        # a specific non-primary port of a dep

[env]
files    = [".env.local"]   # gitignored files sync ships anyway (dev instances)
required = ["API_KEY"]      # names only — values live in the control plane

Field	Default	Meaning
root	"."	Working directory for every recipe, relative to the repo root. Monorepo services point at their package; workspace-aware tools (pnpm) resolve upward from there.
ports	required	Loopback ports the service binds. The first is primary: it’s what a bare dep binding reaches and what the health check probes. Services bind loopback only; boxd exposes declared ports on the private network.
run.setup	required	Idempotent environment recipe. Runs at box birth, on ensure-running, and at dev attach — caller-triggered moments, never a background reconciler.
run.dev	required	The run recipe. Dev instances run it against the synced worktree; pinned instances run it against an immutable checkout.
health.path	TCP-listen check	HTTP path that must return 2xx on the primary port for the instance to count as up. Without it, “something listens on the primary port” is the readiness signal.
health.timeout	"90s"	How long dev and rollovers wait for readiness before failing loudly (with the last log lines).
[deps]	{}	localPort = "service" or "service:port". Each key becomes a loopback port on this service’s box (and on the laptop while this service is viewed) that reaches the named dep through the mesh. Deps drive ensure-on-use (starting this service ensures its deps first) and cohort auto-wiring.
env.files	[]	Gitignored files that sync ships to dev instances anyway.
env.required	[]	Env var names this service needs. Values are set per-service in the control plane (tesser env set); ensure-running fails loudly if any are unset. Values never appear in the manifest — it’s committed.

Validation rules

• A manifest’s own ports and its [deps] keys share the box’s loopback namespace — collisions are an error at dev/ensure-running time.
• A repo with multiple manifests requires the service to be named in make/dev invocations; with one manifest it’s the default. Ambiguity is a loud error listing the options, never a guess.
• Secret values in a manifest are rejected: [env] carries names and file allowlists only.

What is deliberately not here

• No addresses, hosts, or wiring — deps are names; resolution is the mesh’s job, per box, at runtime.
• No behavior flags — restart policy, test commands, and install judgment calls live in CLI verbs, driven by the agent.
• No instance or fleet concerns — machine sizing, TTLs, and routing live in control-plane policy, not in the repo.