# Sandbox and test environment

<!--
title: "Cork sandbox: a test environment with no account, hosted or local, and the endpoints that need no key"
description: "Two sandboxes with no account and no production data: a hosted one an agent gets in one call (POST /agent/identity, anonymous), and Cork's free local mode on 127.0.0.1. How to get each, call it, what it leaves out, and the endpoints that need no key."
canonical: "https://corkcli.com/docs/sandbox"
last_updated: "2026-11-14"
-->

Cork has two sandboxes, and neither touches production data or needs an account, an API key or a card:

- **Hosted, for an agent**: one call to `https://mcp.corkcli.com/agent/identity` gives an agent its own sandbox on Cork's MCP server at once.
- **Local**: Cork's free mode runs the same server and the same MCP tools on your own machine at `127.0.0.1`, and nothing in it is sent to Cork's servers.

There is no test-mode key. For the REST API, which only the cloud serves, use a workspace of your own on Free (below).

## A hosted sandbox, for an agent with no account

```bash
# 1. register: no account, no key
curl -s https://mcp.corkcli.com/agent/identity \
  -H "Content-Type: application/json" -d '{"type": "anonymous"}'

# 2. its identity_assertion for a sandbox token (csb_...)
curl -s https://mcp.corkcli.com/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data-urlencode assertion=<identity_assertion>

# 3. the MCP server, with that token
curl -s https://mcp.corkcli.com \
  -H "Authorization: Bearer csb_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "my-agent", "version": "1"}}}'
```

- **Its own workspace.** Nobody else's data is in it, and it reaches nobody else's.
- **Sandbox repos only.** Repos named `sandbox/<name>`; a call that names none works in `sandbox/demo`.
- **The sandbox's MCP tools.** `get_briefing`, `get_symbol`, `blast_radius`, `recap`, `explain_code`, `remember`, `recall`, `check_collisions`, `report_edit`, the intents, `claim` and the inbox. Not `setup`, `connect_agents` or `send_agent_message`, which reach machines and people.
- **No agent hours, 1,000 calls.** Nothing in it is metered, billed or counted against anyone; it makes 1,000 tool calls at most, two a second. Past them, every call answers with the claim endpoint to use.
- **MCP only.** The hooks' routes and the REST API do not take a sandbox token.
- **A day, unless claimed.** It is deleted 24 hours after it was made. Claiming it with a person's email (`POST /agent/identity/claim`) makes it their agent, in their workspaces on their plan, once they sign in and type the code it shows them; the sandbox goes then. See [auth.md](https://corkcli.com/auth.md).
- **Limits.** 5 registrations an hour from one address, 100 an hour overall.

## The local sandbox: Cork on your machine

