> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Compute API — Code Execution, Browser & Filesystem

> REST API reference for Nonhumans Compute — run sandboxed code, control headless browsers, and read the agent's persistent 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`.

```bash theme={null}
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
  }'
```

<ParamField body="code" type="string" required>
  The source code to execute. Multiline strings are supported.
</ParamField>

<ParamField body="language" type="string" required>
  Execution runtime. One of `python`, `typescript`, or `bash`.
</ParamField>

<ParamField body="timeout" type="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`.
</ParamField>

**Example response:**

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

<ResponseField name="stdout" type="string">
  Standard output captured during execution.
</ResponseField>

<ResponseField name="stderr" type="string">
  Standard error output. Non-empty stderr does not necessarily mean failure — check `exit_code`.
</ResponseField>

<ResponseField name="exit_code" type="integer">
  Process exit code. `0` indicates success; any other value indicates an error.
</ResponseField>

<ResponseField name="duration_ms" type="integer">
  Wall-clock execution time in milliseconds.
</ResponseField>

<Tip>
  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.
</Tip>

***

## 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.

```bash theme={null}
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"
  }'
```

<ParamField body="url" type="string">
  Optional starting URL. The browser navigates to this page immediately after the session is created. If omitted, the browser opens a blank tab.
</ParamField>

**Example response:**

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

<ResponseField name="session_id" type="string">
  Unique identifier for the browser session.
</ResponseField>

<ResponseField name="ws_url" type="string">
  WebSocket endpoint for CDP control. Connect using Playwright, Puppeteer, or any CDP-compatible client.
</ResponseField>

<ResponseField name="expires_at" type="string (ISO 8601)">
  Sessions automatically terminate after 60 minutes of inactivity to avoid runaway billing.
</ResponseField>

**Example — connecting with Playwright:**

```typescript theme={null}
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/{id}/screenshot

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

```bash theme={null}
curl "https://api.nonhumans.ai/v1/compute/browser/sessions/bsn_01HXYZ001/screenshot" \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

<ParamField path="id" type="string" required>
  The browser session ID returned when the session was created.
</ParamField>

**Example response:**

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

<ResponseField name="image" type="string">
  Base64-encoded PNG image of the browser viewport.
</ResponseField>

<ResponseField name="width" type="integer">
  Viewport width in pixels.
</ResponseField>

<ResponseField name="height" type="integer">
  Viewport height in pixels.
</ResponseField>

***

## 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.

```bash theme={null}
curl "https://api.nonhumans.ai/v1/compute/fs?path=/reports" \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

<ParamField query="path" type="string">
  Directory path to list. Defaults to `/` (the root of the agent's filesystem).
</ParamField>

**Example response:**

```json theme={null}
{
  "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.

```bash theme={null}
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="
  }'
```

<ParamField body="path" type="string" required>
  Absolute path where the file should be written (e.g. `/reports/summary.txt`).
</ParamField>

<ParamField body="content" type="string" required>
  Base64-encoded file content. Maximum file size is 100 MB per write.
</ParamField>

**Example response:**

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

<Note>
  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.
</Note>