Code Execution API

The cdbx Code Execution API lets you execute code in a secure sandbox from your own scripts, agents, or applications. Send code, get output — no infrastructure required.

Building an AI agent? MCP is the primary way to give it this capability — see Use it from an AI agent (MCP) below. The REST API on this page is for calling it directly from your own scripts and applications instead.

Base URL

https://cdbx.ai/api/v1/runner

Interactive API explorer → cdbx.ai/api/v1/runner/openapi/index.html (opens in a new tab)

Paste your API key into the Authorize dialog to try endpoints directly in your browser.

Authentication

All endpoints except GET /v1/languages require a cdbx API key with the runner:execute scope.

Generate one in API → API Keys in the sidebar. Pass the key as a Bearer token:

Authorization: Bearer cdbx_your_key_here

Endpoints

Method	Path	Auth	Description
`POST`	`/execute`	Required	Execute code and return output
`POST`	`/check`	Required	Syntax/type check without executing
`POST`	`/run/async`	Required	Start async execution, get job ID
`GET`	`/ws/:jobId`	None	WebSocket stream for async job
`POST`	`/sessions`	Required	Create a persistent session (IDE mode)
`DELETE`	`/sessions/:id`	Required	Delete a session
`POST`	`/sessions/:id/run`	Required	Execute in a session
`POST`	`/sessions/:id/files`	Required	Write files to a session
`GET`	`/languages`	None	List supported languages

Execute code

POST https://cdbx.ai/api/v1/runner/execute

Runs code in a fresh container and returns the output synchronously.

Request body

{
  "language": "python",
  "files": {
    "main.py": "print('Hello, world!')"
  },
  "entrypoint": "main.py",
  "stdin": "",
  "timeout": 10
}

Field	Type	Required	Description
`language`	string	yes	Language ID (see `/languages`)
`files`	object	yes	Map of filename → source code
`entrypoint`	string	yes	The file to execute
`stdin`	string	no	Input piped to stdin
`timeout`	number	no	Max execution seconds (capped by tier)

Response body

{
  "stdout": "Hello, world!\n",
  "stderr": "",
  "exitCode": 0,
  "duration": 142
}

Field	Description
`stdout`	Standard output
`stderr`	Standard error
`exitCode`	Process exit code (0 = success)
`duration`	Wall-clock time in milliseconds
`error`	Set if the Code Execution API itself failed (not the user code)

Check (syntax/type check)

POST https://cdbx.ai/api/v1/runner/check

Same request shape as /execute. Runs only the compile or type-check step without executing the program. Languages that have no check command return an empty successful response. Useful for real-time error feedback without consuming execution quota.

Async execution (streaming)

For long-running code or when you want to stream output line-by-line:

Step 1 — start the job:

POST https://cdbx.ai/api/v1/runner/run/async

Same request body as /execute. Returns immediately:

{
  "jobId": "abc123",
  "wsUrl": "/v1/ws/abc123"
}

Step 2 — connect via WebSocket:

wss://cdbx.ai/api/v1/ws/{jobId}

Each message is a JSON event:

{ "type": "stdout", "data": "Hello\n" }
{ "type": "stderr", "data": "" }
{ "type": "exit",   "exitCode": 0, "duration": 300 }

Event types: stdout, stderr, exit, error.

Sessions (IDE / REPL mode)

Sessions keep a container alive between runs — useful for interactive REPL use or when you want to share state across multiple executions.

Create a session

POST https://cdbx.ai/api/v1/runner/sessions

{ "language": "python" }

Response:

{ "id": "sess_abc123", "language": "python" }

Run in a session

POST https://cdbx.ai/api/v1/runner/sessions/{id}/run

{
  "files": { "main.py": "x = 42\nprint(x)" },
  "entrypoint": "main.py",
  "stdin": "",
  "timeout": 10
}

files is optional if you've already written files to the session. Returns the same RunResponse as /execute.

Write files to a session

POST https://cdbx.ai/api/v1/runner/sessions/{id}/files

{
  "files": {
    "helper.py": "def greet(name): return f'Hello, {name}'"
  }
}

Delete a session

DELETE https://cdbx.ai/api/v1/runner/sessions/{id}

Returns 204 No Content.

List supported languages

GET https://cdbx.ai/api/v1/runner/languages

Public endpoint — no auth required.

{
  "languages": [
    { "id": "python",     "name": "Python",     "version": "3.12", "extension": ".py"  },
    { "id": "javascript", "name": "JavaScript", "version": "20",   "extension": ".js"  },
    ...
  ]
}

Limits by tier

Tier	Executions/month	Max timeout
Free	100	10s
Pro	2,000	30s
Enterprise	Unlimited	60s

When the monthly limit is reached the API returns 429:

{ "error": "Monthly execution limit reached (100/month on free plan)..." }

With headers:

Header	Description
`X-RateLimit-Limit`	Your monthly execution limit
`X-RateLimit-Remaining`	Executions remaining this month
`X-RateLimit-Reset`	Unix timestamp when the counter resets

Extra executions

Purchase additional execution packs in Plans & Credits. Packs are consumed after your monthly quota is exhausted and never expire.

Pack	Price
1,000 executions	$5
2,500 executions	$10
7,000 executions	$25

Examples

curl

curl -X POST https://cdbx.ai/api/v1/runner/execute \
  -H "Authorization: Bearer cdbx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "files": { "main.py": "print(\"Hello, world!\")" },
    "entrypoint": "main.py"
  }' \
  | jq

fetch (Node.js)

const res = await fetch('https://cdbx.ai/api/v1/runner/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer cdbx_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    language: 'javascript',
    files: { 'index.js': 'console.log("Hello, world!")' },
    entrypoint: 'index.js',
  }),
});
 
const { stdout, stderr, exitCode, duration } = await res.json();

requests (Python)

import requests
 
response = requests.post(
    'https://cdbx.ai/api/v1/runner/execute',
    headers={
        'Authorization': 'Bearer cdbx_your_key_here',
        'Content-Type': 'application/json',
    },
    json={
        'language': 'python',
        'files': {'main.py': 'print("Hello, world!")'},
        'entrypoint': 'main.py',
    },
)
 
data = response.json()
print(data['stdout'])

SDKs

Prefer not to hand-roll the HTTP calls above? Official SDKs wrap the same endpoints:

npm install @cdbx.ai/run      # TypeScript / Node.js
pip install cdbx-run           # Python

import { run } from '@cdbx.ai/run';
 
const { stdout } = await run('cdbx_your_key_here', {
  language: 'python',
  code: 'print("Hello, world!")',
});

@cdbx.ai/run on npm (opens in a new tab) · cdbx-run on PyPI (opens in a new tab)

Use it from an AI agent (MCP)

If your caller is Claude Code, Claude Desktop, or any other MCP client, you don't need to hand-roll HTTP calls — connect to the standalone Code Execution MCP server instead:

https://cdbx.ai/api/mcp/runner

It exposes exactly one tool, run_code, backed by the same execution path as the REST API above. Unlike the main cdbx MCP Server (which also gives an agent access to your apps), this server needs nothing but a key with the runner:execute scope — no mcp:read/mcp:write, and no exposure to anything else in your account:

claude mcp add --transport http cdbx-runner https://cdbx.ai/api/mcp/runner \
  --header "Authorization: Bearer cdbx_your_key_here"

Service status

Real-time health for all supported languages — latency, uptime, and status per language — is available at cdbx.ai/status.

Terminal Keyboard Shortcuts