introduction

Core model

Org → Room → Sandboxes[] + Fabric + Drive

Org (tenant)
  └── Room (workflow run)
        ├── Fabric         mailboxes, topics, fan-out, barriers
        ├── Drive          shared POSIX artifacts
        └── Sandboxes[]    Firecracker microVMs (one per agent)
              ├── guest daemon → fabric stream
              └── /mnt/drive

Org

Tenancy boundary. Holds API keys, credits, quotas, and org-scoped audit. You get an org when you sign up at fystash.ai.

Room

Run-scoped policy and artifact boundary. Create a room, spawn sandboxes into it, then destroy the room when finished. Room destroy tears down sandboxes; drive artifacts for that room go with it unless you copied them out.

Sandbox

Ephemeral isolated compute. Created from a template with a unique guest_cid (typically 9100–9999) and memory budget. Default network posture is controlled; optional egress allowlist and port preview are available.

Fabric

Low-latency messaging inside a room: directed send, request/reply, topic fan-out, and barriers. Identity is host-derived — guests cannot spoof another agent.

Drive

Durable shared filesystem for large artifacts. Prefer writing files to the drive and sending small fabric messages with paths/digests instead of shipping bulk bytes over the fabric.

Lifecycle (canonical)

1. Create room

2. Spawn coordinator + workers from templates

3. Coordinate over fabric; put large outputs on the drive

4. Barrier when N workers are ready

5. Destroy sandboxes / room when done

See Create & exec for the hello path.