Workspaces

Sandboxes are disposable; workspaces are what survives. A workspace is org-owned persistent storage you can mount into a sandbox like a filesystem, browse from the dashboard, and hand to an agent as memory that outlives any single run. Threads remember the conversation — workspaces remember the files. A workspace can be:

Used from	What it enables
Dashboard	Browse, upload, download, rename, move, copy, and delete files
Sandboxes	Mount an org workspace at `/workspace` or a subpath
Agents	Give sandbox-backed and managed agents durable storage
REST API	Manage workspace metadata through the control plane and file bytes through the storage API

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:

Create an organization workspace.
Create a sandbox with that workspace mounted at /workspace or a subpath.
Link an in_sandbox agent to that sandbox.
The agent reads and writes files under the mount path during its work.
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

Type	Visibility	Sandbox mounting
Organization workspace	Visible to organization members according to their role and resource access	Supported
Personal workspace	Visible to the owner and organization admins	Not 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 control-plane API. Creating a workspace also creates the backing storage root; if storage is unavailable or the organization is over its storage quota, the request fails before the workspace becomes usable.

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"

The list response includes both workspaces and a storage summary with used bytes, quota bytes, and whether storage is currently unlimited for the organization.

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

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

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

curl -X POST https://api.runtools.ai/v1/sandboxes \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "repo-env",
    "template": "base-ubuntu",
    "mounts": [
      {
        "workspaceId": "9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e",
        "path": "/workspace"
      }
    ]
  }'

Once mounted, the workspace appears inside the sandbox at the requested path. Personal workspaces are intentionally rejected by the mount resolver. 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. They accept the same API-key or bearer-token auth style, and require the files:read or files:write scopes shown below.

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"

Uploads are limited to 100 MB by default. If the organization has exceeded its storage quota, write operations return a quota error and the workspace becomes read-only until usage is reduced or credits are added. Rename, move, copy, and delete operations are exposed through the same /files route family. Mutating operations are path-safe: names cannot escape the workspace root, and large batch operations are bounded.

Delete Safety

Workspace deletion is soft-delete at the metadata layer and best-effort cleanup at the storage layer. Personal workspaces cannot be deleted through the workspace delete API. Before deleting an organization workspace, RunTools checks whether active sandboxes, installable agents, or custom agents still reference it:

curl https://api.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/usage \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

If the workspace is still referenced, DELETE /v1/workspaces/:id returns 409 WORKSPACE_IN_USE with a usage summary. Pass ?force=true only after you have intentionally detached or accepted the affected references.

Permissions

Scope	Access
`files:read`	List workspaces, inspect usage, list files, read file info, and download files
`files:write`	Create, upload, move, copy, rename, and delete files or workspaces
`files:` / ``	Full workspace access allowed by the caller’s organization role
`activity:read` / `*`	Read workspace activity events

Organization admins can use broader organization views where supported. Members only see workspaces allowed by their resource access.

Best Practices

Use workspaces for durable project files

Treat sandbox-local files as disposable unless they are written into a mounted workspace.

Mount at predictable paths

Use /workspace for the main project tree, or /workspace/data, /workspace/cache, and similar subpaths when a sandbox needs multiple mounts.

Keep personal files out of shared sandboxes

Personal workspaces are owner/admin scoped and are intentionally not mounted into sandboxes.

Getting Started

Platform

Core Features

Advanced

Persistent Storage For Sandbox Agents

Workspace Types

Create A Workspace

Mount Into A Sandbox

File Operations

Delete Safety

Permissions

Best Practices

Next Steps

Workspaces API

Workspace Files API

​Persistent Storage For Sandbox Agents

​Workspace Types

​Create A Workspace

​Mount Into A Sandbox

​File Operations

​Delete Safety

​Permissions

​Best Practices

​Next Steps

Workspaces API

Workspace Files API

Persistent Storage For Sandbox Agents

Workspace Types

Create A Workspace

Mount Into A Sandbox

File Operations

Delete Safety

Permissions

Best Practices

Next Steps