Volumes

A volume is a persistent disk attached to a container in an agent workload. Volumes survive across workload restarts (within the same thread) and let agents maintain working state — checkout caches, partial work, learned data — without storing it in a database.

Volume lifecycle

A volume in the platform has two layers:

  • Volume definition — the configuration record stored in the Agents service. Has a name, size, and mount path. Does not occupy disk until it is provisioned.
  • Volume instance — the actual provisioned disk on a runner. One definition can have multiple instances — typically one per thread the agent participates in.

Instances are created on demand by the orchestrator when an agent starts a workload that needs the volume. They are cleaned up when:

  • The volume definition is deleted, or
  • The thread is archived and the cleanup window passes.

You inspect instances under Monitoring → Storage.

Create a volume definition

In the Console

  1. Console → Volumes (/organizations/<org>/volumes).
  2. Click New volume.
  3. Set:
    • Name — display name.
    • Size — disk size in GB.
    • Mount path — where the volume is mounted in the container (e.g. /workspace).
  4. Save.

With Terraform

hcl
resource "agyn_volume" "workspace" {
  organization_id = agyn_organization.acme.id

  name       = "workspace"
  size_gb    = 10
  mount_path = "/workspace"
}

Attach a volume

Volumes by themselves do nothing — you must attach them to an agent or MCP server for them to mount inside the workload.

In the Console

  1. Console → Agents → <agent> → Volume attachments tab.
  2. Click Attach volume.
  3. Pick a volume and the target container (the agent itself or one of its MCPs).
  4. Save.

Attachments take effect on the next workload start.

With Terraform

hcl
resource "agyn_agent_volume_attachment" "workspace_on_support" {
  agent_id  = agyn_agent.support.id
  volume_id = agyn_volume.workspace.id
}

Attach to an MCP by specifying mcp_id instead of (or in addition to) agent_id.

Storage class and sizing

Volumes are provisioned as Kubernetes PVCs with the default ReadWriteOnce storage class on the runner's cluster. The size is fixed at creation; resizing is not currently supported — create a new volume and migrate data manually if you need more space.

When to use a volume

ScenarioVolume?
Agent needs to remember context across runs in the same threadYes
Agent works on a long-lived code workspace (git checkout, build artifacts)Yes
Agent calls an MCP whose state is purely in an external systemNo
You want to share state across threads or agentsNo — use external storage or a shared MCP backend instead

Per-thread volume instances are sized once and used independently. If you need shared state across threads, store it externally and let the agent read/write it through an MCP server.

Delete a volume

Deleting a volume definition removes its configuration. Existing instances are marked for deprovisioning; the runner removes the PVCs in the background.

In the Console

  1. Volumes list → kebab menu → Delete.
  2. Confirm. The Console warns about active instances.

With Terraform

Delete the resource block and apply. Terraform issues DeleteVolume.