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

# Limits & Quotas

> Current public limits and validation rules

Most limits depend on your organization's policy and available capacity — this page collects the ones that are fixed in the public SDK and API contracts (validation ranges, upload caps, batch sizes). For your org's live usage and quota state, check the dashboard or run `runtools usage`.

## Sandbox Requests

Sandboxes accept these resource fields:

```typescript theme={null}
await rt.sandbox.create({
  template: 'base-ubuntu',
  resources: {
    vcpus: 2,
    memory: '4GB',
    disk: '10GB',
  },
  idleTimeout: 1800,
});
```

The API validates template availability, workspace mount ownership, safe mount paths, and authorization. If a request exceeds what your organization can use, the API returns an error envelope with an explanatory code/message.

## Agent Definition Validation

`defineAgent()` validates several client-side ranges before deploy:

| Field              | Accepted range                          |
| ------------------ | --------------------------------------- |
| `maxIterations`    | 1 to 100                                |
| `maxTokens`        | 1 to 128000                             |
| `temperature`      | 0 to 2                                  |
| `topP`             | 0 to 1                                  |
| `topK`             | Positive integer                        |
| `presencePenalty`  | -2 to 2                                 |
| `frequencyPenalty` | -2 to 2                                 |
| `executionMode`    | `in_sandbox`, `managed`, or `local-mac` |

`in_sandbox` agents require `sandbox`. `local-mac` execution mode agents require `targetDeviceId` and cannot declare `sandbox`.

Only one active run may write to a thread at a time. A second run against the same active thread returns `409 THREAD_BUSY`.

Platform model calls are charged by token usage. BYOK calls use customer-provided provider keys and are not billed as Platform inference.

## Secrets And Files

| Surface                    | Current behavior                                               |
| -------------------------- | -------------------------------------------------------------- |
| Secrets list               | Metadata only; values are never included                       |
| Secret reveal              | Policy-gated by owner/admin rules                              |
| User-private secrets       | Visible to the owner; broader metadata views are admin-only    |
| Org-shared secrets         | Admin-controlled                                               |
| Workspace mounts           | Personal workspaces cannot be mounted into sandboxes           |
| Storage API                | Requires `files:read`, `files:write`, `files:*`, or `*` scopes |
| Workspace upload           | Default max upload is 100 MB per request                       |
| Workspace batch operations | Copy, move, and delete accept up to 250 IDs per request        |

## Usage Surfaces

```bash theme={null}
runtools usage --json
```

Usage rows include token totals, sandbox seconds, tool executions, and storage bytes when available.

## Handling Limit Errors

```typescript theme={null}
import { RunToolsApiError } from '@runtools-ai/sdk';

try {
  await rt.sandbox.create({ template: 'base-ubuntu' });
} catch (error) {
  if (error instanceof RunToolsApiError) {
    console.error(error.status, error.code, error.message);
  }
}
```

Common causes include missing scopes, admin-only operations, unavailable templates, invalid agent config, or trying to write resources outside your ownership boundary.