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 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	User identity and preferences.
memories/MEMORY.md	Memory API	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. 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.
Attach a document to one turn only	Message attachments.
Store USER.md / MEMORY.md facts	Memory API.

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:

{
  "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.

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. This is useful for project templates, customer documents, or datasets the agent should already have on its first turn:

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 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. 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 for the request schema, size limits, and supported media types.