Sandboxes

Overview

A sandbox is a separate copy of your project's runtime data. Same agents, same routines, same configs, but its own threads, users, messages, and credentials. Anything you do inside it stays inside it.

You'll reach for one when you want to:

• run a new routine against realistic data before it touches production conversations
• give a customer-facing demo without polluting your live thread history
• let different environments (staging, scratch, customer-specific) coexist without stepping on each other

Every new project ships with a default sandbox called Test. Start there.

---

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 ArchAgents Portal:

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

# CLI
archagent 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 ArchAgents 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
archagent list sandboxmails --sandbox dsb_abc123
archagent describe sandboxmail sem_abc123 --sandbox dsb_abc123

Cleaning up

archagent delete sandboxmail sem_abc123 --sandbox dsb_abc123
archagent 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
archagent activate sandbox

# List sandboxes, active sandbox is marked with *
archagent 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

---

ArchAgents Portal

ArchAgents Portal at https://archagents.com 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.

Exercise new agent behavior in test and staging first. Promote to production after the end-to-end behavior holds up against realistic data.