Skip to main content

​
Overview

Each deployment has its own filesystem rooted at /workspace inside the agent’s container. It’s a real filesystem: the agent reads, writes, and organizes it with the standard file tools, everything persists across sessions, and your product gets direct access through the Files API. What lives in the workspace:
ContentDescription
OutputsStoryboards, scripts, drafts, rendered assets — what the agent produces
Working stateNotes, intermediate results, and to-dos the agent keeps across runs
SkillsSkill files loaded with source: "file"
Memory filesThe durable context behind Memory
The filesystem is per-deployment: customer A’s agent cannot read customer B’s files under any circumstance — isolation is by container, not by convention.

​
How the agent uses the workspace

The agent treats /workspace the way an employee treats their desk: it saves outputs there, keeps notes for itself, and picks up where it left off. A run can end with “saved to storyboard.md” and next week’s run starts by reading it. The agent’s file activity appears on the SSE stream as ordinary tool_call / tool_result events. Debugging often starts here too — reading the agent’s workspace is the fastest way to see what it was thinking.

​
Access files from your product

Read and write the workspace directly with the Files API: 
// Sync an agent output into your product
const file = await herm.files.read("dep_7xK9s2", { path: "storyboard.md" });
const markdown = await file.text();

// Seed an input file before a run
await herm.files.write("dep_7xK9s2", {
  path: "briefs/q3-brief.md",
  content: briefMarkdown,
});

// Browse the workspace
const { entries } = await herm.files.list("dep_7xK9s2", { path: "videos/" });

​
Watching for changes

Rather than polling, enable filesystem_webhooks in the deployment’s features to receive filesystem events on the SSE stream the moment the agent writes: 
for await (const event of await herm.deployments.events.stream("dep_7xK9s2")) {
  if (event.type === "filesystem") {
    console.log(`${event.change}: ${event.path}`);
  }
}
Use this to sync agent outputs into your product as they’re produced.

​
Lifecycle

EventEffect on the workspace
Run endsNothing — files persist
Restart or deployNothing — files persist
New threadNothing — threads share the deployment’s workspace
Deployment deletedDestroyed, unless retain_filesystem: true keeps a snapshot for 30 days
See Delete a deployment for retention details.