Setting up a sandbox

Give your tests a clean, seeded, isolated copy of your app to run against, instead of shared staging or production.

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:

Set up a sandbox with 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:

In Settings → GitHub, click Install GitHub App and grant access to the repositories that build your application.
Link those repos to your application — in the app, or from the CLI:
bash
```
cofactor property repo link --property <id> --repo owner/name
```
Multi-service app? Link every repo that ships together — frontend, backend, workers — so one sandbox can hold the whole release.

Settings → GitHub — Install GitHub App grants access to the repos that build your sandboxes

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:

bash

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 — your agent works it until every item is done or deliberately skipped

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.

A verified template on the Sandboxes page — Launch provisions a fresh instance; past instances expire and tear down on their own

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:

bash

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. Every new instance then creates that persona's user inside the sandbox and registers the login automatically — 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.

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