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

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

```text theme={null}
.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:

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

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

## Every field

```toml theme={null}
# .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.