Skip to main content

Workspaces

A workspace is a persistent folder of files. It lives in object storage, and each run mounts it into a sandbox. Everything the agent writes there survives the sandbox, including notes, generated files, memory/ and staged skills. Agents that attach the same workspace share the same files.

A workspace alone stores files. The agent needs a sandbox to mount it with full read and write tools; without one it can only read.

broods/index.ts
import { defineAgent, defineSandbox, defineWorkspace } from "broods";

export const box = defineSandbox({ name: "box", provider: "lambda" });

export const notes = defineWorkspace({
name: "notes",
storage: { provider: "s3" }, // the default, may be omitted
});

export const myAgent = defineAgent({
name: "my-agent",
sandboxes: [box],
workspaces: [notes],
});

The first workspace is the default when a tool call leaves out the workspace argument.

Which sandbox mounts a workspace​

Each workspace entry resolves to an effective sandbox:

workspaces: [
notes, // inherit the agent's first sandbox
{ workspace: team, sandbox: lockedDown }, // pin its own sandbox
{ workspace: docs, sandbox: null }, // read-only, no compute
],
EntryEffective sandbox
bare workspacethe agent's first sandbox, or read-only when the agent has none
sandbox: <sandbox>that sandbox, with its own permissionMode
sandbox: nullnone. Reads go straight to storage. Cheapest, but they lag recent writes

That lets one agent give different workspaces different sandboxes and approval rules, lets two agents reach one workspace through their own sandboxes, and makes a workspace read-only.

Tools per workspace​

Effective sandboxTools
a sandboxread, write, edit, glob, grep, bash, memory_save
noneread and glob through a read-only mount, which sees writes at once
none, sandbox: nullread and glob straight from storage, no cold start, reads can lag
none, your own bucketread and glob straight from storage, reads can lag
Agent hasTools
sandboxes, no workspacebash, a fresh machine each call unless the sandbox is persistent
sandboxes and workspacesthe workspace tools, plus bash on the other sandboxes by name
neithernone

The file tools list every workspace, so the model picks one with the workspace argument, and each call runs on that workspace's sandbox with its permissionMode. Writing to a read-only workspace returns "workspace is read-only", and bash there returns "no sandbox available for this command". Neither asks for approval.

Own machine or borrowed​

It matters whether the workspace's sandbox is the agent's own first sandbox:

SetupWhat the agent gets
sandboxes: [a], workspace on a or inheritedIts own machine with the workspace mounted. On a persistent a, bash may write anywhere on the machine
workspace on b, no sandboxesb only runs the workspace. bash writes outside the workspace are refused, except /tmp and /var/tmp
sandboxes: [a], workspace on bBoth. The workspace is scoped as above, and a stays reachable with bash sandbox: "<name>"

The refusal exists because the workspace is the only storage that outlives a sandbox. sandboxes: [a, b] with a workspace on b is rejected, since b would be reachable both with and without the mount.

Disk workspaces​

storage: { provider: "disk" } keeps a workspace's files on its sandbox's own disk instead of a bucket. It needs a persistent worker sandbox: no mount and no container, so every file tool answers in a fraction of a second.

export const disk = defineSandbox({
name: "disk",
provider: "worker",
persistent: true,
});
export const project = defineWorkspace({
name: "project",
storage: { provider: "disk" },
});
  • Each workspace folder, partition and user conversation is its own disk, up to 24 MiB.
  • read, write, edit, glob, grep and bash all work. edit and glob read the file out and compute in Broods, since the shell has no node.
  • There is no bucket behind it: download links and the workspace files API read nothing, and the memory harness (memory_save and its prompt) is off. Reach a user's files with GET and PUT .../files on the agent's URL, with the runtime key and that user's token.

Partitioning​

By default every run mounts the same folder. Partitioning gives each conversation, ticket or team its own folder under one workspace, so a GitHub issue cannot read another issue's files. It separates files, memory/ and TASKS.md. The agent's prompt, tools, credentials and skills stay shared.

