Architecture

​

The whole system in one diagram

┌─ laptop ───────────────────────────────────────────┐
│ coding agent ──▶ tesser CLI                        │
│ tesserd: viewport proxy (<boxid>.localhost:port,   │
│          localhost:3000), tunnels, dep bindings,   │
│          switcher panel                            │
│ authoritative: worktrees, SSH keys, viewport       │
└────────┬──────────────────────────────┬────────────┘
         │ SSH + rsync (data plane)     │ token'd HTTPS/WS (control)
         ▼                              ▼
┌─ VPC (public subnet, public IPs) ─────┐   ┌─ control plane (cells) ──────┐
│                                       │   │ org cell: service registry,  │
│                                       │   │   alias defaults, warm pool, │
│  box ── private IPs (mesh) ── box     │   │   policy, tokens             │
│  ┌─────────────────────────┐          │   │ box cell (per box):          │
│  │ boxd: supervisor, mesh  │◀── WS ───┼──▶│   lifecycle state machine,   │
│  │ ports, activity clock,  │ presence │   │   overrides, derived routing │
│  │ presence, health        │ + tables │   │   table, reaper timers       │
│  │ service on loopback     │          │   │                              │
│  │ workspace (rsync mirror)│          │   │ Cloudflare Workers today;    │
│  └─────────────────────────┘          │   │ celld fleet for BYOC — same  │
└───────────────────────────────────────┘   │ bundle (compat subset)       │
                                            └──────────────────────────────┘

• Data plane — SSH and rsync to box public IPs, VPC private IPs between boxes. Every byte of sync, exec, logs, and mesh traffic. Boring on purpose; survives control-plane death entirely.
• Control plane — cells. Decisions only: who exists, what routes where, what sleeps when. Never carries data.
• Viewport — the laptop’s browser window into the system, owned by tesserd.

​

Boxes and instances

• Instance box — born as (content source × service), runs exactly one service instance. One instance per box, always: this keeps ports collision-free, boxes fungible, lifecycles uncoupled, and makes the shared main instance of a service indistinguishable from anyone’s dev instance. A monorepo worktree spawns one box per service (a cohort).
• Workbench box — born as (worktree, no service). A synced workspace plus compute, existing to exec — tests, typechecks, builds. Serving boxes serve; workbenches compute. Heavy jobs never contend with a dev server.

​

Naming and routing

table(box) = org defaults ⊕ overrides(owner(box))

• The org cell holds one default binding per name — normally the pinned main instance. A blue/green rollover is one atomic write here.
• A dev box may carry per-name overrides, stored in its box cell, written by its owner’s tools. The common case is written automatically: cohort auto-wiring points a worktree’s sibling boxes at each other at creation time.
• An org-owned (pinned) box structurally cannot carry overrides — so the shared mesh resolves identically everywhere and can never call into someone’s dev instance. Per-user routing conflicts aren’t forbidden; they’re unrepresentable.

​

Deps are loopback ports, not URLs

[deps]
5001 = "worker"     # this box's localhost:5001 reaches worker
5432 = "db"         # raw TCP — nothing inspects the stream

• Apps need zero changes. Real repos already say localhost:5001 in their .env; on a tesser box that URL simply is the dep.
• No DNS anywhere. No resolver interception, no hosts files, no invented TLD. Names live in manifests, tables, and UI — never on the wire.
• Any protocol works. With one instance per box, forwarding needs no Host/SNI inspection, so postgres rides exactly like HTTP.

​

The viewport

• localhost:3000 — the selected target: the stable door.
• <boxid>.localhost:<port> — any box’s port, directly. Browsers resolve *.localhost to loopback natively (RFC 6761, secure context, no config); tesserd binds each declared port number once and Host-routes, so two boxes on :8080 share one laptop listener. Box IDs are already unique, already on stdout — agents construct URLs mechanically, and there is no name allocation to design.
• Nothing is installed or modified on the host OS. The only global resource consumed is loopback ports, first-come-fail-loud.

​

The control plane

• Org cell — service registry, alias defaults, warm-pool state and refill alarms, fleet policy (reaper TTLs), tokens. Writers: rollovers and admin operations.
• Box cell (one per box) — the box’s lifecycle state machine, its overrides, its derived routing table, presence, reaper timers. It is the join point: it subscribes to org defaults and materializes defaults ⊕ overrides per box. Nobody outside writes its derived state.
• A user cell (token, presence, preferences — nothing routable) is folded into the org cell until a second user exists; the split is mechanical because nothing routes through it.

​

boxd ↔ cell sync: drift-proof by construction

​

boxd

• Process supervisor — spawns the dev recipe as a child, holds the pipes, writes a rotated local log, records exit codes, replaces on restart. boxd supervises but never resurrects: a crash is recorded and reported; re-running dev is the recovery path, because callers own starts.
• Mesh forwarder — owns the dep loopback ports; exposes the service’s declared ports on the private IP (services themselves bind loopback only).
• Activity clock — timestamps meaningful events: mesh traffic, exec children, CLI ops. Live child processes pin the box awake; SSH keepalives and presence pings don’t count. This clock is what the reaper trusts.
• Presence + health — a WebSocket to its box cell carrying heartbeats, table-version echoes, “listening on port” / healthcheck results, and bounded breadcrumbs: exit codes, health flips, a ~40-line crash snapshot (what a failed rollover reports). Bulk logs never leave the box — tesser logs is a direct SSH tail.

​

Content transport

• Dev instances sync from the live worktree — fingerprint short-circuit so unchanged trees cost nothing, a mass-deletion guard against syncing the wrong worktree, and a per-box lock serializing concurrent syncs.
• Pinned instances sync from a throwaway standalone shallow clone of the sha (real .git, one commit, detached HEAD) materialized by the caller.
• Every box is guaranteed a valid standalone repo — sync never ships the source’s .git-shaped thing verbatim. (A linked git worktree checkout’s .git is a file pointing at a laptop path; shipping it raw breaks git on the box.)

​

Lifecycle

​

Infrastructure

• Public subnet, public IPs. Every box gets an auto-assigned public IPv4; the laptop SSHes straight to it — direct, key-only (per-box keypairs, BatchMode, per-box known_hosts). No jump host, no NAT. Public IPs change across sleep/wake; the daemon re-resolves tunnel endpoints when a box moves.
• Box↔box mesh rides VPC-internal private IPs, which are stable for a box’s whole life — including across sleep/wake — so routing tables never chase addresses.
• Security group: :22 in from anywhere (sshd only accepts the per-box keys), members may talk to members on anything, all egress.
• Warm pool: cloud-maintained machine-warm blanks; claim-by-retag in seconds; unclaimed boxes self-destruct on a timer.
• Static infra is an alchemy stack (infra/); ephemeral boxes are not IaC — cells drive RunInstances directly and EC2 tags remain legible truth.