# Fystash

> Multi-agent sandbox fabric: Firecracker microVMs, a shared POSIX room drive, and fabric messaging. Not an LLM. Production topology is GCP nested KVM (`topology=nested`) — do not claim bare metal.

Canonical docs: https://docs.fystash.ai  
Full page index: https://docs.fystash.ai/llms.txt  
Short agent contract (this file): https://fystash.ai/llms.txt (alias: https://fystash.ai/llm.txt)

## Prerequisites

A human must already have an org API key (`key-…`) from https://fystash.ai/account or Billing success after signup. Agents cannot create accounts, mint keys, or complete Stripe checkout. With a key, drive everything via MCP or REST against the public control plane.

## Credentials

```bash
export FYSTASH_API=https://api.fystash.ai
export FYSTASH_API_KEY='key-…'
```

Auth on every request: `Authorization: Bearer <FYSTASH_API_KEY>`

Talk to `https://api.fystash.ai` only. Do not use fystash.ai Next.js `/api/*` cookie routes from an agent.

## Preferred interface: MCP

```bash
pip install fystash-mcp
# or
uvx fystash-mcp
```

Cursor / Claude Desktop `mcp.json`:

```json
{
  "mcpServers": {
    "fystash": {
      "command": "uvx",
      "args": ["fystash-mcp"],
      "env": {
        "FYSTASH_API": "https://api.fystash.ai",
        "FYSTASH_API_KEY": "key-…"
      }
    }
  }
}
```

Prefer MCP tools over inventing curl when the server is configured. Never invent or commit API keys. See https://docs.fystash.ai/get-started/connect-agent

## Must-check first

1. `health` — confirm API up; note `topology=nested` and pool readiness
2. `usage` — credits, entitlement, quotas
3. Stop and tell the user what to do if 402 risk, zero credits, or not entitled (they use https://fystash.ai/billing)

## Core workflow

1. `room_create` with a unique `room_id` (e.g. `room-hello-<shorthex>`)
2. `sandbox_create` / from-template: `agent_id`, unique `guest_cid`, `template_id`, `memory_mib`
3. `sandbox_exec` (e.g. `echo hello`) — confirm exit 0
4. Leave running unless the user asks to destroy; then `room_destroy` or `sandbox_destroy`

The webapp (Dashboard / Rooms / Logs) is a **prompt hub**. Never ask the user to click Create, Exec, or dig logs in the UI — do that with MCP.

## Templates

| template_id | Use | Typical memory_mib |
|-------------|-----|--------------------|
| default | Coding (`git` / `curl` / `python3` / `node`) | 256 |
| browser | Chromium + CDP preview | 2048 |
| desktop | XFCE + computer-use + noVNC | 1536 |
| docker | Docker Engine in-guest | 2048 |

Optional create args: `env_json` (string map; no `FYSTASH_*` keys), `egress_allowlist_json` (IPv4/CIDR/hostname list).

## Rules

- `guest_cid`: unique int per sandbox in the room, typically `9100–9999`; do not reuse an in-use cid
- Prefer MCP over curl when available
- Do not claim bare-metal latency
- Summarize audit/status for the user; do not dump raw logs unless asked
- Never ask the user to operate sandboxes in the webapp UI

## MCP tool map

| Need | Tool | REST twin |
|------|------|-----------|
| Health / pool | `health` | `GET /health` |
| Org usage / entitlement | `usage` | `GET /v1/orgs/{org_id}/usage` |
| List rooms | `room_list` | `GET /v1/rooms` |
| Room lifecycle | `room_create`, `room_get`, `room_destroy` | `/v1/rooms` |
| Sandbox | `sandbox_create`, `sandbox_exec`, `sandbox_destroy` | from-template / exec / delete |
| Fabric | `agent_send`, `agent_request`, `agent_fanout`, `agent_wait`, `barrier_arrive` | fabric APIs |
| Drive | `fs_read`, `fs_write`, `fs_list` | room drive |
| Audit | `audit_list`, `org_audit_list` | room / org audit |

## Minimal REST hello

```bash
curl -fsS "$FYSTASH_API/health"

ROOM=room-hello-$RANDOM
curl -fsS -X POST "$FYSTASH_API/v1/rooms" \
  -H "Authorization: Bearer $FYSTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"room_id\":\"$ROOM\"}"

curl -fsS -X POST "$FYSTASH_API/v1/rooms/$ROOM/sandboxes/from-template" \
  -H "Authorization: Bearer $FYSTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"a1","guest_cid":9100,"memory_mib":256}'

curl -fsS -X DELETE "$FYSTASH_API/v1/rooms/$ROOM" \
  -H "Authorization: Bearer $FYSTASH_API_KEY"
```

## TypeScript SDK

```bash
npm install @fystash_ai/sdk
```

```ts
import { RoomClient } from "@fystash_ai/sdk";

const client = new RoomClient({
  baseUrl: process.env.FYSTASH_API!,
  apiKey: process.env.FYSTASH_API_KEY!,
});
const room = `room-hello-${Date.now()}`;
await client.createRoom(room);
await client.createFromTemplate(room, "a1", { guestCid: 9100, memoryMib: 256 });
await client.destroy(room);
```

## Product links

- Docs: https://docs.fystash.ai
- Quickstart: https://docs.fystash.ai/get-started/quickstart
- Connect agent: https://docs.fystash.ai/get-started/connect-agent
- Pricing: https://fystash.ai/pricing
- Sign up: https://fystash.ai/signup
- Account (keys): https://fystash.ai/account
- Dashboard (prompt hub): https://fystash.ai/dashboard
- Billing: https://fystash.ai/billing
- Support: mailto:support@fystash.ai

## Optional task patterns

Once MCP is configured with the user's key:

- **Org status:** health → usage → room_list; short status only
- **Create room:** health + usage; room_create; sandbox_create agent_id=a1 guest_cid=9100 memory_mib=256; exec hello; report room_id
- **Diagnose:** health → usage → room_list; classify healthy / degraded / blocked; say exactly what the human should do next
- **Plan multi-agent work:** propose room id, agent roles + guest_cids, fabric/barriers, drive layout, success criteria — do not implement until the user says go