Agent Durable Storage#

Each agent is provisioned with a dedicated, persistent S3-backed folder that survives across sessions and runs. This is distinct from the session working directory (cwd), which is ephemeral and lost when a session ends. 1

The feature was introduced in PR #5247 and gives every agent one durable folder keyed by its artifact ID.

How It Works#

Storage Layout#

The runner mounts the durable folder at <cwd>-agent and creates an agent-files symlink inside the session cwd pointing to it 2. The symlink is rebuilt every run because geesefs (the FUSE-based S3 mount driver) silently downgrades symlinks to empty files across remounts 1. An AGENTA_AGENT_MOUNT_DIR environment variable is also injected into the daemon, giving the agent three discovery signals without requiring any instructions text 1.

A README.md is seeded in the durable folder on first run explaining the persistence contract. 3

Infrastructure Requirements#

The runner container requires SYS_ADMIN capability, /dev/fuse device access, and apparmor:unconfined to support geesefs FUSE mounts 4.

API Layer#

The API uses a deterministic slug derived from the artifact UUID to ensure idempotency across repeated sign calls. The slug format is:

__ag__agent__{canonical_artifact_id}__{slugified_name}

Key service functions in api/oss/src/core/mounts/service.py 5:

• mint_agent_slug(artifact_id, name) — validates the artifact ID as a UUID and returns the deterministic slug. Raises MountArtifactIdInvalid for non-UUID artifact IDs.
• get_or_create_agent_mount(artifact_id, name) — idempotently upserts the durable mount for an artifact.
• fetch_agent_mount(artifact_id, name) — reads an existing mount without creating one.

Two HTTP endpoints in api/oss/src/apis/fastapi/mounts/router.py 6:

• POST /mounts/agents/sign?artifact_id=<uuid>&name=default — signs scoped S3 credentials for the agent mount (idempotent; same artifact always returns the same mount).
• POST /mounts/agents/query — reads the mount without creating it (used by the UI).

Runner Layer#

Core logic lives in services/runner/src/engines/sandbox_agent/agent-mount.ts 7:

Best-effort contract: Any failure in agent-mount setup (missing artifact ID, signing error, geesefs issue) logs and continues. Session cwd behavior is always preserved as a fallback. 1

Mount and unmount wiring is handled in services/runner/src/engines/sandbox_agent.ts — the durable mount is established before daemon creation and torn down after the session cwd during cleanup. 1

System Prompt Injection#

agent-mount-guidance.ts defines a platform system-prompt segment that is appended to the harness system prompt (never to CLAUDE.md/AGENTS.md) when an agent mount exists 11. The segment instructs the agent to:

• Use agent-files/ or $AGENTA_AGENT_MOUNT_DIR for anything it wants to keep across sessions.
• Check the durable folder before answering recall questions ("what did we decide", "do you remember X"). 12

Wiring is harness-specific 11:

• Pi: combined into plan.appendSystemPrompt
• Claude: passed as _meta.systemPrompt.append in the ACP session

UI Integration#

The Session Inspector's Mounts tab displays an "Agent files" panel above the session cwd panel. It calls POST /mounts/agents/query via fetchAgentMount(artifactId, projectId) in web/oss/src/components/SessionInspector/api.ts. 1

⚠️ Known bug (AGE-3983): In v105.8+, the latest-edited-files view incorrectly surfaces the agent-files symlink as the primary content instead of actual edited files. Tracked in issue #5480. 13

Key Files#