Skip to main content

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.

​
Overview

Use workspaces as storage that survives beyond one sandbox. For sandbox-backed agents, a mounted workspace is the agent’s persistent filesystem memory: the agent works through the sandbox, and the storage mounted at /workspace remains available for later runs. The main guide is Workspaces. The detailed REST reference is split between Manage Workspaces and Workspace Files.

​
Management API

Workspace metadata lives on the orchestrator 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"
  }'

​
Mount Into A Sandbox

Mount paths must be /workspace or a subpath under /workspace. 
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
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"
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"
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 *. Personal workspaces are owner/admin scoped and are not mountable into sandboxes.