Sandbox (Test Environment) FAQ

Security and maintenance FAQ for Cofactor sandboxes.

Short answers to the security and maintenance questions teams ask most about Cofactor sandboxes, the disposable environments Cofactor provisions to run and validate your tests. For setup, start with Setting up a sandbox; for the full feature tour, see Sandboxes.

01Security

Is my sandbox isolated from other customers?

Yes. Every sandbox runs on its own dedicated single-tenant compute instance, so there is no shared host between organizations. Each instance lives in an isolated network segment with its own outbound gateway, so one customer's sandbox has no network path to another customer's sandbox. Instances are also encrypted at rest.

Can code running in my sandbox reach Cofactor's own systems?

No. Sandboxes are network-isolated from Cofactor's internal services. Code in a sandbox cannot initiate connections to our application databases, caches, or internal APIs; those paths are blocked at the network layer. The sandbox host itself holds no credentials to Cofactor's data. All control traffic flows one way, from Cofactor into the sandbox over a hardened management channel, never the reverse.

What happens to my application's own secrets and credentials?

The configuration and credentials you put on a template (database URLs, API keys, test logins) belong to your environment and stay single-tenant to your sandbox. They are encrypted at rest and only decrypted into your own instance at provision time so your app can run. We recommend using scoped, test-only credentials for sandboxes rather than production secrets: a sandbox is a place to exercise your app, not a vault. Cofactor credential templates make it easy to bind a different credential per environment.

Do you send my data to AI providers using our keys?

No. When the sandbox agent calls an AI model, the request is routed through a Cofactor-side proxy, and real AI-provider API keys are never placed inside your sandbox. The agent only ever holds a scoped, per-instance token, and that token is only valid for its own instance.

You run arbitrary code in the sandbox. How is that safe?

Running your code is the point of a sandbox, and the safety comes from where it runs. Your app runs in containers on a dedicated, network-isolated instance with no access to Cofactor's systems or to other customers. Management actions on the sandbox are authenticated, org-scoped, and audit-logged, and all outbound network activity is recorded so unusual traffic is visible. Sandboxes are also disposable: they run for a limited lifetime and are torn down when you're done.

Can I restrict what my sandbox is allowed to talk to on the internet?

Yes. This is the network egress allowlist. You can put a sandbox in one of three modes:

Mode	Behavior
Off	Standard outbound internet access
Observe	Access is unchanged, but every request that falls outside your allowlist is recorded so you can see what your app reaches before you lock it down
Enforce	Outbound traffic is denied by default and only approved destinations are allowed

The essentials a sandbox needs to function (DNS, Cofactor's own endpoints, and package registries during build) are always permitted, so turning enforcement on won't break your environment.

How do I see what got blocked, and allow something I actually need?

Each sandbox has an Egress view listing the destinations that were blocked (or, in Observe mode, would be blocked): destination, port, how many times it was hit, and when it was last seen. When you spot a destination your app legitimately needs, click Allow. It's added to the allowlist and applied to the running sandbox within seconds, with no rebuild required. Start in Observe mode to learn your app's real outbound footprint, then switch to Enforce once the allowlist looks right.

Can I keep a sandbox off the public internet entirely?

Yes. Launch it as a Private instance and it gets no public URL; it's reachable only over private access details instead of a shareable link. Combine Private with an egress allowlist when you want an environment that is neither reachable from, nor able to freely reach, the public internet. See the access-mode options in Sandboxes.

How long is sandbox data kept?

Sandboxes are ephemeral. Instances run for a bounded lifetime (a TTL you can set at launch) and are terminated afterward, which tears down the environment and its data. You can also terminate a sandbox yourself at any time from the sandbox list or the CLI.

How long is my code kept on your servers?

Only as long as it takes to run your tests, and cleanup is automatic:

On the sandbox instance: each sandbox clones your repository into an ephemeral instance that is terminated at the end of its lifetime (by default 8 hours for a manually launched sandbox, or about 1 hour for one spun up automatically for an ad-hoc test), which tears down the checkout. That instance is the only place your code lives while a sandbox is running.
Access tokens: the GitHub token used to clone your repository is short-lived (about 1 hour).

Terminate a sandbox at any time to remove its running instance immediately.

02Maintenance

Day-to-day upkeep runs through the cofactor sandbox CLI. Two concepts to keep straight: a template is the reusable definition of how to build and run your app, and an instance is a running environment provisioned from a template.

Which version of my code does a sandbox run?

By default, every sandbox is provisioned from the latest commit on your repository's default branch (main), fetched fresh at launch. Sandboxes are provisioned on demand for your tests, so a freshly provisioned sandbox always reflects the current tip of that branch. You can point a template at a different branch, or override the branch for a single launch, when you want to test something other than main.

How do I check a sandbox's health and read its logs?

cofactor sandbox diagnostics <instance-id> reports agent health, app health, and container status at a glance.
cofactor sandbox logs <instance-id> [--service <name>] [--tail <n>] shows container logs, optionally scoped to one service.

How do I reset or re-provision a sandbox?

Fresh instance from a template: cofactor sandbox provision <template-id> (add --ttl <hours> to set its lifetime). Tear one down with cofactor sandbox terminate <instance-id>. Because every provision builds fresh from your current config and the latest commit, terminate-and-re-provision is the clean way to get back to a known-good state.
To warm the shared authoring instance the Flow Designer uses: cofactor sandbox warm <template-id> --wait.

How do I re-seed test data?

Baseline data is seeded by run-on-provision actions, which run automatically once per new instance and expose their outputs to flows as $var.SEED.*. Re-run one on a live instance with cofactor sandbox action execute <instance-id> <slug>. See Sandbox base seeds for how seeds layer.

How do I update the app version running in a sandbox?

This is automatic. Because every sandbox is provisioned from the latest commit on its branch, re-provisioning picks up your newest code with no extra steps; you don't need to change the branch or rebuild to get the latest main. To test a different branch, update the template's repo link with cofactor sandbox repo update --template <id> --branch <branch>, and the change applies to the next sandbox you provision. Note that a running sandbox does not update itself: new code lands when a fresh sandbox is provisioned. cofactor sandbox build <instance-id> rebuilds and restarts the app services from the code already on that instance; it does not pull new code.

What happens when my infrastructure or build config changes?

When you change how your app is built or run (for example your Dockerfile, docker-compose file, environment config, or setup and seed scripts), the change is applied the next time you provision a sandbox: each sandbox is built fresh from your current configuration and the latest commit on its branch. Sandboxes that are already running are not modified in place, so provision a new sandbox to pick up the change.

What happens when my database changes?

Each sandbox runs its own database (a container defined in your compose setup) that is created fresh every time a sandbox is provisioned. Your schema migrations run automatically as part of your setup and startup scripts, and your seed or demo data is loaded automatically on first launch, so a newly provisioned sandbox always reflects your current schema. Because the database is part of the ephemeral environment, its data does not carry over between fresh provisions: each new sandbox starts from a clean, freshly migrated, freshly seeded state. A sandbox that is reused while still running keeps its current data until it is re-provisioned.

How do I change a sandbox's size?

cofactor sandbox set-size <template-id> <size> sets the compute size used for the next provision or rebuild. Sizes range from small to 2xlarge; the change applies to future provisions, not to already-running instances.

Sandboxes: full feature reference
Setting up a sandbox: the recommended setup path
Credential templates: per-environment logins
Testing Private Environments: VPC-based testing