Compute API — Code Execution, Browser & Filesystem

The Compute API gives your agent an always-on execution environment. Run code in isolated sandboxes, spin up headless browser sessions for web automation, and persist files across runs on a dedicated filesystem — all without managing infrastructure. Every execution is scoped to your agent and billed per millisecond of active compute.

POST /v1/compute/run

Execute code in a sandboxed environment. The sandbox is ephemeral — it starts fresh for each request — but can read from and write to your agent’s persistent filesystem via /v1/compute/fs.

curl -X POST https://api.nonhumans.ai/v1/compute/run \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "import math\nresult = math.factorial(10)\nprint(f\"10! = {result}\")",
    "timeout": 30
  }'

string

required

The source code to execute. Multiline strings are supported.

string

required

Execution runtime. One of python, typescript, or bash.

integer

Maximum execution time in seconds. Defaults to 30. Maximum 300 (5 minutes). Executions that exceed the timeout are terminated and return a non-zero exit_code.

Example response:

{
  "stdout": "10! = 3628800\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 142
}

string

Standard output captured during execution.

string

Standard error output. Non-empty stderr does not necessarily mean failure — check exit_code.

integer

Process exit code. 0 indicates success; any other value indicates an error.

integer

Wall-clock execution time in milliseconds.

Use the bash language to chain multiple tools, invoke Python and TypeScript scripts together, or run shell commands like curl, jq, or ffmpeg — all available in the sandbox by default.

POST /v1/compute/browser/sessions

Open a new headless Chromium browser session. Returns a WebSocket URL you can use to control the browser via the Chrome DevTools Protocol (CDP) or Playwright.

curl -X POST https://api.nonhumans.ai/v1/compute/browser/sessions \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

string

Optional starting URL. The browser navigates to this page immediately after the session is created. If omitted, the browser opens a blank tab.

Example response:

{
  "session_id": "bsn_01HXYZ001",
  "ws_url": "wss://compute.nonhumans.ai/browser/bsn_01HXYZ001",
  "expires_at": "2024-12-01T18:00:00Z"
}

string

Unique identifier for the browser session.

string

WebSocket endpoint for CDP control. Connect using Playwright, Puppeteer, or any CDP-compatible client.

string (ISO 8601)

Sessions automatically terminate after 60 minutes of inactivity to avoid runaway billing.

Example — connecting with Playwright:

import { chromium } from "playwright";

const session = await fetch("https://api.nonhumans.ai/v1/compute/browser/sessions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NONHUMANS_KEY}` },
}).then((r) => r.json());

const browser = await chromium.connectOverCDP(session.ws_url);
const page = await browser.newPage();
await page.goto("https://example.com");
const title = await page.title();
console.log("Page title:", title);
await browser.close();

GET /v1/compute/browser/sessions//screenshot

Capture a PNG screenshot of the current state of a browser session. Useful for visual verification and debugging.

curl "https://api.nonhumans.ai/v1/compute/browser/sessions/bsn_01HXYZ001/screenshot" \
  -H "Authorization: Bearer $NONHUMANS_KEY"

string

required

The browser session ID returned when the session was created.

Example response:

{
  "image": "iVBORw0KGgoAAAANSUhEUgAAA...",
  "width": 1280,
  "height": 800,
  "captured_at": "2024-12-01T17:45:00Z"
}

string

Base64-encoded PNG image of the browser viewport.

integer

Viewport width in pixels.

integer

Viewport height in pixels.

GET /v1/compute/fs

List files and directories in your agent’s persistent filesystem. The filesystem persists across compute runs and browser sessions, making it ideal for storing intermediate results, downloaded files, and agent state.

curl "https://api.nonhumans.ai/v1/compute/fs?path=/reports" \
  -H "Authorization: Bearer $NONHUMANS_KEY"

string

Directory path to list. Defaults to / (the root of the agent’s filesystem).

Example response:

{
  "path": "/reports",
  "entries": [
    {
      "name": "q4-analysis.csv",
      "type": "file",
      "size_bytes": 48920,
      "modified_at": "2024-12-01T14:00:00Z"
    },
    {
      "name": "charts",
      "type": "directory",
      "modified_at": "2024-12-01T13:00:00Z"
    }
  ]
}

PUT /v1/compute/fs

Write a file to your agent’s persistent filesystem. Creates the file if it doesn’t exist; overwrites it if it does. Intermediate directories are created automatically.

curl -X PUT https://api.nonhumans.ai/v1/compute/fs \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/reports/summary.txt",
    "content": "UmVwb3J0IHN1bW1hcnkgY29udGVudC4="
  }'

string

required

Absolute path where the file should be written (e.g. /reports/summary.txt).

string

required

Base64-encoded file content. Maximum file size is 100 MB per write.

Example response:

{
  "path": "/reports/summary.txt",
  "size_bytes": 24,
  "written_at": "2024-12-01T17:50:00Z"
}

Files written to the persistent filesystem are accessible from subsequent POST /v1/compute/run executions at the same path. Use this to share data between tasks without making network calls.

Overview

Endpoints

Compute API — Code Execution, Browser & Filesystem

POST /v1/compute/run

POST /v1/compute/browser/sessions

GET /v1/compute/browser/sessions//screenshot

GET /v1/compute/fs

PUT /v1/compute/fs

​POST /v1/compute/run

​POST /v1/compute/browser/sessions

​GET /v1/compute/browser/sessions//screenshot

​GET /v1/compute/fs

​PUT /v1/compute/fs

POST /v1/compute/run

POST /v1/compute/browser/sessions

GET /v1/compute/browser/sessions//screenshot

GET /v1/compute/fs

PUT /v1/compute/fs