# E2B — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Secure, stateful Linux coding workspaces with commands, background jobs, files, and large artifact transfer. Runtime is fully prepaid: create a sandbox with a funded window, then explicitly buy more time before it expires. There is no subscription, automatic renewal, negative balance, or postpaid overage. Every sandbox is isolated to the calling Locus Pro account.

**Category:** Developer Tools | **Website:** [e2b.dev](https://e2b.dev) | **Docs:** [e2b.dev/docs](https://e2b.dev/docs)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/e2b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### Create Sandbox

Choose and prepay a 30-to-3,600-second runtime window. Locus reserves the full quote before provisioning and finalizes it only after E2B accepts the sandbox; a definitive failure releases the reservation. The runtime clock starts when provisioning succeeds, and the sandbox terminates at the funded deadline unless Extend Sandbox prepays more time first. Ending early does not refund unused time. This is prepaid requested-time billing, not postpaid elapsed-time billing. There is no automatic renewal or recurring charge. The base image includes standard shell tools plus Python and Node.js; third-party packages such as matplotlib are not guaranteed, so install required dependencies in the sandbox. Outbound internet is off unless explicitly enabled, public ingress stays restricted, and each workspace can run up to five sandboxes at once. A rare inconclusive provider response returns creation_pending while Locus reconciles it automatically, so do not retry create.

**Estimated cost:** $0.001908–$0.109900 for 30–3,600 sec; $0.010075 at 5 min (includes $0.001 workspace fee)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | Optional human-readable label shown by list and get. |
| `timeoutSeconds` | number | No | Prepaid runtime window from 30 to 3,600 seconds. Default 300. Use Extend Sandbox before expiry to buy more time without losing workspace state. |
| `allowInternetAccess` | boolean | No | Enable outbound internet access. Default false. This does not make workspace ports public. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/create \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"research-workspace","timeoutSeconds":300,"allowInternetAccess":false}'
```

### List Sandboxes

List only running sandboxes owned by the calling Locus Pro account, including their funded deadline, seconds remaining, and expiry warning. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | number | No | Maximum results from 1 to 100. Default 25. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":25}'
```

### Get Sandbox

Get safe lifecycle details for an account-owned sandbox, including its funded deadline, seconds remaining, expiry warning, and how much more time can currently be added. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Sandbox ID returned by create or list. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/get \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01"}'
```

### Extend Sandbox

Prepay 30 to 3,600 additional seconds and move the existing sandbox deadline forward without restarting it or losing files and processes. The resulting remaining window may not exceed 3,600 seconds and must leave at least three minutes for safe provider reconciliation, so a near-expiry sandbox may require a larger addition. Funds are reserved before E2B can change the deadline; insufficient balance leaves the old deadline untouched. Concurrent extensions are serialized and ambiguous network responses are retried against one absolute target. Locus then confirms the deadline in the background and refunds a target that E2B proves was not applied, so a retry cannot accidentally buy the same time twice. A terminated sandbox cannot be revived.

**Estimated cost:** $0.001908–$0.109900 for 30–3,600 additional sec (includes $0.001 workspace fee)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID returned by create or list. |
| `additionalSeconds` | number | Yes | Whole prepaid seconds to add, from 30 to 3,600. Current remaining time plus this value must be 180 to 3,600 seconds so any ambiguous provider result can settle before expiry. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/extend \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","additionalSeconds":900}'
```

### Run Command

Run a bounded foreground shell command in an account-owned sandbox and return its exit code, stdout, stderr, and timeoutReason when the command times out. Python bytecode caches are disabled to keep repeated interpreter runs reliable. Use Start Background Job for servers, builds, and interactive processes. Environment values are accepted only for this process and redacted before request persistence. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Sandbox ID returned by create or list. |
| `command` | string | Yes | Shell command to run. |
| `cwd` | string | No | Working directory inside the sandbox. |
| `env` | object | No | Up to 32 process-only environment variables (16 KiB total). Values are redacted from Locus request history. |
| `timeoutSeconds` | number | No | Command timeout from 1 to 3,600 seconds. Default 60; it cannot outlive the sandbox deadline. |
| `maxOutputBytes` | number | No | Exact maximum bytes returned for each output stream, from 1,024 through 262,144. Default 65,536. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/run-command \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","command":"python - <<'"'"'PY'"'"'\nprint(sum(range(10)))\nPY","timeoutSeconds":60}'
```

### Start Background Job

Start a long-running build, server, test, or interactive process and return immediately with a jobId and pid. Optional pseudo-terminal mode supports programs that require a TTY, while retained output and stdin remain available through Get Job and Send Job Input. Each sandbox retains at most 100 jobs; when the limit is reached, the oldest completed jobs are pruned before a new one starts, while active jobs are never removed. Environment values are process-only and redacted from Locus request history. Public ingress remains restricted, so test workspace servers from inside the sandbox. Jobs stop when their timeout or prepaid sandbox deadline is reached. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID. |
| `command` | string | Yes | Shell command to start. |
| `cwd` | string | No | Working directory. |
| `env` | object | No | Up to 32 process-only environment variables (16 KiB total). Values are redacted from Locus request history. |
| `timeoutSeconds` | number | No | Job timeout from 1 to 3,600 seconds. Default 60. |
| `keepStdinOpen` | boolean | No | Keep stdin open for later Send Job Input calls. Default false. |
| `pseudoTerminal` | boolean | No | Run through a Linux pseudo-terminal for interactive/TTY-dependent tools. Default false. Usually pair with keepStdinOpen. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/start-command \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","command":"npm run dev","cwd":"/home/user/project","timeoutSeconds":900,"keepStdinOpen":false,"pseudoTerminal":false}'
```