Turn it on with partitioned: "conversation" on the workspace and a partition on every connection the agent uses:

export const support = defineWorkspace({
name: "support",
partitioned: "conversation",
});

export const slack = defineSlackConnection({
partition: { by: "shared" },
botToken: env("SLACK_BOT_TOKEN"),
signingSecret: env("SLACK_SIGNING_SECRET"),
});

export const github = defineGitHubConnection({
partition: { by: "conversation", alias: "support" },
webhookSecret: env("GITHUB_WEBHOOK_SECRET"),
appId: env("GITHUB_APP_ID"),
privateKey: env("GITHUB_PRIVATE_KEY"),
});
  • by: "shared" mounts the workspace root. That run sees root files and every child folder.
  • by: "conversation" mounts only a private child folder under alias/. It cannot see the root or its siblings.
  • alias is the folder name under the root. It may contain letters, digits, dots, underscores and hyphens.
RunAgent seesMounted folder
Direct API or cronworkspace supportroot
Direct API with a user tokenworkspace supportusers/<hash of the conversation>/
Slack, any thread in C456workspace supportroot
GitHub issue owner/repo#123workspace supportsupport/<hash of owner/repo#123>/
GitHub issue owner/repo#456workspace supportsupport/<hash of owner/repo#456>/

A run that carries a user token always mounts its own conversation's folder under users/, whatever partitioned says, so one end user never sees another's files. Its subagents mount that user folder too, under their own agent folder when the workspace is partitioned: "agent". A persistent agent sandbox gets one reservation per user conversation too, unless its options.reservationKey pins one to share.

A new child folder starts empty. Files at the root are not copied in. A channel record can also set partition for one place.

broods dev checks the rules. A workspace with partitioned: "conversation" needs partition on every attached connection, and a connection with partition needs at least one partitioned workspace.

Per agent​

partitioned: "agent" splits the workspace by agent instead of by conversation. Every agent that attaches it gets its own folder under agent/, with its own sandbox, S3 prefix and mount credentials, so two agents on one workspace cannot read each other's files. It needs no partition on the connections, and every conversation of one agent shares that agent's folder.

export const scratch = defineWorkspace({
name: "scratch",
partitioned: "agent",
});

When a child folder is deleted​

ChannelEnd of conversationFolder deleted
GitHub issue or pull requestclosedyes
Slack, Discord, Telegram, Pancake, Zalo, Linear, WhatsApp, Teams, Google Chat, Twilio, Messenger, Instagramnever, threads do not endno

Only conversation folders are ever deleted, shortly after the close event. On chat channels they pile up one per thread, so prune them from the dashboard Files view or the files API, or use shared there.

Bring your own bucket​

A workspace can live in an S3 bucket you own. Your bucket needs your credentials:

export const notes = defineWorkspace({
name: "notes",
storage: {
provider: "s3",
bucket: "acme-workspaces",
region: "us-west-2",
prefix: "agents/", // required, the mount is scoped to bucket/prefix/
auth: {
type: "assumeRole",
roleArn: "arn:aws:iam::111122223333:role/broods-mount",
},
},
});
auth.typeCredentialsUse
managed, defaultthe platform's rolethe managed bucket only
assumeRoleyour IAM role, assumed for each runan AWS bucket
r2your R2 API token, from env varsa Cloudflare R2 bucket

A workspace with bucket is rejected unless:

  • auth.type is assumeRole and roleArn is a role outside the platform's AWS account, or auth.type is r2 (see below).
  • bucket is not one of the platform's own buckets.
  • endpoint, if set, is a public https URL. Other S3-compatible stores keep provider: "s3" and change endpoint.

With assumeRole, the platform assumes your role for each run and narrows the session to bucket/prefix*, so code in the sandbox only ever holds credentials for that prefix. No access keys are stored. Static access keys for MinIO and other stores are not supported. deny-all sandboxes cannot reach your bucket; use allow-all.

Trusting Broods​

