Sandbox definitions

Definition, not snapshot#

Some parts of a sandbox have a source that can be named again: a repo has a remote and branch, the workspace itself is a repo with a remote, a connection has a kind and non-secret configuration, and an environment overlay is source code. Other parts exist only here: transcripts, unpushed branches, checkpoints, account sessions and ledgers. A definition carries the first set as references. A bundle carries the definition plus the irreplaceable state.

What the TOML describes#

# Intentic sandbox definition: safe to review and publish.
schemaVersion = 1
name = "storefront"

# Names only. The target asks its owner for the values.
secrets = ["SENTRY_AUTH_TOKEN"]

[environment]
baseImage = "ghcr.io/intentic/sandbox:stable"
dockerfile = '''
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg
'''

# Only choices that differ from the defaults.
[settings]
workspaceMap = true

# The workspace itself: notes, skills, personas, automations, designs, drafts.
[workspace]
remote = "https://github.com/example/storefront-workspace.git"
ref = "main"

[[repositories]]
id = "product"
remote = "https://github.com/example/product.git"
ref = "main"

# The connection lands visibly unauthenticated.
[[capabilities]]
id = "linear"
kind = "mcp"
config = { url = "https://mcp.linear.app/sse" }

The file does not include credentials, browser or provider sessions, owner identity, transcripts, unpushed git data, checkpoints or the built image. An export also lists anything it could not express — a repository with no remote, or a workspace nobody has published — instead of quietly leaving it out.

The file is derived, never kept as a second copy. Downloading one reads the live repo remotes, capability manifests, overlay and settings each time, and equal state produces byte-identical output. There is no stored sandbox.toml that can drift from the sandbox it describes, which is also what makes a drift comparison a computation rather than bookkeeping.

The format version is exact: this build accepts schemaVersion = 1. Unknown keys are errors rather than being discarded, so a misspelled field cannot look as though it applied successfully.

The workspace itself#

/work is a git repository. It tracks everything in the workspace that is not a project repository, reference material or internal daemon state — which in practice is the sandbox's way of working: notes, authored skills, personas, automations, workflow and loop designs, drafts and workspace extensions. Credentials, browser profiles and provider sessions sit outside that repository by construction, which is what makes publishing it safe to offer.

Publish it from the same card and a private repository is created on your connected GitHub or GitLab account. From then on the definition carries a [workspace] section, and a target that applies the file gets the way you work, not only the code you work on. Until then the export says so in its omissions, because the difference is too large to leave for someone to discover.

A workspace only lands on the exact clean baseline this daemon created, or during its marked first-boot window. A one-commit repository is not assumed to be empty. A changed baseline, visible file change, or existing workspace remote marks the item “already here”. Before checkout, the fetched tree is inspected away from /work. Private or ignored state, nested repositories, symlinks, gitlinks, the reference shelf and the public outbox are refused; an ignored credential already on disk is never exposed to checkout.

What arrives switched off#

The sections above can guarantee their own safety — a connection has nowhere to put a credential, an overlay is written as a proposal. A raw checkout cannot, because whatever is in the tree is what lands. Intentic therefore builds an inert tree in a temporary checkout first, and only that tree can touch the live workspace. Three things arrive off, each named on the report:

• The environment overlay goes to the approval gate as a proposal instead of arriving already approved.
• Automations arrive disabled, because the scheduler fires enabled ones unattended.
• Workspace extensions arrive switched off, because an extension's code runs in the sandbox once it is on.

Files represented by their own checklist sections — capabilities, settings and the approved overlay source — keep the target's bytes during workspace checkout. They change only if their own item is selected. A malformed active manifest or a failed safety write fails the workspace item; the report never claims something was switched off when it was not.

Everything else — designs, drafts, personas, skills, notes — waits for a person to open it, so it lands as it is.

Download, bring in, or compare#

Open Sandbox → Environment and find Export and Import. One card per direction, so a definition is not a card of its own: it is one of the things you can take out, and one of the things you can bring in.

• Export → Download sandbox.toml derives the current file and names anything omitted from it. The button beside it exports a bundle instead, which is the same document plus the bytes nothing can reference; it asks, before it starts packing, whether to write the secret values into the file. The answer is per export and starts at no.
• Export → Compare sandbox.toml writes nothing. It returns one line per difference, or says the sandbox is in agreement.
• Import → Choose a file takes the definition and parses it into a checklist. Applicable items start selected; existing repo paths and connection ids are marked “already here” and are never overwritten. The same picker takes an environment bundle or a packed Hermes/OpenClaw folder — you do not tell it which you have, it reads the file and says.

Bringing one in is preview-first, whatever it was. The daemon holds the exact artifact behind a short-lived plan token, then re-derives the selected items from those held bytes when you confirm. The browser cannot alter the reviewed plan on the way back.

Consent does not travel#

A shared file may name an overlay that installs packages, but it does not carry the source owner's approval. Applying it writes an environment proposal; the target owner reviews and rebuilds it through the same gate as an agent-proposed change. Connections arrive without authentication and secret names arrive without values. The apply report repeats every manual step that remains.

Existing things are protected by the same rule: a definition lands beside, never over. It is an additive arrival mechanism, not a force-convergence command. Use Compare to measure drift and make an explicit local change when the target already has a conflicting repo or connection.

One definition, many sandboxes#

The sandbox run contract can seed an empty workspace from the TOML on first boot. The workspace is checked out, repositories are cloned, connection cards are created unauthenticated, settings are applied, and the overlay waits for its new owner. Replaying the same container environment on a later rebuild is inert because the workspace is no longer empty. That makes one reviewed definition a fleet recipe — every sandbox in the fleet with the same skills, personas and designs, not merely the same code — without turning boot into an unreviewed configuration executor.

Runners reuse the same definition contract more narrowly. They receive the parent's approved image overlay and a settings-only definition; repos still travel through the conversation's git branches, and capabilities and secrets do not travel at all.

Related pages

• Docker setup: the replaceable image and durable volumes a definition describes.
• Remote runners: how the definition keeps execution environments in step.
• Architecture: why reproducible shape and irreplaceable state are separate.