Skip to main content

​
Clones

A clone is one running instance of a template. It has: A clone does not store which environment it belongs to. Membership lives on the environment (Environment.members) as the single source of truth; status derives a clone’s environment by reverse lookup.

​
Modes

A template declares modes — named sets of services. The first declared mode is the default. Every template ships an api mode (backend only — the lightest clone, enough for an agent that talks to the API or MCP server). The Slack template additionally ships a full mode that adds the frontend UI; the API-only templates (Stripe, Notion, HubSpot, GitHub, Linear) have api alone. Pick one with --mode:
Omit it and you get the template’s first declared mode.

​
Tokens

When a clone’s template has a provision surface (Slack today), spin calls its bootstrap endpoint once the backend is healthy and mints a default app with a bot token and a user token. They’re shown once at spin time and stored in the registry (the clone DB keeps only hashes). Reprint or rotate them with hone env tokens <id>. Templates without a provision surface simply have no tokens.

​
States

A clone moves through a small state machine:
hone env doctor flags clones in non-terminal states that need a live check.

​
Environments

Clones compose into environments — the top-level primitive you point an agent at and score. An environment has a name, a member list (the source of truth for membership), and a rolled-up state (running / partial / stopped / failed). Spin clones straight into one:
Or declare them in an environment.yaml and hone env spin it. See Environments for the full story.

​
The registry

Everything above is persisted to ~/.asymmetric/registry.json — a versioned JSON file holding clones and environments, rewritten on every create / destroy / reset / seed / start / stop. It’s plain JSON and safe to read (tokens are redacted from status/ls):
The schema is versioned and migrated on read: opening an older registry upgrades it in place (v1 → v2 renamed groups to environments and rebuilt environments from any legacy per-clone group tags, so no membership is lost on upgrade). Because the registry is the source of truth, status, doctor, and db work without touching Docker at all — they just read it. If it ever gets corrupted, hone env doctor is the recovery path.
Override the registry location with ASYM_HOME. Point CI at a throwaway directory so its clones never collide with your local ones.