> ## 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
> Persistent storage for sandboxes, agents, and project work
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:
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
| 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.
```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"
}'
```
List workspaces:
```bash theme={null}
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`.
```bash CLI theme={null}
runtools sandbox create \
--name repo-env \
--template base-ubuntu \
--mount 9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e:/workspace
```
```typescript SDK theme={null}
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');
```
```bash cURL theme={null}
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:
```typescript theme={null}
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.
```text theme={null}
https://storage.runtools.ai/v1
```
List a directory:
```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"
```
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=@./README.md"
```
Download a file:
```bash theme={null}
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:
```bash theme={null}
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
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
Create, list, rename, delete, and inspect workspace references.
List directories, upload files, download files, and mutate workspace contents.