Disks

A platform-provisioned shared file system for workflows and agents. Top-level disk blocks declare it; disk nodes run commands on it; agents mount it in their sandboxes.

A disk block declares a shared file system that Swirls provisions when you deploy. Use it for working files that workflows and agents need to share.

type: disk nodes run shell commands against the disk. Agents mount it in their sandboxes. Disk commands execute on Swirls Cloud.

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.

Field	Required	Notes
`label`	No	Display string. Defaults to the disk's name.
`region`	No	Quoted region hint, e.g. `"aws-us-east-1"`. The platform picks a default when omitted.

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"
  }
}

Field	Required	Notes
`disk`	Yes	Bare identifier naming a declared `disk` block.
`command`	Yes	Quoted string (run as-is) or `@ts` block returning the command string.

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: "openai/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.