> ## 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 SDK

> Persistent storage and files with `rt.workspaces`

`rt.workspaces` manages the persistent storage you mount into sandboxes and hand to agents as filesystem memory (see [Workspaces](/features/workspaces) for the concept). The bytes inside a workspace live under `rt.workspaces.files`.

## Manage workspaces

```typescript theme={null}
const ws = await rt.workspaces.create({ name: 'Docs Project', slug: 'docs-project' });

const all = await rt.workspaces.list();                 // auto-paged
const page = await rt.workspaces.listPage({ limit: 20 }); // cursor-aware
const one = await rt.workspaces.get(ws.id);

await rt.workspaces.update(ws.id, { name: 'Docs' });

const usage = await rt.workspaces.usage(ws.id);          // { bytes, fileCount, billableBytes }
const { events } = await rt.workspaces.activity(ws.id, { limit: 50 });

await rt.workspaces.delete(ws.id);                       // soft delete
```

`create()` provisions the backing storage root; if the org is over its storage quota, it fails before the workspace is usable. `delete()` returns `409 WORKSPACE_IN_USE` when a sandbox, agent, or installable agent still references the workspace — check `usage()` (and the REST [usage endpoint](/api-reference/workspaces/manage)) first, or force from the API.

## Files

`rt.workspaces.files` reads and writes the contents of a workspace. Paths are workspace-relative.

```typescript theme={null}
const files = rt.workspaces.files;

// List + inspect
const { entries } = await files.list(ws.id, { path: 'src', recursive: false });
const info = await files.info(ws.id, 'src/README.md');

// Read
const text = await files.readText(ws.id, 'src/README.md');
const bytes = await files.readBytes(ws.id, 'assets/logo.png');

// Write — content can be a string, Uint8Array, ArrayBuffer, or Blob
await files.write(ws.id, 'notes/todo.md', '# TODO\n- ship docs', { contentType: 'text/markdown' });
await files.write(ws.id, 'data/report.bin', bytes, { overwrite: false }); // 409 if it already exists

// Create a directory, delete a path
await files.mkdir(ws.id, 'cache');
await files.delete(ws.id, 'notes/todo.md');
```

<Note>
  Only **organization** workspaces can be mounted into sandboxes; **personal** workspaces are reserved for thread storage and personal files. With a scoped API key, reads need `files:read` and writes need `files:write`.
</Note>

## Mount into a sandbox

Mounting is what turns a workspace into an agent's durable memory:

```typescript theme={null}
const sandbox = await rt.sandbox.create({
  template: 'base-ubuntu',
  mounts: [{ workspaceId: ws.id, path: '/workspace' }],
});
```

Anything written under `/workspace` outlives the sandbox and reappears in any sandbox that mounts the same workspace. See [Workspaces](/features/workspaces) for the full memory model and the [Workspace Files API](/api-reference/workspaces/files) for the REST surface.

## Methods

| Method                                                   | Description                                                 |
| -------------------------------------------------------- | ----------------------------------------------------------- |
| `list(options?)` / `listPage(options?)`                  | List workspaces (auto-paged / cursor-aware)                 |
| `create(options)`                                        | Create a workspace + backing storage root                   |
| `get(id)`                                                | Get one workspace                                           |
| `update(id, options)`                                    | Update metadata                                             |
| `usage(id)`                                              | Bytes, file count, and billable bytes                       |
| `activity(id, options?)`                                 | Workspace activity events (`{ limit?, cursor? }`)           |
| `delete(id)`                                             | Soft-delete (409 if still referenced)                       |
| `files.list(id, options?)`                               | List a directory (`{ path?, recursive?, limit?, cursor? }`) |
| `files.info(id, path)`                                   | File metadata                                               |
| `files.readText(id, path)` / `files.readBytes(id, path)` | Read contents                                               |
| `files.write(id, path, content, options?)`               | Write a file (`{ contentType?, overwrite? }`)               |
| `files.mkdir(id, path, options?)`                        | Create a directory                                          |
| `files.delete(id, path)`                                 | Delete a path                                               |