Sandboxes

Overview

Sandboxes give you isolated environments inside one ArchAstro project.

Use them when you want to:

• test without touching production data
• run demos safely
• give different teams or environments their own isolated workspace

When you use a sandbox, ArchAstro keeps the data in that sandbox separate from production and from other sandboxes.

Every new project starts with a default sandbox named "Test" so you can begin trying things without touching production.

A sandbox is a safe workspace where you can prove behavior before it reaches production.

If you are building agents seriously, that matters a lot. Sandboxes let you test realistic conversations, routines, and email flows without creating production noise or touching real user data.

---

A concrete example

Imagine you are building a billing support agent.

Before you let it touch production conversations, you can:

1. activate a sandbox
2. create a demo user
3. create a billing test thread
4. send a realistic message
5. inspect the result and any captured emails

That gives you a safe way to answer the questions that matter:

• does the agent respond correctly?
• do the routines trigger when expected?
• does the knowledge access look right?
• do email and notification flows behave properly?

---

Creating sandboxes

Create additional sandboxes through the CLI or developer portal:

Slugs must be lowercase alphanumeric with hyphens, 2-100 characters, and unique per project. They cannot start or end with a hyphen.

# CLI
archastro create sandbox -n "Staging" -s staging

---

Access in sandboxes

Each sandbox has its own access credentials, separate from production:

• client-side work uses sandbox publishable keys
• server-side setup uses sandbox secret keys
• sandbox credentials only reach sandbox data, not production

Create and revoke sandbox credentials through the CLI or developer portal as needed for test environments and demos.

If the work is test-only, use sandbox credentials so the resulting data stays in the sandbox.

---

How sandboxes behave

When you work inside a sandbox, the platform does four simple things:

1. It knows which sandbox you selected.
2. It keeps reads inside that sandbox automatically.
3. It saves new data back into that sandbox automatically.
4. It keeps that work separate from production and other sandboxes.

Your code does not need a different logic path for sandbox versus production. The main difference is which sandbox or credential you choose.

Production credential  →  production workspace
Sandbox credential     →  selected sandbox workspace

This separation applies across the main things teams care about, including users, teams, threads, messages, agents, configs, integrations, automations, files, and secrets.

You do not need one mental model for testing and a different one for production. The main difference is which environment you selected.

---

Sandbox emails

Emails sent within a sandbox are captured instead of delivered. This lets you test email flows (registration, notifications, magic links) without sending real emails.

Viewing captured emails

# CLI
archastro list sandboxmails --sandbox dsb_abc123
archastro describe sandboxmail sem_abc123 --sandbox dsb_abc123

Cleaning up

archastro delete sandboxmail sem_abc123 --sandbox dsb_abc123
archastro delete sandboxmails --sandbox dsb_abc123 --all

---

Using sandboxes with the CLI

The CLI can be pointed at a sandbox so later commands operate on sandbox data:

# Activate a sandbox
archastro activate sandbox

# List sandboxes — active sandbox is marked with *
archastro list sandboxes

When a sandbox is active, later CLI commands create and inspect data inside that sandbox until you switch back.

For day-to-day development, the common loop is:

1. activate the sandbox
2. create or update the agent
3. run a test thread
4. inspect the result
5. clean up or reset as needed

---

Developer portal

The portal at developers.archastro.ai provides a visual interface for sandbox management under Project → Sandboxes:

• Create and manage sandboxes
• Create the credentials each sandbox needs
• Review recent usage and status
• Revoke access with confirmation

---

Design patterns

Integration testing

Use a sandbox to run automated tests without affecting production:

1. Create a sandbox (or use the default "Test" sandbox)
2. Use the sandbox publishable key in your test suite
3. Create users, agents, and threads — all isolated to the sandbox
4. Verify email flows by checking captured sandbox emails
5. Clean up by deleting sandbox emails between test runs

This is the right pattern when you want realistic end-to-end testing without touching production.

Demo environments

Create a named sandbox (e.g., demo) with pre-seeded data for customer demos. Each demo sandbox is isolated, so you can reset it independently without touching production or other sandboxes.

This works well when you want a stable environment for sales, solutions, or implementation walkthroughs.

Staging pipeline

Use sandboxes as lightweight staging environments:

1. test sandbox — automated test suite
2. staging sandbox — manual QA and review
3. Production — the main project workspace

All three share the same project configuration but have completely separate user data, threads, and state.

Production should not be the place where you first discover confusing agent behavior.