- **The real server.** `npx corkcli` installs one program, `cork`, which is both the agents' hooks and the local server (`cork local`). The local server is the same engine as the cloud: briefings, the code graph, the write gate, change notices, messages, notes, recipes.
- **The same MCP tools.** All 20 tools of the [Cork MCP server](https://corkcli.com/docs/mcp-tools.md) (`get_briefing`, `get_symbol`, `blast_radius`, `remember`, `recall`, `send_agent_message`...), at `http://127.0.0.1:<port>/mcp`.
- **On this machine only.** It listens on `127.0.0.1` and nowhere else. Its data is one SQLite file, `~/.cork/local/collide.db` (`~/.collide/local/` on a machine installed before the rename). See [what Cork sends](https://corkcli.com/data.md): in the local mode, none of it.
- **Free, with no limits.** No account, no agent-hour metering and no time limit.

## Start the local sandbox

```bash
npx corkcli
# or, without Node:
curl -fsSL https://corkcli.com/install.sh | sh
```

That sets up Claude Code, Codex, Cursor and Hermes: their hooks, and Cork's MCP entry (`cork mcp`, a stdio relay to the local server). The hooks start the local server when an agent first needs it; `cork status` prints its address and data folder.

## Call the local server directly

The server writes its port and its one credential, a key minted on first start, beside its data:

```bash
PORT=$(cat ~/.cork/local/port)     # 47600, or the next free port
TOKEN=$(cat ~/.cork/local/token)   # only this machine's agents read it

curl -s http://127.0.0.1:$PORT/health   # no key needed

curl -s http://127.0.0.1:$PORT/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "my-agent", "version": "1"}}}'
```

The answer carries an `Mcp-Session-Id` header. Send it with every later request: `notifications/initialized`, then `tools/list` and `tools/call` (Streamable HTTP, MCP 2025-06-18). Without the key, `/mcp` answers `401`.

## A throwaway local sandbox

To keep tests apart from your own local data, run a second local server with its own data folder and port, and delete the folder when you are done:

```bash
DIR=$(mktemp -d)
CORK_LOCAL_DIR=$DIR CORK_HARNESS_WATCH=0 ~/.cork/bin/cork local --port 47700 &
SANDBOX=$!
sleep 1
curl -s http://127.0.0.1:47700/health
TOKEN=$(cat "$DIR/token")
# ... call http://127.0.0.1:47700/mcp as above ...
kill $SANDBOX && rm -rf "$DIR"
```

`CORK_HARNESS_WATCH=0` keeps this extra server from touching your agent tools' settings.

## What the local sandbox leaves out

The local server has no REST API v1 (`/api/v1/...` answers `404`), no OAuth endpoints, no billing, no dashboard, and no teammates on other machines: those are the cloud's. Agents on one machine see each other there; agents on two machines need an account.

## The REST API without touching a team's data

The cloud has no separate test host: `https://api.corkcli.com` is production. To try the REST API, use a workspace you own that no teammate works in:

1. Sign up at https://corkcli.com/login (GitHub, Google or email). Free is 10 agent hours a month per account, plus 30 bonus hours the first month, with no card, and includes one workspace you own. An agent's use of it counts toward those hours like any other.
2. Get a credential yourself, with no form or key request: an MCP client's OAuth sign-in, `cork login`, or the OAuth flow by hand ([auth.md](https://corkcli.com/auth.md)).
3. If you belong to other workspaces too, tick only the one you test in when you approve the client: the token is then held to it.

## Endpoints that need no key

Each of these answers with no credential at all:

| Endpoint | What it answers |
|---|---|
| `GET https://api.corkcli.com/api/v1/health` | the server is up |
| `GET https://api.corkcli.com/api/v1/plans` | the plans, the free tier, how to get credentials, and this sandbox |
| `GET https://api.corkcli.com/api/v1/status` | the server's own self-check record |
| `GET https://corkcli.com/status.json` | the status page for machines (also [status.md](https://corkcli.com/status.md)) |
| `GET https://corkcli.com/.well-known/mcp.json` | every MCP tool, with its input schema and annotations |
| `GET https://corkcli.com/openapi.json` | the REST API v1 (OpenAPI 3.1) |
| `GET https://mcp.corkcli.com/.well-known/oauth-protected-resource` | the protected resource (RFC 9728) |
| `GET https://mcp.corkcli.com/.well-known/oauth-authorization-server` | the authorization server (RFC 8414), with its `agent_auth` block |
| `POST https://mcp.corkcli.com/register` | a new OAuth client (RFC 7591) |
| `POST https://mcp.corkcli.com/agent/identity` | an agent's registration: `anonymous` (a hosted sandbox at once) or `service_auth` (a code for its person) |
| `GET https://api.corkcli.com/api/invites/{code}` | what an invite link is for, before signing in |

```bash
curl -s https://api.corkcli.com/api/v1/plans
```

## Questions

### Does Cork have a sandbox or test environment?

Yes, two. An agent gets a hosted sandbox in one call (`POST https://mcp.corkcli.com/agent/identity` with `{"type": "anonymous"}`), with no account, and Cork's free local mode (`npx corkcli`) runs the same server and MCP tools on `127.0.0.1`. Neither touches production data. There is no test-mode API key.

### Do I need an API key to try Cork?

No. An agent mints its own: an anonymous registration's sandbox token, or a person's token once they approve it. The local sandbox needs none (its key is minted on your machine), the endpoints above need none, and OAuth with dynamic client registration and `cork login` are self-serve too.

### Does the sandbox cost anything?

No. The hosted sandbox holds no agent hours and is not metered; the local mode is free with no time limit and is not metered either. A workspace on Free in the cloud is 10 agent hours a month, with no card.

## More

- [auth.md](https://corkcli.com/auth.md) · [Cork MCP server](https://corkcli.com/docs/mcp-tools.md) · [Cork API reference (REST v1)](https://corkcli.com/docs/api.md) · [Cork CLI](https://corkcli.com/docs/cli.md)
- [Install](https://corkcli.com/install.md) · [Pricing](https://corkcli.com/pricing.md) · [llms.txt](https://corkcli.com/llms.txt)
