Setting up a sandbox

A sandbox is an isolated, disposable copy of your application, built from your repo and seeded with known data. Think of it as a preview environment crossed with a database fixture — for the whole app, and the browser that drives it. Tests run against clean, predictable state, so assertions stay tight and one run never trips over another's leftovers.

You define a sandbox once as a template, verify it, then provision fresh instances from it on demand. Setting up the template is real work — build artifacts, seed data, provisioning actions, health probes — which is exactly why you shouldn't do it by hand.

Don't want to read this? Copy this prompt and give it to your agent:

Or read on to do it yourself.

01Before you start: connect GitHub

Cofactor builds your sandbox from source, so a GitHub connection is the one hard prerequisite — and installing the app is a human step your agent can't do for you:

1. In Settings → GitHub, click Install GitHub App and grant access to the repositories that build your application.

2. Link those repos to your application — in the app, or from the CLI:

   bashCopy

   cofactor property repo link --property <id> --repo owner/name
   

3. Multi-service app? Link every repo that ships together — frontend, backend, workers — so one sandbox can hold the whole release.

If template creation shows no repositories to pick from, this is what's missing.

02Let your agent build the template (recommended)

The CLI ships an authoring guide written for agents — cofactor sandbox guide — covering everything a template needs: research, artifacts (Docker Compose, Dockerfiles, setup scripts), actions, verification, and the checklist. Your agent reads it, then works the loop:

cofactor sandbox create <application>        # template from your linked repo(s)
cofactor sandbox checklist <template-id>     # what's left before verification
cofactor sandbox verify <template-id>        # provision once, probe it, flip to verified
cofactor sandbox provision <template-id>     # fresh instance from a verified template

The checklist is the contract: build steps, seed data, credentials, probes — each completed or deliberately skipped. When verify goes green, the template is reusable forever: every provision after that is a clean environment on a fresh URL.

The prompt at the top of this page packages all of this up — paste it into Claude Code (or any agent with the CLI available) and it handles the loop, pausing where you're needed: approving the login, and installing the GitHub App.

03How sandboxes fit into environments

Every application has environments — the permanent ones you configure (staging, production), local ones, and ephemeral ones. Sandbox instances are the ephemeral kind: when you provision one, it shows up on your application's environment pages next to the permanent targets, with its own URL and a bounded lifetime (expired entries disappear from selectors after 24 hours).

That means a sandbox is a first-class target everywhere environments are:

• Flows and suites can run against a sandbox instance like any other environment.
• Ad-hoc tests prefer them — set your application's default ad-hoc environment to a verified sandbox template and every one-click test starts in a fresh, seeded copy. See Ad-hoc testing.
• PR tests go further: mention the bot on a pull request and Cofactor provisions a sandbox from that PR's branch — testing unmerged code on a disposable copy.
• Per-environment variables ($var.ENV.*) resolve against whatever environment the run targets, sandboxes included — flows stay portable across staging, production, and sandbox without edits.

04Personas: logins in a world that resets

A fresh sandbox has no users — by design. Personas solve the login problem.

A persona is a named role on your application — Admin, Member, Read-only viewer — and credentials bind to personas per environment:

cofactor persona list --application <name>
cofactor persona create --application <name> --name "Admin"

The trick that makes sandboxes seamless: bind your template's credential-provisioning action to a persona. Cofactor then creates that persona's user inside the sandbox and registers the login for you — no manual credential wrangling, no stale passwords. A flow authored as "run as Admin" works against staging, production, and a sandbox born thirty seconds ago.

The action runs at one of two moments:

• On provision — flag the action to run on provision and it fires once as each new instance comes up, so the login exists before any test runs. Best for the roles every run needs.
• On demand — otherwise it runs the first time a flow actually logs in as that persona on the instance, so you don't provision logins a run never uses.

Either way the login lands on the running instance. That's the one caveat worth remembering: because a persona is minted on a live instance, a sandbox flow needs an instance to be up. If none is running when a flow starts, the run provisions one first (slower, and subject to the build's own health checks). Warm one ahead of a suite to avoid the cold start:

cofactor sandbox warm <template-id> --wait

Point the flow's default environment at the durable sandbox environment (the template-backed one), not at a specific instance's ephemeral environment — ephemeral environments are transient and can't be defaults. If a persona login fails to resolve on a sandbox, the usual cause is "no live instance" or "no provisioning action bound to that persona," not a missing mapping.

If your app has more than one role worth testing, give each its own persona and provisioning action — role-based tests stay honest because each run gets exactly the access it claims to have.

See Credential templates and Credentials & login for the full model.

05Next steps

• Sandboxes — the full template and instance model: states, rebuilds, multi-repo setups, troubleshooting
• Setup, seed & teardown — shaping the data a sandbox starts with
• Ad-hoc testing — the fastest way to put a sandbox to work

Designing a good test — writing assertions that exploit deterministic data