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

# Workspaces & Files

> Persistent storage across sandboxes and agent runs

Workspaces are the storage that survives beyond a single sandbox. For a sandbox-backed agent, a mounted workspace *is* its filesystem memory — the agent works through the sandbox, and whatever lands under `/workspace` is still there next run.

The main guide is [Workspaces](/features/workspaces). The detailed REST reference is split between [Manage Workspaces](/api-reference/workspaces/manage) and [Workspace Files](/api-reference/workspaces/files).

Workspace metadata is managed by the main API. File bytes are served by
the storage API, which validates workspace ownership, path safety, upload
limits, and storage quota before touching the workspace root.

## Management API

Workspace metadata lives on the main API:

```bash theme={null}
curl https://api.runtools.ai/v1/workspaces \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

```bash theme={null}
curl -X POST https://api.runtools.ai/v1/workspaces \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Project",
    "slug": "docs-project"
  }'
```

Creation returns only after the backing storage root is created. If storage quota
or root creation fails, the workspace is not usable and the request fails closed.
Workspace lists include both `workspaces` and an org storage summary.

## Mount Into A Sandbox

Mount paths must be `/workspace` or a subpath under `/workspace`. Only
organization workspaces can be mounted into sandboxes; Personal workspaces are
reserved for user files and thread storage.

```typescript theme={null}
const sandbox = await rt.sandbox.create({
  template: 'base-ubuntu',
  name: 'workspace-runner',
  mounts: [
    {
      workspaceId: '9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e',
      path: '/workspace',
    },
  ],
});

await sandbox.waitForReady();
await sandbox.exec('ls -la /workspace');
```

An agent linked to `workspace-runner` can use `/workspace` for durable repo files, generated artifacts, and task notes. Threads preserve conversation context; workspaces preserve files.

## Storage API

Workspace file endpoints use the storage service:

```text theme={null}
https://storage.runtools.ai/v1/workspaces
```

They accept the same customer auth style as the control plane: `Authorization:
Bearer <session-or-api-key>` or `X-API-Key: <api-key>`.

List files:

```bash theme={null}
curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src?showHidden=false" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

Inspect workspace or path size:

```bash theme={null}
curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/info/src?showHidden=false" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

Create a folder:

```bash theme={null}
curl -X POST https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "notes",
    "type": "folder"
  }'
```

Upload a file:

```bash theme={null}
curl -X POST https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/upload/src \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -F "file=@./local-file.txt"
```

Rename a file:

```bash theme={null}
curl -X PUT https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src/local-file.txt \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "rename",
    "name": "renamed.txt"
  }'
```

Move or copy multiple files:

```bash theme={null}
curl -X PUT https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "move",
    "target": "/archive",
    "ids": ["/src/renamed.txt"]
  }'
```

Download a file:

```bash theme={null}
curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/direct?id=/src/local-file.txt&download=true" \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -o local-file.txt
```

Delete files by ID:

```bash theme={null}
curl -X DELETE https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["/src/local-file.txt"]
  }'
```

## Permissions

File APIs require `files:read`, `files:write`, `files:*`, or `*`. WorkOS
dashboard sessions can read and write files for visible workspaces; API keys
must carry the required scopes.

Personal workspaces are owner/admin scoped and are not mountable into sandboxes.
Org workspaces can be mounted at `/workspace` or a safe subpath under
`/workspace`.

## Safety Limits

* Paths are normalized inside the workspace root. `..`, null bytes, and escaped
  paths are rejected.
* Uploads default to 100 MB unless the deployment config raises the limit.
* Batch move/copy/delete operations default to 250 files per request.
* If storage quota is exceeded, write operations return an error and the
  workspace becomes effectively read-only until usage is reduced or credits are
  added.
* Workspace deletion is soft-deleted in metadata and removes the backing storage
  root. Deleting a workspace that is still mounted or referenced returns
  `WORKSPACE_IN_USE` unless the caller confirms with `force=true`.