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.

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; the server fills in the shared org and drive IDs when they are available.

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.

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.

Helm

Enable the co-deployed service with agentFs.enabled=true:

agentFs:
  enabled: true
  image:
    tag: 0.9.0
  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.