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

Workspaces are persistent storage owned by your organization. In plain terms, a workspace is a storage space that can be mounted into sandboxes like a filesystem, browsed from the dashboard, and used by agents to keep project state across runs. A workspace can be:
Used fromWhat it enables
DashboardBrowse, upload, download, rename, move, copy, and delete files
SandboxesMount an org workspace at /workspace or a subpath
AgentsGive sandbox-backed and managed agents durable storage
REST APIManage workspace metadata and file operations
Sandbox-local storage disappears when a sandbox is destroyed. A mounted workspace is the durable filesystem boundary.

​
Persistent Storage For Sandbox Agents

For sandbox-backed agents, a workspace is the agent’s persistent filesystem memory. The agent uses its linked sandbox for shell commands and file tools, and the mounted workspace is the part of that filesystem that remains available across runs. The flow is:
  1. Create an organization workspace.
  2. Create a sandbox with that workspace mounted at /workspace or a subpath.
  3. Link an in_sandbox agent to that sandbox.
  4. The agent reads and writes files under the mount path during its work.
  5. When the sandbox is paused, resumed, or replaced, the workspace contents remain available for the next run.
This is the right place for repo checkouts, long-running task notes, generated files, caches you want to keep, and agent-maintained project state. Conversation threads preserve chat history; workspaces preserve files.

​
Workspace Types

TypeVisibilitySandbox mounting
Organization workspaceVisible to organization members according to their role and resource accessSupported
Personal workspaceVisible to the owner and organization adminsNot mountable
Personal workspaces are useful for private user storage. Use organization workspaces when a sandbox, shared project, or managed agent needs durable storage.

​
Create A Workspace

Workspace metadata is managed through the orchestrator API: 
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"
  }'
List workspaces: 
curl https://api.runtools.ai/v1/workspaces \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

​
Mount Into A Sandbox

Mounts are declared when the sandbox is created. Mount paths must be /workspace or a subpath under /workspace. 
runtools sandbox create \
  --name repo-env \
  --template base-ubuntu \
  --mount 9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e:/workspace
Once mounted, the workspace appears inside the sandbox at the requested path. Any sandbox-backed agent attached to that sandbox can use its file tools against the same path: 
await rt.agent.run(
  'code-assistant',
  'Open /workspace/README.md, update the setup notes, and run the tests.',
);
If you destroy the sandbox and later create a new sandbox with the same workspace mounted, the files under /workspace are still there.

​
File Operations

Workspace file endpoints use the storage service: 
https://storage.runtools.ai/v1
List a directory: 
curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src?showHidden=false" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
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=@./README.md"
Download a file: 
curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/direct?id=/src/README.md&download=true" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

​
Permissions

ScopeAccess
files:readList workspaces, inspect usage, list files, read file info, and download files
files:writeCreate, upload, move, copy, rename, and delete files or workspaces
files:* / *Full workspace access allowed by the caller’s organization role
Organization admins can use broader organization views where supported. Members only see workspaces allowed by their resource access.

​
Best Practices

Treat sandbox-local files as disposable unless they are written into a mounted workspace.
Use /workspace for the main project tree, or /workspace/data, /workspace/cache, and similar subpaths when a sandbox needs multiple mounts.
Personal workspaces are owner/admin scoped and are intentionally not mounted into sandboxes.

​
Next Steps

Workspaces API

Create, list, rename, delete, and inspect workspace references.

Workspace Files API

List directories, upload files, download files, and mutate workspace contents.