Skip to main content
Every deployment has a persistent filesystem rooted at /workspace. These endpoints give your product direct access to it — sync agent outputs, seed input files, or clean up. All paths are relative to the workspace root.

​
List files

GET /v1/deployments/:deployment_id/files

const { entries } = await herm.files.list("dep_7xK9s2", { path: "videos/" });
ParameterTypeRequiredDescription
pathstringNoDirectory to list. Defaults to the root
{
  "path": "videos/",
  "entries": [
    { "name": "variation-1.mp4", "type": "file", "size": 8123456, "modified_at": "2026-06-11T20:58:09Z" },
    { "name": "drafts", "type": "directory", "modified_at": "2026-06-10T08:12:44Z" }
  ]
}

​
Read a file

GET /v1/deployments/:deployment_id/files/content
Returns the file contents. The SDK gives you the raw bytes plus a text() convenience: 
const file = await herm.files.read("dep_7xK9s2", { path: "storyboard.md" });

const markdown = await file.text();
// or: const bytes = await file.bytes();

​
Write a file

PUT /v1/deployments/:deployment_id/files
Creates or overwrites a file. Accepts a string, Uint8Array, or Blob; parent directories are created automatically. 
await herm.files.write("dep_7xK9s2", {
  path: "briefs/q3-brief.md",
  content: await Bun.file("q3-brief.md").text(),
});

{
  "path": "briefs/q3-brief.md",
  "size": 2048,
  "modified_at": "2026-06-11T21:15:30Z"
}

​
Delete a file

DELETE /v1/deployments/:deployment_id/files

await herm.files.delete("dep_7xK9s2", { path: "drafts/old-take.mp4" });
Pass a directory path to delete it recursively.

​
Watching for changes

Rather than polling, enable filesystem_webhooks in the deployment’s features to receive filesystem events on the SSE stream whenever the agent writes to the workspace: 
for await (const event of await herm.deployments.events.stream("dep_7xK9s2")) {
  if (event.type === "filesystem") {
    console.log(`${event.change}: ${event.path}`);
  }
}

​
Errors

StatusErrorWhen
400validation_errorInvalid or escaping path
404not_foundDeployment or path does not exist
413validation_errorFile exceeds the size limit
See Errors for the full error reference.