# Fystash for coding agents

Fystash is the **agent-native sandbox platform**. A Sandbox is composed from Components and State.

Use **Sandbox** for the definition. A running instance is a **Run**.

Canonical lifecycle:

```text
Sandbox definition → Sandbox (`sandbox.yaml`, kind: Sandbox)
immutable version  → Revision
state line         → Branch
running Sandbox    → Run
proof/results      → Evidence
safety preview     → Plan
```

This file is public documentation (not a repository `AGENTS.md`).

## Retired nouns — do not use

Room, Episode, EpisodeSpec, World, and `sbx_` IDs are not current resources.
Do not call `/v1/rooms` or `/v1/episodes`. Do not describe Fystash as a fitness app.

## Never

- Guess Organization or Project identity.
- Call private operator, GCP, or host-agent endpoints.
- Invent Rooms, Episodes, World, or a Sandbox control-plane resource / `sbx_` IDs.
- Bypass Plan digest or approval.
- Retry blindly; do not replace unavailable GPU with CPU; do not silently switch Project.
- Put secrets in docs, git, or chat.

## Context

Create an account at https://fystash.ai/signup if you do not have one, then:

```bash
fystash login
fystash connect
fystash current
```

Prefer `fystash current` over guessing `FYSTASH_PROJECT_ID`. Server apps may use `FYSTASH_API_URL`, `FYSTASH_ACCESS_TOKEN`, and `FYSTASH_PROJECT_ID` explicitly. Do not read `~/.fystash/credentials.json` unless the caller opts into CLI context.

Production API: `https://api.fystash.ai/v1`
Hosted MCP: `https://mcp.fystash.ai/mcp`

## Start a Sandbox

```bash
fystash sandbox start --file sandbox.yaml
fystash sandbox exec <run-id> -- echo hello
fystash sandbox evidence <run-id>
fystash sandbox stop <run-id>
```

Preserve canonical Run IDs. Machine mode (`--json`) never silently approves a Plan.

## Plan / apply

`planDigest` on apply must be the digest of the Plan that was shown. Retrying apply on the same intent reuses one idempotency key. A new Plan object is a new intent.

## Interfaces

- CLI: `fystash` (`npx -y @fystash/cli`)
- MCP: `https://mcp.fystash.ai/mcp`
- TypeScript: `@fystash/sdk` (ergonomic `Fystash` client, not generated-transport internals)
- Convex: `@fystash/convex@^0.2.0` (Sandbox → Revision → Branch → Run → Evidence from actions)
- Python: `fystash` on PyPI
- Skills: https://github.com/fystash/agent-skills — `fystash skills install`

Prefer structured JSON (`fystash --json` / non-TTY). Preserve canonical error `code` and read remediation.

## Availability

Hosted Remote MCP, launch-grade CLI, Agent Skills, and TS/Python SDKs are proven.
Wave 7 is OPEN. PERF-M is BLOCKED-EXTERNAL. GPU is not promoted. 30-day soak is not complete. Public GA is **not** claimed.

## Docs

https://docs.fystash.ai/llms.txt
https://docs.fystash.ai/get-started/quickstart
https://fystash.ai/pricing