Broods reaches every customer's role as the same AWS principal, so your role's trust policy must also require an external id that only your account's calls carry. Broods assigns that id to your account and sends it every time it assumes your role. You cannot set it yourself: a workspace whose auth sets externalId is rejected with a 400. Without this, another Broods account that learned your role ARN could mount your bucket (the confused deputy problem).

Read the id, the principal to trust and a ready-to-paste trust policy from the workspace's storage settings in the dashboard, GET /v1/account/storage-trust, or the SDK:

const { externalId, principalArn, trustPolicy } =
await account.getStorageTrust();

Set the role's trust policy to it:

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::<Broods account id>:root" },
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": { "sts:ExternalId": "<your external id>" }
}
}
]
}

The id is the same for every workspace of the account and does not change.

Migrating an existing assumeRole workspace

Workspaces created before Broods assigned the id used the externalId you chose, or none. Do this once per account:

  1. Read your id as above and put it in each role's trust policy, replacing any sts:ExternalId you set yourself.
  2. Drop externalId from each workspace's auth: remove it from your defineWorkspace and deploy, send "externalId": null in a PATCH /v1/workspaces/{workspaceId}, or press Remove in the dashboard.

Until the trust policy names the new id, mounts and file reads of that workspace fail. A workspace still storing externalId is rejected on its next save and its files cannot be browsed from the dashboard. R2 workspaces and the managed bucket are not affected.

Cloudflare R2​

Create an R2 API token with Object Read & Write on the bucket, store its S3 keys as env vars, and point the workspace at your account's R2 endpoint:

import { defineWorkspace, env } from "broods";

export const files = defineWorkspace({
name: "r2-files",
storage: {
provider: "s3",
bucket: "agent-files",
prefix: "broods/", // required
endpoint: "https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
auth: {
type: "r2",
accessKeyId: env("R2_ACCESS_KEY_ID"),
secretAccessKey: env("R2_SECRET_ACCESS_KEY"),
},
},
});
broods env set R2_ACCESS_KEY_ID
broods env set R2_SECRET_ACCESS_KEY

Over the API, write the keys as "${R2_ACCESS_KEY_ID}" references to account env vars set under /v1/env. A literal key is rejected, and so is any endpoint other than https://<32-character account id>.r2.cloudflarestorage.com (the eu and fedramp jurisdiction hosts work too). Leave region unset or auto. Only the two keys take env(). For each run the config plane signs R2 temporary credentials that last one hour and only reach bucket/prefix. The token's own keys never enter a sandbox. Revoking the token stops every credential minted from it. An env var the keys reference cannot be deleted while the workspace uses it.

These rules are checked when you save and again whenever the storage is used, so a workspace saved before a rule existed fails with the same error until you fix it.

Files and sharing​

The dashboard Files tab lists, previews, uploads, renames and deletes the same files the agent mounts. Selecting a file previews it below the tree, and Enter keeps it open as a tab so several files can be reviewed side by side. Uploads and previews are capped at 512 KiB per file; agents can write larger files through the mount, and those offer Download instead of a preview.

To hand a file to a person, mint a download link:

curl -X POST "$BROODS_BASE_URL/v1/workspaces/$WORKSPACE_ID/download-links" \
-H "Authorization: Bearer $ACCOUNT_SECRET" \
-H "Content-Type: application/json" \
-d '{"path": "documents/report.docx", "expiresInSeconds": 86400}'

It returns a short downloadPath such as /v1/downloads/K3n8…. Join it to the base URL. It lasts as long as you asked, 24 hours by default and 30 days at most, and anyone holding it can download that one file. Deleting the workspace or the account revokes it.

GET /v1/workspaces/{id}/files?path=… returns a presigned storage URL instead. It expires in five minutes and breaks when a chat or email client rewrites it, so use it only for machine fetches you make right away.

Freshness​

The agent always sees its own writes, because its tools read through the mount. A file written through the mount reaches storage when it is closed, so other readers, such as the dashboard Files tab, another sandbox, or memory/MEMORY.md loaded at the start of a turn, can briefly see the older version. Details are in Storage internals.

See Memory and sessions for what the agent stores in a workspace on its own.