agent-fs Co-deployment
Run agent-fs alongside Agent Swarm for persistent shared files, task attachments, previews, and semantic search
agent-swarm uses local-fs by default when no agent-fs endpoint is configured. That keeps fresh installs self-contained, but files stay local to the API process. Set AGENT_FS_API_URL and let the API boot seeder provision API_AGENT_FS_API_KEY plus per-agent AGENT_FS_API_KEY secrets to enable the richer provider.
Document delivery
Agent prompts direct short answers to the task output and documents such as reports, summaries, research, and drafts to Markdown files in agent-fs. Without agent-fs, documents use Markdown task attachments. Pages are reserved for polished artifacts shared with a wider audience or explicitly requested; interactive tools use apps.
What Changes
With agent-fs enabled, task attachments and /api/fs/* use a shared filesystem provider instead of the local data directory. The dashboard can upload, preview, download, and delete task files. Workers can also write agent-fs pointers through store-progress; before changing task state, the server verifies that every pointer exists in the exact organization and drive supplied on the attachment or resolved from the registering agent's configured defaults. If scope, credentials, or a file is missing, the entire call fails without registering any attachment or terminal result.
Assigned-task prompts now also include a ready-to-run download recipe for each attachment using the provider-agnostic raw route:
curl -s \
-H "Authorization: Bearer ${AGENT_SWARM_API_KEY:-$API_KEY}" \
-H "X-Agent-ID: $AGENT_ID" \
"$MCP_BASE_URL/api/fs/tasks/<taskId>/files/<attachmentId>/raw" \
-o /tmp/<filename>That lets workers fetch task files in one call without discovering the underlying storage provider, org, or drive first.
The first-class agent-fs integration has two deliberate v1 limits:
| Limit | Value |
|---|---|
| Signed URL expiry | 1 hour maximum |
| API upload file types | All types allowed; the session composer accepts a narrower list |
| Upload size | 50 MB maximum |
Docker Compose
docker-compose.local.yml and docker-compose.example.yml include MinIO and agent-fs. For a self-hosted install, use docker-compose.example.yml, the reference deployment, and deploy every agent in it by default. The API waits for agent-fs, sets AGENT_FS_API_URL=http://agent-fs:7433, and registers a service key on first boot when API_AGENT_FS_API_KEY is not supplied.
The minio-init service turns on object versioning for the bucket. agent-fs needs it for content diffs and revert, which Comb uses to review agent edits. agent-fs checks versioning once at startup. On a running stack, run docker compose -f docker-compose.local.yml up -d minio-init && docker compose -f docker-compose.local.yml restart agent-fs. Versions written before that keep no stored content. For your own S3 bucket (for example with Helm), turn on versioning before agent-fs starts.
docker compose -f docker-compose.local.yml up --build
curl http://localhost:7433/healthThe local recipe uses:
AGENT_FS_API_URL=http://agent-fs:7433
AGENT_FS_REGISTER_EMAIL=swarm-admin@agent-fs.local
S3_ENDPOINT=http://minio:9000
S3_BUCKET=agentfs
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
EMBEDDING_PROVIDER=localdocker-compose.example.yml takes the MinIO login, and the agent-fs S3 key, from MINIO_ROOT_USER and MINIO_ROOT_PASSWORD in .env. Both are required.
Set API_AGENT_FS_API_KEY if you want to pre-provision a stable API-owned bootstrap key. Otherwise, the API seeder calls /auth/register, stores the generated key as an encrypted global swarm config secret, creates the shared org and drive, and persists AGENT_FS_DEFAULT_ORG_ID plus AGENT_FS_DEFAULT_DRIVE_ID. Workers do not receive this bootstrap key; the runner asks the API to create an agent-scoped AGENT_FS_API_KEY for each agent. If an agent's canonical registration already exists but its key was lost, provisioning registers a UUID-suffixed recovery identity, invites it to the shared organization as an editor, and stores the new agent-scoped key.
Bundled agent-fs behind the swarm API
The API enables the proxy by default when AGENT_FS_API_URL is nonblank. Set AGENT_FS_PROXY=false to disable it. The browser reaches agent-fs at <public API URL>/agentfs, without another public port or tunnel.
| Path on the API | Goes to agent-fs | Auth |
|---|---|---|
/agentfs/* (GET, POST, PUT, PATCH, DELETE) | /* | agent-fs's own af_ key |
/share/* (GET) | /share/* | none: public share links |
/site/* (GET) | /site/* | none: public site links |
- Bodies stream both ways, including the events stream that Comb uses for live updates.
- The API forwards only an
Authorization: Bearer af_...header, never the swarm API key, anaswt_token, cookies orX-Agent-ID. - The swarm's CORS rules apply on
/agentfs/*. On/share/*and/site/*, agent-fs's own CORS headers apply, because site pages run in a sandboxed, opaque origin. - Share tokens are redacted from the API access log.
- Comb uses
<public API URL>/agentfs(fromPUBLIC_MCP_BASE_URL, elseMCP_BASE_URL) when the swarm'sAGENT_FS_PUBLIC_URLis blank. An explicit value still wins.
agent-fs has its own AGENT_FS_PUBLIC_URL, with a different meaning: the base for the absolute share links that agent-fs builds. Set it to <public API URL>/agentfs on the agent-fs container, so share links point at the API. Share pages load their files from /share/<token>/raw and /site/<token>/, which the API serves too.
# swarm-api
AGENT_FS_API_URL=http://agent-fs:7433
AGENT_FS_PROXY=true
COMB_ENABLED=true
# agent-fs
AGENT_FS_PUBLIC_URL=https://swarm.example.com/agentfsagent-fs POST /auth/register is public, and agent-fs does not check that the caller owns the email. The swarm invites its users' emails to the shared drive, so an account made first with a teammate's email would get that teammate's seat. The proxy therefore asks for a swarm credential on POST /agentfs/auth/register: the operator API key can register any email, and a user token (aswt_) can register only the user's own email or an alias. The API also limits that route to 5 requests per minute per client IP. An agent-fs that is reachable without the proxy keeps the public route, so keep it on a private network.
The swarm API also provides these routes for authenticated users:
GET /api/fs/mereturns the user identity and membership state for agent-fs.POST /api/fs/keysaccepts alabeland creates a named key scoped to the organization. The response returns the key once. The swarm never stores the key.
New installs: onboard bundle
agent-swarm onboard --yes, which the one-shot install.sh runs, writes a compose file with two more services. Pass --no-agent-fs to leave them out. The interactive wizard does not add them.
| Service | What it runs | Host port |
|---|---|---|
agent-fs | agent-fs on local disk (AGENT_FS_STORAGE_PROVIDER=local, volume agent_fs_data), with its built-in local embeddings. No MinIO. | none: the browser goes through /agentfs on the API |
tei | Text Embeddings Inference with nomic-ai/nomic-embed-text-v1.5, for swarm memory. mem_limit: 2g, --max-batch-tokens 2048, --max-client-batch-size 256. | none |
The API gets AGENT_FS_API_URL=http://agent-fs:7433, AGENT_FS_PROXY=true, COMB_ENABLED=true, AGENT_FS_LINK_TARGET=dashboard and the EMBEDDING_* settings for TEI, including the nomic query and document prefixes. Each agent gets AGENT_FS_API_URL, APP_URL and AGENT_FS_LINK_TARGET. With APP_URL set, agents link files to the dashboard even without AGENT_FS_LINK_TARGET. An APP_URL saved on the Configuration page reaches running agents at their next poll. The API starts after agent-fs is healthy, so the boot seeder can provision it. It does not wait for TEI: the first boot downloads the model weights, and memory search uses keywords only until TEI is ready. TEI publishes one image tag per CPU architecture, so on an arm64 host .env sets TEI_IMAGE to the arm64 tag.
The bundle adds about 1 GB of RAM at idle, 2.5 GB of images and 1.5 GB of volumes. The first boot downloads about 1.5 GB. Existing installs do not change: when docker-compose.yml exists, install.sh skips onboarding and only starts the stack. With --tunnel, the installer also recreates agent-fs, so its AGENT_FS_PUBLIC_URL uses the tunnel URL.
Local storage cannot make public signed URLs. On a bundled install, agent-fs signed-url returns a link that needs a login: kind: "app", <AGENT_FS_APP_URL>/file/~/..., which opens Comb. For a file URL that works with no login, agents use agent-fs share-create. The swarm API serves share links at /share/*. Comb is not affected: it loads files through the proxy with the person's own key.
Late Provisioning and Shared-Org Invitations
If agent-fs is provisioned after the first filesystem request, provisioning now exports AGENT_FS_API_URL and clears the cached provider selection. POST /api/config/reload does the same after reloading global config. The next filesystem request can therefore switch from local-fs to agent-fs without restarting the API process.
A tenant-authenticated control plane can invite a customer into the shared organization without reading the API-owned bootstrap key:
curl -s -X POST "$MCP_BASE_URL/api/fs/members/invite" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"customer@example.com","role":"editor"}'role accepts viewer, editor, or admin and defaults to editor. The API performs the invite with its bootstrap identity, never returns a key, and handles repeat calls by skipping the invite when the member's existing role already satisfies the request (status: "already_member", invited: false).
An email that already has an agent-fs account joins the org at once (status: "added"). From agent-fs 0.18.9, an email with no account gets a pending invite instead (status: "pending"), with an acceptUrl when agent-fs has an app URL configured. agent-fs sends no email, so pass the acceptUrl to the person yourself. See the POST /api/fs/members/invite API reference for the response schema.
Helm
Enable the co-deployed service with agentFs.enabled=true:
agentFs:
enabled: true
image:
tag: 0.18.37
bucket: agentfs
s3:
existingSecret: agent-fs-s3
endpoint: https://s3.amazonaws.com
region: us-east-1
embedding:
provider: localThe referenced secret can contain:
kubectl create secret generic agent-fs-s3 \
--from-literal=S3_ACCESS_KEY_ID=... \
--from-literal=S3_SECRET_ACCESS_KEY=... \
--from-literal=S3_ENDPOINT=https://s3.amazonaws.com \
--from-literal=S3_REGION=us-east-1For hosted embeddings, set agentFs.embedding.provider to openai or gemini, set agentFs.embedding.model, and provide agentFs.embedding.apiKey or EMBEDDING_API_KEY in the existing secret.
helm template charts/agent-swarm --set agentFs.enabled=true | rg 'agent-fs|API_AGENT_FS_API_KEY|EMBEDDING_'Migration Note
Older deployments could implicitly assume hosted live.agent-fs.dev behavior. The no-config default is now local-fs. To keep shared agent-fs behavior after upgrading, set AGENT_FS_API_URL and provide or let the seeder create API_AGENT_FS_API_KEY; per-agent AGENT_FS_API_KEY rows are created by the runner provisioning endpoint.
For production, back up both systems:
- Agent Swarm SQLite database and
SECRETS_ENCRYPTION_KEY - agent-fs SQLite database plus its S3/MinIO bucket
Verify
curl http://localhost:3013/api/fs/capabilities \
-H "Authorization: Bearer $API_KEY"The response should show providerId: "agent-fs" when the provider is active. If it shows local-fs, check AGENT_FS_API_URL, the stored API_AGENT_FS_API_KEY, and the API boot logs for the provisioning seeder. After late provisioning or a config reload, repeat this request; a process restart is no longer required to re-select the provider.