> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Files and workspaces

> Persistent sandbox volumes, workspace paths, and how to read or write files from your application.

Each agent and stable `subjectId` receives an isolated persistent workspace on a
durable sandbox volume. Files written there survive session boundaries, sandbox
restarts, and agent version promotions. The same volume is mounted for later
sessions, automations, and Files API calls for that agent and subject.

Use this guide for the workspace model. Use the
[Files API](/api-reference/files) when your application needs to list, upload,
download, move, or delete files without sending a chat turn.

## Workspace model

The volume is the subject's home directory. Paths in the Files API and in the
built-in `file` / `terminal` toolsets are relative to that root:

| Path                 | Owner                                     | Purpose                                              |
| -------------------- | ----------------------------------------- | ---------------------------------------------------- |
| `/`                  | Subject workspace                         | Durable files the agent and your application share.  |
| `memories/USER.md`   | [Memory API](/guides/memory-and-learning) | User identity and preferences.                       |
| `memories/MEMORY.md` | [Memory API](/guides/memory-and-learning) | Agent-learned environment facts.                     |
| `skills/`            | Agent version                             | Configured Markdown skills written at sandbox start. |

Treat `memories/` and `skills/` as reserved. Read or seed memory through the
Memory API, and change configured skills through
[agent versions](/api-reference/skills). Application files belong in ordinary
workspace directories such as `uploads/`, `reports/`, or `projects/`.

## Choose an access path

| Goal                                         | Use                                                                                 |
| -------------------------------------------- | ----------------------------------------------------------------------------------- |
| Let the agent read and write during a turn   | Enable the `file` and `terminal` toolsets.                                          |
| Inspect or seed the volume from your backend | [Files API](/api-reference/files).                                                  |
| Attach a document to one turn only           | [Message attachments](/api-reference/send-message#send-a-message-with-attachments). |
| Store USER.md / MEMORY.md facts              | [Memory API](/guides/memory-and-learning).                                          |

Turn attachments are copied into the session event history. They are not
automatically written onto the volume. Ask the agent to save them, or upload
with the Files API when the file should persist for later sessions.

## Enable file tools

Configure the built-in `file` toolset on the agent:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "agent_toolset",
  "configs": [
    {
      "name": "file",
      "enabled": true,
      "permissionPolicy": { "type": "always_allow" }
    }
  ]
}
```

The toolset provides `read_file`, `write_file`, `patch`, and `search_files`.
`terminal` can also create and update files through the shell. See
[Built-in agent toolsets](/api-reference/tools#built-in-agent-toolsets).

## Seed files before the first session

You can write files onto a subject's volume before creating a session, the same
way you can [seed memory](/guides/memory-and-learning#seed-memory-before-the-first-session).
This is useful for project templates, customer documents, or datasets the agent
should already have on its first turn:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PUT \
  "https://api.herm.run/v1/agents/agent_123/users/user_123/files/content" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "path": "briefing/account.md",
    "encoding": "utf-8",
    "content": "Acme is on the Pro plan. Renewal is 12 September.",
    "createParents": true
  }'
```

The first write creates the volume if it does not exist yet. To hide sandbox
cold-start from the first user message, also
[prewarm](/api-reference/sessions#prewarm-an-agent) the agent for that subject.

## Persistence and scope

* Workspace files are scoped to the authenticated organization, agent, and
  stable `subjectId`.
* A new session with the same scope sees the existing workspace.
* Automations for that subject run against the same volume.
* A different subject receives a different workspace.
* Promoting an agent version does not reset a subject's workspace.
* Deleting a session does not delete the volume. The workspace lives with the
  agent and subject, not with any one conversation.

Reuse the same `subjectId` for the same person, team, or customer. Changing it
intentionally creates a separate filesystem boundary.

## Volume capacity

Each subject volume starts at 512 MiB and expands automatically toward a 4 GiB
ceiling as usage approaches capacity. Check current usage with
[`GET /v1/agents/{agentId}/users/{subjectId}/volume`](/api-reference/files#get-volume-usage).
Writes that would exceed the ceiling return `400 validation_error`.

## Send input files for one turn

To include a file in a turn without persisting it on the volume, add a base64
`data_url` attachment to `user.message`. Herm makes the material available to
the agent for that turn.

See [Send a message with attachments](/api-reference/send-message#send-a-message-with-attachments)
for the request schema, size limits, and supported media types.