Workspaces & Files

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. The detailed REST reference is split between Manage Workspaces and Workspace 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:

curl https://api.runtools.ai/v1/workspaces \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

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.

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.

Getting Started

Platform

Core Features

Advanced

Management API

Mount Into A Sandbox

Storage API

Permissions

Safety Limits

​Management API

​Mount Into A Sandbox

​Storage API

​Permissions

​Safety Limits

Management API

Mount Into A Sandbox

Storage API

Permissions

Safety Limits