agent-fs Co-deployment

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:

Docker Compose

docker-compose.local.yml and docker-compose.example.yml include MinIO and agent-fs. 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

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.

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