# Developer sandbox

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

A developer sandbox is a Kenso workspace of your own for building and testing an integration. It starts with example campaigns, contacts, inboxes and conversation threads, and everything in it is simulated: sends, orders and charges never reach a provider. Nothing leaves Kenso. Campaigns still plan and send in the sandbox, your webhook endpoints still receive its events, and a few reserved test addresses answer like real leads would.

You work in it with a test key: `kenso_test_` and 49 letters and digits. A test key works only in its sandbox, and only on `Ken-Version: 1.1` routes, which is what `kenso` sends: every other workspace answers 404, and a request without that version, or to a route that has no 1.1 form, answers 403. You have one sandbox at most.

This is not the cloud sandbox a coding agent runs in (`kenso work run`, see `kenso docs agents`).

Sandboxes are in beta: the commands work in workspaces where Kenso has turned them on.

## Commands

The sandbox commands run with your live key, in your current workspace. Run with a test key, they stop before sending anything.

| Command | What it does |
|---|---|
| `sandbox create` | Creates your sandbox and its first test key, and saves the key as the profile `sandbox` |
| `sandbox list` | Lists your sandbox |
| `sandbox reset [sandboxId]` | Deletes everything in the sandbox and seeds it again. Test keys and webhook endpoints stay |
| `sandbox key [sandboxId]` | Creates another test key (5 active at most) and saves it as the profile `sandbox` |
| `sandbox delete [sandboxId]` | Deletes the sandbox with its webhook endpoints and their delivery history, and revokes its test keys, then removes the profile `sandbox` |

Without an id, `reset`, `key` and `delete` use your one sandbox. `delete` asks first on a terminal; in a script or an agent it needs `--yes`, and `--dry-run` prints the request it would send.

## Quick start

```bash
kenso sandbox create
```

It prints the sandbox and its test key once, as JSON:

```json
{"sandboxId":20417,"name":"Sandbox (you@acme.com)","status":"ready","seed":{"campaigns":2,"contacts":25,"inboxes":2,"threads":4},"testKey":{"id":"apk_...","prefix":"kenso_test_AbCdE","secret":"kenso_test_...","expiresAt":"2027-02-13T18:00:00Z"},"profile":"sandbox"}
```

The key is saved as the profile `sandbox`, and your active profile stays the live one. Add `--profile sandbox` to run any command in the sandbox:

```bash
kenso campaigns list --profile sandbox
kenso auth status --profile sandbox
```

`KENSO_API_KEY` and `KENSO_WORKSPACE_ID` win over every profile, `--profile sandbox` included: while either is set, a command does not use the test key and its sandbox. Unset them, or set `KENSO_API_KEY=<the test key> KENSO_WORKSPACE_ID=<sandboxId>` to work in the sandbox. `sandbox create` and `sandbox key` warn when they are set, and `auth status` when they override the profile.

`auth status` says `"keyKind":"test"` and names the sandbox. A test key expires after 90 days: `kenso sandbox key` makes a new one and saves it over the old one in the profile. To start over, `kenso sandbox reset`. When you are done, `kenso sandbox delete --yes`.

Your code can use the same key without the CLI: send it as `Authorization: Bearer <key>` and the sandbox id as `X-Ken-Workspace-Id`.

## Reserved test leads

Add a lead with one of these addresses to a sandbox campaign and launch it. After its simulated send, the lead gets that outcome. A `+label` before the `@` is ignored, so `replied-interested+signup@test.ken.so` works too.

| Address | Outcome in a sandbox |
|---|---|
| `replied-interested@test.ken.so` | A reply classified Interested |
| `bounced@test.ken.so` | A hard bounce |
| `ooo@test.ken.so` | An out-of-office auto reply |
| `unsubscribed@test.ken.so` | An unsubscribe |

Any other address gets a simulated send and nothing after it.

## More for developers

- [API docs](/docs)
- [MCP server](/mcp)
- [Interactive API reference](https://developer.ken.so/reference/)
- [Changelog](/docs/changelog)
