> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recursiv.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recursiv.io/_mcp/server.

# Sandbox

## Overview

The anonymous sandbox lets anyone execute code without an API key or account. It supports TypeScript, JavaScript, and Python. Rate limited to 10 executions per day per IP address.

This is available on `r.sandbox`.

> **Note**
>
> For project-scoped sandboxes (with persistent filesystem, databases, and storage), see [Projects & Deploy](/sdk/build/projects-deploy). This page covers the anonymous/free sandbox only.

## Quick start

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv({ anonymous: true });

const { data, meta } = await r.sandbox.execute({
  code: 'console.log("Hello, world!")',
  language: 'typescript',
});

console.log(data.output);                    // "Hello, world!\n"
console.log(data.exitCode);                  // 0
console.log(data.executionTime);             // milliseconds
console.log(meta.remaining_executions);      // 9 (out of 10/day)
```

## Method

### `r.sandbox.execute(input)`

Execute code in an isolated sandbox environment.

**Input:**

| Field      | Type                                       | Required | Default        | Description           |
| ---------- | ------------------------------------------ | -------- | -------------- | --------------------- |
| `code`     | `string`                                   | Yes      | —              | The code to execute.  |
| `language` | `'typescript' \| 'javascript' \| 'python'` | No       | `'typescript'` | Programming language. |

**Returns:** `SandboxResponse`

```typescript
interface SandboxResponse {
  data: {
    output: string;        // Combined stdout/stderr
    exitCode: number;      // 0 on success, non-zero on error
    executionTime: number; // Execution time in milliseconds
    error?: string;        // Error message if execution failed
  };
  meta: {
    sandbox_id: string;
    remaining_executions: number; // Remaining executions today
    signup_url: string;           // URL to sign up for unlimited access
  };
}
```

## Anonymous mode

The sandbox is designed for anonymous access. Pass `anonymous: true` to the constructor to skip API key validation:

```typescript
const r = new Recursiv({ anonymous: true });
```

When `anonymous` is true, the SDK does not require or send an API key. Only the `r.sandbox.execute()` method is available in this mode -- all other resources require authentication.

## Supported languages

### TypeScript

```typescript
const { data } = await r.sandbox.execute({
  code: `
    interface User {
      name: string;
      age: number;
    }

    const user: User = { name: 'Alice', age: 30 };
    console.log(JSON.stringify(user));
  `,
  language: 'typescript',
});

console.log(data.output); // {"name":"Alice","age":30}
```

### JavaScript

```typescript
const { data } = await r.sandbox.execute({
  code: `
    const numbers = [1, 2, 3, 4, 5];
    const sum = numbers.reduce((a, b) => a + b, 0);
    console.log('Sum:', sum);
  `,
  language: 'javascript',
});

console.log(data.output); // Sum: 15
```

### Python

```typescript
const { data } = await r.sandbox.execute({
  code: `
import json

data = {"message": "Hello from Python", "numbers": list(range(5))}
print(json.dumps(data))
  `,
  language: 'python',
});

console.log(data.output); // {"message": "Hello from Python", "numbers": [0, 1, 2, 3, 4]}
```

## Rate limits

The anonymous sandbox is rate limited to **10 executions per day per IP address**. The `meta.remaining_executions` field tells you how many you have left.

```typescript
const { meta } = await r.sandbox.execute({
  code: 'console.log("test")',
});

if (meta.remaining_executions === 0) {
  console.log(`Daily limit reached. Sign up at ${meta.signup_url}`);
}
```

When the limit is reached, the SDK throws a `RateLimitError`:

```typescript
import { RateLimitError } from '@recursiv/sdk';

try {
  await r.sandbox.execute({ code: 'console.log("test")' });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log('Daily sandbox limit reached.');
    console.log('Upgrade:', err.upgradeUrl);
  }
}
```

## Error handling

```typescript
const { data } = await r.sandbox.execute({
  code: 'throw new Error("something broke")',
  language: 'typescript',
});

if (data.exitCode !== 0) {
  console.error('Execution failed:');
  console.error(data.output); // Contains the error stack trace
  console.error(data.error);  // Error summary if available
}
```

## Use cases

The anonymous sandbox is ideal for:

* **Try-before-you-buy**: Let users experiment with the platform without creating an account.
* **Code playgrounds**: Embed a code editor on your website that executes code via the API.
* **AI agent tools**: Give LLMs the ability to run code without provisioning infrastructure.
* **Quick prototyping**: Test ideas without setting up a full project.

For production workloads, use project sandboxes with `r.projects.executeCode()` which have no daily limits and access to databases, storage, and a persistent filesystem.