agent-swarm.devagent-swarm.dev
Guides

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:

LimitValue
Signed URL expiry1 hour maximum
API upload file typesAll types allowed; the session composer accepts a narrower list
Upload size50 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/health

The 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=local

docker-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 APIGoes to agent-fsAuth
/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, an aswt_ token, cookies or X-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 (from PUBLIC_MCP_BASE_URL, else MCP_BASE_URL) when the swarm's AGENT_FS_PUBLIC_URL is 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/agentfs

agent-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/me returns the user identity and membership state for agent-fs.
  • POST /api/fs/keys accepts a label and 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.

ServiceWhat it runsHost port
agent-fsagent-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
teiText 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:

values.yaml
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: local

The 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-1

For 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.

On this page