### Get Background Job

Read a background job state, exit code, and bounded stdout/stderr even after the process exits. Truncation and full byte counts are explicit. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID. |
| `jobId` | string | Yes | Job ID returned by Start Background Job. |
| `maxOutputBytes` | number | No | Maximum bytes returned per stream. Default 65,536; maximum 262,144. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/get-job \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","jobId":"550e8400-e29b-41d4-a716-446655440000"}'
```

### List Background Jobs

List sandbox jobs by jobId with safe state, pid, timing, and exit metadata. Commands and environment values are never returned. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID. |
| `limit` | number | No | Maximum jobs from 1 to 100. Default 25. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/list-jobs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","limit":25}'
```

### Send Job Input

Send bounded UTF-8 or base64 bytes to a background process that was started with keepStdinOpen, and optionally close stdin to signal EOF. Input is redacted from Locus request history. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID. |
| `jobId` | string | Yes | Job ID returned by Start Background Job. Locus resolves and verifies its process ID before sending input. |
| `data` | string | No | Input data. Optional only when close is true. |
| `encoding` | string | No | 'utf8' (default) or 'base64'. |
| `close` | boolean | No | Close stdin after sending data. Default false. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/send-input \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","jobId":"550e8400-e29b-41d4-a716-446655440000","data":"yes\n","close":false}'
```

### Stop Sandbox Process

Stop a Locus background job inside the account-owned sandbox. Locus verifies the job and resolves its process ID instead of accepting an arbitrary sandbox PID. This does not terminate the sandbox or refund runtime. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID. |
| `jobId` | string | Yes | Job ID returned by Start Background Job. Arbitrary sandbox process IDs are not accepted. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/stop-process \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","jobId":"550e8400-e29b-41d4-a716-446655440000"}'
```

### Write File

Create or replace a bounded text or binary file in an account-owned sandbox. Use a signed upload URL for larger artifacts. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Sandbox ID returned by create or list. |
| `path` | string | Yes | Absolute destination path without parent-directory traversal. |
| `content` | string | Yes | UTF-8 text or base64-encoded bytes, up to 256 KiB decoded. |
| `encoding` | string | No | 'utf8' (default) or 'base64'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/write-file \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","path":"/home/user/input.txt","content":"hello from Locus","encoding":"utf8"}'
```

### Read File

Read a bounded text or binary file from an account-owned sandbox, with explicit truncation metadata. Use a signed download URL for larger artifacts. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Sandbox ID returned by create or list. |
| `path` | string | Yes | Absolute file path without parent-directory traversal. |
| `encoding` | string | No | Return 'utf8' (default) or 'base64'. |
| `maxBytes` | number | No | Maximum bytes to return. Default 65,536; maximum 262,144. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/read-file \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","path":"/home/user/input.txt","encoding":"utf8"}'
```

### List Files

List up to 500 files and directories in an account-owned sandbox. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Sandbox ID returned by create or list. |
| `path` | string | Yes | Absolute directory path without parent-directory traversal. |
| `depth` | number | No | Traversal depth from 1 to 4. Default 1. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/list-files \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","path":"/home/user","depth":1}'
```

### Manage Sandbox Files

Create a directory, move a file or directory, or permanently remove a path inside an account-owned sandbox. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID. |
| `action` | string | Yes | 'create_directory', 'move', or 'remove'. |
| `path` | string | Yes | Source or target path. |
| `destination` | string | No | Required destination path for move. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/filesystem \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","action":"create_directory","path":"/home/user/project"}'
```

### Create Artifact Upload URL

Create a short-lived, path-scoped HTTPS upload URL for artifacts too large for Write File. The caller must POST multipart/form-data before expiry. Ownership is checked first; Locus never returns the E2B API key. The requested lifetime is 30 to 300 seconds and is shortened automatically if the sandbox will expire sooner. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID. |
| `path` | string | Yes | Exact destination path inside the sandbox. |
| `expiresInSeconds` | number | No | URL lifetime from 30 to 300 seconds. Default 60. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/create-upload-url \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","path":"/home/user/project/archive.tar.gz","expiresInSeconds":60}'
```

### Create Artifact Download URL

Create a short-lived, path-scoped HTTPS download URL for a large sandbox artifact. Ownership is checked first; the URL expires in at most five minutes, is shortened if the sandbox will expire sooner, and does not expose the E2B API key. The $0.001 action charge does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Running sandbox ID. |
| `path` | string | Yes | Exact file path inside the sandbox. |
| `expiresInSeconds` | number | No | URL lifetime from 30 to 300 seconds. Default 60. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/create-download-url \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01","path":"/home/user/project/result.zip","expiresInSeconds":60}'
```

### Terminate Sandbox

Permanently terminate an account-owned sandbox and every process inside it. Files and process state cannot be recovered, and unused prepaid runtime is not refunded. The $0.001 action charge is separate and does not add runtime.

**Estimated cost:** $0.001

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sandboxId` | string | Yes | Sandbox ID returned by create or list. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/e2b/kill \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sandboxId":"sbxexample01"}'
```