Runners Quickstart

Managed runners are in private beta and gated behind the FF_GATEWAY_MANAGED_RUNNER_BETA flag. Without access, the runner endpoints return 404 and the dashboard surfaces are hidden. Request the beta to get added to the allowlist.

Managed runners are sandboxed execution environments for AI agents. They provide isolated compute (via E2B cloud sandboxes) with full audit trails, RBAC, and governance controls.

Prerequisites

A Curate-Me account with a gateway API key (cm_sk_* or cm_gw_*)
An E2B API key (for production runners) or use fake provider for testing

Quick Start with curl

1. Create a Runner


curl -X POST http://localhost:8002/gateway/admin/runners/ \
  -H "Content-Type: application/json" \
  -H "X-CM-API-Key: cm_sk_your_key_here" \
  -d '{
    "provider_type": "fake",
    "tool_profile": "locked",
    "ttl_seconds": 3600
  }'

Response:


{
  "runner_id": "runner_abc123def456",
  "state": "ready",
  "provider_type": "fake",
  "tool_profile": "locked",
  "ttl_seconds": 3600
}

2. Start a Session


curl -X POST http://localhost:8002/gateway/admin/runners/runner_abc123def456/start \
  -H "X-CM-API-Key: cm_sk_your_key_here"

3. Execute a Command


curl -X POST "http://localhost:8002/gateway/admin/runners/runner_abc123def456/exec?session_id=sess_xyz" \
  -H "Content-Type: application/json" \
  -H "X-CM-API-Key: cm_sk_your_key_here" \
  -d '{
    "argv": ["echo", "Hello from the sandbox!"],
    "timeout_seconds": 30
  }'

4. View Events


curl "http://localhost:8002/gateway/admin/runners/runner_abc123def456/events?limit=20" \
  -H "X-CM-API-Key: cm_sk_your_key_here"

5. Stop and Terminate


# Stop the session
curl -X POST "http://localhost:8002/gateway/admin/runners/runner_abc123def456/stop?session_id=sess_xyz" \
  -H "X-CM-API-Key: cm_sk_your_key_here"
 
# Terminate the runner
curl -X POST http://localhost:8002/gateway/admin/runners/runner_abc123def456/terminate \
  -H "X-CM-API-Key: cm_sk_your_key_here"

Quick Start with Python SDK


from curate_me import CurateMe
 
client = CurateMe(api_key="cm_sk_your_key_here")
gw = client.gateway
 
# Create and start
runner = gw.runners.create(provider_type="fake", tool_profile="locked")
session = gw.runners.start_session(runner["runner_id"])
 
# Execute commands
result = gw.runners.exec_command(
    runner["runner_id"],
    session["session_id"],
    argv=["echo", "Hello!"],
)
print(result["stdout"])  # "fake output"
 
# View events
events = gw.runners.get_events(runner["runner_id"])
for event in events["events"]:
    print(f"  {event['event_type']} at {event['timestamp']}")
 
# Clean up
gw.runners.stop_session(runner["runner_id"], session["session_id"])
gw.runners.terminate(runner["runner_id"])

Quick Start with TypeScript SDK


import { CurateMe } from '@curate-me/sdk';
 
const client = new CurateMe({ apiKey: 'cm_sk_your_key_here' });
 
// Create and start
const runner = await client.runners.create({ tool_profile: 'locked' });
const session = await client.runners.startSession(runner.runner_id);
 
// Execute commands
const result = await client.runners.execCommand(
  runner.runner_id,
  session.session_id,
  ['echo', 'Hello!'],
);
console.log(result.stdout);
 
// View events
const events = await client.runners.getEvents(runner.runner_id);
events.events.forEach((e) => console.log(`  ${e.event_type}`));
 
// Clean up
await client.runners.stopSession(runner.runner_id, session.session_id);
await client.runners.terminate(runner.runner_id);

Quick Start with CLI


# Create a runner
curate runners create --provider fake --profile locked
 
# Start a session
curate runners start runner_abc123
 
# Execute a command
curate runners exec runner_abc123 sess_xyz echo "Hello!"
 
# View events
curate runners events runner_abc123
 
# Stream live output
curate runners stream runner_abc123
 
# Terminate
curate runners terminate runner_abc123 --yes

Tool Profiles

Profile	Description	Use Case
`locked`	Minimal tools, no network	Safe code execution
`web_automation`	Browser + HTTP access	Web scraping, API testing
`full_vm_tools`	Full system access	System administration, builds

Provider Types

Provider	Description	Requires
`e2b`	Cloud sandbox (production)	`E2B_API_KEY`
`fake`	In-memory (testing)	Nothing
`claude_computer_use`	Claude + E2B desktop	`ANTHROPIC_API_KEY`

Next Steps

API Reference — Full endpoint documentation
Security Model — Egress policies, PII scanning
Dashboard — Visual runner management
Pricing — Plans and usage calculator