Get started

1. Install

npm install @acoyfellow/lab

2. Connect your agent

Add Lab as a stdio MCP server so your agent can run code and read saved results. Works with Claude Desktop, Cursor, or any MCP client.

{
  "mcpServers": {
    "lab": {
      "command": "npx",
      "args": ["-y", "@acoyfellow/lab-mcp"],
      "env": {
        "LAB_URL": "$LAB_URL"
      }
    }
  }
}

Replace $LAB_URL with your public app origin. Don't have one yet? Self-host guide →

3. Run code

Send code to Lab. It runs in a Cloudflare Worker sandbox and returns the result plus a persisted resultId.

import { createLabClient } from "@acoyfellow/lab";

const lab = createLabClient({ baseUrl: process.env.LAB_URL! });

const result = await lab.runSandbox({
  body: "return 2 + 2",
  capabilities: [],
});

console.log(result.result); // 4
console.log(result.ok);     // true

// Every run saves a result:
// JSON for agents: $LAB_URL/results/${result.resultId}.json
// Viewer for humans: $LAB_URL/results/${result.resultId}

curl -X POST $LAB_URL/run \
  -H 'Content-Type: application/json' \
  -d '{"body":"return 2 + 2","capabilities":[]}'

4. See the result

Every run saves a JSON result. Agents should read /results/{id}.json. Humans can open /results/{id} in the viewer. Successful runs include full step data. Failed or aborted runs include the error and reason; per-step detail may be partial.

curl -s "$LAB_URL/results/$RESULT_ID.json" | jq .