Disks

What it is. A shared file system for unstructured data, provisioned by the platform when you deploy. You declare a disk block; Swirls creates and manages the backing storage. No provider ids, no vendor API keys.

Use it when workflows and agents need shared state on disk, you want to control the contents of a file system from a workflow, or an agent needs a workspace. Agents are very good at navigating file systems, which makes a disk the natural shared memory between an agent and the workflows around it.

Works with type: disk nodes (which run shell commands against the disk) and agents (which mount shared disks into their sandboxes).

Disk commands run in deployed projects. Deploy to Swirls Cloud to exercise disks end to end.

Top-level disk block

A disk <name> { } block declares a shared disk. There is no type: field; the keyword identifies the block. Every field is optional, so disk shared_a { } is valid.

disk proj {
  label: "Project shared disk"
  region: "aws-us-east-1"
}

The platform provisions the backing disk on deploy. Provisioning is idempotent: a retried deploy reuses the same disk, and label or region metadata updates in place. Disk contents are entirely yours; Swirls imposes no layout or schema on files.

Using it from a workflow

A type: disk node binds to the block by bare identifier and runs one shell command against the disk:

disk proj {
  label: "Project disk"
}

workflow audit {
  label: "Audit disk contents"
  root {
    type: disk
    label: "List reports"
    disk: proj
    command: "ls -la reports"
  }
}

Use @ts when the command depends on upstream outputs:

node fetch_report {
  type: disk
  label: "Cat report"
  disk: proj
  command: @ts {
    const id = context.nodes.root.output.reportId
    return "cat reports/" + id + ".md"
  }
}

Standard shared node fields apply (label, description, secrets, review, failurePolicy). Do not set schema: on a disk node. The output envelope is fixed: { stdout, stderr, exitCode, timing }, where timing carries totalMs, queueMs, and executeMs. Command output is capped, so very large stdout or stderr is truncated.

Mounting disks into agents

Agents opt into shared disks with disks: on the agent block:

disk kb {}

agent helper {
  secrets: ai_creds
  model: "gpt-4o"
  disks: [ kb ]
}

• Every deployed agent also gets a dedicated platform-managed disk, not declared as a disk block, mounted at /mnt/agent in its sandbox.
• Each shared disk mounts at /mnt/disks/<diskName>, in disks: order.
• disks: entries must reference declared disk blocks; duplicates error.

An agent writes persistent working files to /mnt/agent and shares data with workflows and other agents through /mnt/disks/<name>.

Validation

• Disk names must match ^[a-zA-Z0-9_]+$; duplicates error.
• A disk node's disk: field must name a declared disk block.

Common mistakes

Setting id: or secrets: on a disk block. Both fields were removed. The parser errors with Disk block no longer accepts "id:" (or "secrets:"). The platform provisions the disk at deploy time; you never supply a disk id or a vendor API key.

Setting schema: on a disk node. The output envelope is fixed (stdout, stderr, exitCode, timing); declaring a schema errors.

Assuming a mount path in disk node commands. A type: disk node runs its command remotely against the disk; it does not see the /mnt/disks/<name> paths agents see. Use relative paths, as in the examples above.

Choosing between memory primitives

• Streams: structured workflow output you want to query and reuse. Swirls-managed.
• Disks: unstructured files and shared working space. You control the layout.
• Database: a relational store Swirls provisions and migrates for you.
• Postgres: the relational database you already have.

Further reading

• Node types: the disk node's fields
• Agents: sandboxes and disk mounts