# Shardflux

> Shardflux gives AI agents persistent, isolated cloud computers called workspaces. An agent opens a workspace by key, runs commands and edits files in it, suspends it when idle, resumes it later with its files and processes intact, and forks it. The `shard` CLI (`npx @shardflux/cli@latest`) does everything the Shardflux dashboard does, from creating the account to running commands in a workspace, without a browser.

Shardflux (https://shardflux.dev) is a hosted service by Helios One Oy. It fits when an agent needs its own computer that keeps its state between tasks: one workspace per customer, project or task, each a Firecracker microVM with its own kernel, with tools for commands, files, processes, a terminal, git and a browser. Clients: the TypeScript SDK (`@shardflux/sdk`, Node.js 24+), the Python SDK (`shardflux`, Python 3.10+), the `shard` CLI, a local MCP server (`@shardflux/mcp`) and the HTTP API (`https://api.shardflux.dev/v1`). API keys (`sfk_<key id>_<secret>`) are server credentials, created in the console at https://app.shardflux.dev or with `shard setup`. It does not fit calls from a browser or mobile app, workspaces larger than 16 vCPU and 32 GiB RAM, or data that must stay outside AWS us-west-2.

Every docs page is also served as Markdown at its path plus `.md`.

**Agents: use the `shard` CLI.** This part is for AI agents and coding assistants that act for a person. People use the dashboard; the CLI does the same without a browser: sign-up, sign-in, two-factor authentication, organizations, projects, API keys, members, invitations, billing, usage and cost estimates, spend alerts, the audit log, account export and deletion, egress policies, volumes, secrets, templates and workspaces. It needs Node.js 24 or later. Run it with `npx @shardflux/cli@latest <command>`, or install it once with `npm install -g @shardflux/cli@latest` and run `shard <command>`; below, `shard` means either. On a terminal npx asks before it installs a package; `npx --yes @shardflux/cli@latest ...` skips the question. `shard --help` lists every command, and every command has its own `--help`.

**From no account to a running workspace.** Create the account, verify the email address with the link from the verification email (keep the quotes), sign in (the session is saved for the next commands), set up an organization, project and API key (created when missing, then saved), then open a workspace by key and run a command in it:

```sh
printf '%s\n' "$PASSWORD" | npx @shardflux/cli@latest auth register --email you@example.com
npx @shardflux/cli@latest auth verify-email '<link from the verification email>'
printf '%s\n' "$PASSWORD" | npx @shardflux/cli@latest auth login --email you@example.com
npx @shardflux/cli@latest setup
npx @shardflux/cli@latest ws open acme/demo --template python-node-browser
npx @shardflux/cli@latest ws exec acme/demo -- python3 -c 'print(40 + 2)'
```

- Passwords and keys never go in command arguments. Pipe the password on standard input as above, or type it at the prompt on a terminal (no echo). Keep it in an environment variable or a secret store, not in files, logs or shell history.
- With two-factor authentication on, `auth login` also needs `--code <code>` from the person's authenticator app (or `--recovery-code <code>`). Without it, `auth login` exits 4 with `mfa_required`, and `shard auth mfa --code <code>` completes the sign-in within 10 minutes.
- `shard setup` is safe to run again: it keeps a saved key that still works (`--new-key` makes a new one). It never prints the key.
- Credentials are saved in `~/.config/shardflux/credentials.json` by default (`SHARDFLUX_CONFIG_DIR` moves it; the file is readable only by you). `SHARDFLUX_API_KEY` and `SHARDFLUX_SESSION_TOKEN` override the saved key and session.
- Each `auth login` is a session the person can see and sign out in the dashboard (Settings > Account & security). It lasts 30 days from its last use. `shard auth sessions` lists the sessions; `shard auth logout` ends yours.
- Exports, deletions, email and two-factor changes need the password again. On a terminal the CLI asks; without one it exits 4 with `step_up_required`: run `printf '%s\n' "$PASSWORD" | shard auth step-up`, then retry.

**What needs a person.** Two steps. The verification email: ask the person for the link in it, or read it yourself if you have access to that mailbox (`shard auth resend-verification`, signed in, sends a new link; that link also sets a new password, which `auth verify-email` reads from standard input). Paying: `shard billing upgrade <plan>` prints a Stripe Checkout URL; a person opens it and pays. Do not enter card details yourself. Everything else runs from the CLI.

**Billing.** `shard billing plans` lists the plans and their keys, and `shard billing status` shows the organization's plan and subscription. `shard billing upgrade <plan> --wait` prints the Checkout URL, then waits: it exits 0 once the subscription is active, 6 when the checkout expired or was canceled, and 5 after `--timeout` (default 15m; the checkout stays open). `--open` opens the URL in the default browser, useful on the person's own machine. An organization that already has a subscription changes plans in the Stripe Customer Portal: `upgrade` then prints the portal URL instead, and `shard billing portal` prints it any time.

**SDKs and the MCP server.** `shard env` prints `export` lines for the saved key and the API URL: `eval "$(shard env)"` (`--shell fish` or `--shell powershell` for other shells). The Python SDK `shardflux` and the MCP server `@shardflux/mcp` read `SHARDFLUX_API_KEY`; the TypeScript SDK `@shardflux/sdk` takes it as `apiKey`. The SDKs' `ShardfluxAccount` class does the account steps from code, with a CLI session.

**Output, errors and exit codes.** Add `--json` for machine-readable output: stdout carries the API's JSON, and an error is one `{"error": {...}}` document on stderr. Exit codes: 0 success, 1 error, 2 usage, 3 not found, 4 authentication or permission, 5 timeout, 6 the awaited operation or checkout failed or was canceled, 130 interrupted. `ws exec` exits with the command's own code.

**Keep the CLI current.** The CLI says on stderr when a newer version is out or yours is no longer supported (it asks at most once a day). Update with `npm install -g @shardflux/cli@latest`; `npx @shardflux/cli@latest` always runs the newest. `shard version --check` checks now, and `SHARDFLUX_NO_UPDATE_CHECK=1` turns the check off. If `auth`, `setup` or `billing` is an unknown command, your CLI is older than 0.5.0: update it.

## Docs

- [Support and bug reports](https://docs.shardflux.dev/support.md): public bug and feature forms, private support, and security reporting
- [For coding agents](https://shardflux.dev/agents.md): when Shardflux fits and when it does not, plans and limits, runtimes, authentication, an account from the terminal, a complete example, MCP setup and a prompt to copy
- [Feedback](https://shardflux.dev/agents.md#feedback): send feedback straight to the Shardflux founder while you work with `shard feedback` (CLI 0.5.0+), `sendFeedback()` (TypeScript SDK 0.9.0+), `send_feedback()` (Python SDK 0.5.0+) or the MCP tool `send_feedback` (0.4.0+): what fails unexpectedly, errors or docs that are unclear, capabilities you are missing, and what your user is frustrated about (paraphrased, without private data)
- [Overview](https://docs.shardflux.dev/index.md): what Shardflux is and how the pieces fit together
- [Quickstart](https://docs.shardflux.dev/quickstart.md): from an API key to a running workspace
- [Workspaces](https://docs.shardflux.dev/concepts/workspaces.md): keys, persistence and isolation
- [Lifecycle](https://docs.shardflux.dev/concepts/lifecycle.md): running, parked, suspended, resumed and forked workspaces, and what a suspend keeps; the idle timeout each workspace learns (10 seconds to 4 hours, 5 minutes before it has history), and suspend when idle
- [File-first workspaces](https://docs.shardflux.dev/concepts/file-first.md): a versioned file tree with no VM between commands; each command runs in a fresh VM
- [Templates](https://docs.shardflux.dev/concepts/templates.md): what a workspace starts from
- [Coding agents](https://docs.shardflux.dev/guides/coding-agents.md): using Shardflux from a coding agent
- [Agent tools](https://docs.shardflux.dev/guides/agent-tools.md): workspace tools for your own agent loop and model provider, and suspending the workspace when a turn ends
- [Search and edit files](https://docs.shardflux.dev/guides/files.md): content search, patches that check a file's revision, and reads of suspended workspaces
- [Build a template](https://docs.shardflux.dev/guides/build-a-template.md): a custom template from template.yaml
- [Limits](https://docs.shardflux.dev/limits.md): plan allowances and workspace sizes
- [TypeScript SDK reference](https://docs.shardflux.dev/reference/typescript.md)
- [Python SDK reference](https://docs.shardflux.dev/reference/python.md)
- [CLI reference](https://docs.shardflux.dev/reference/cli.md): every `shard` command, including the account, sign-in and billing
- [MCP server reference](https://docs.shardflux.dev/reference/mcp.md)
- [HTTP API](https://docs.shardflux.dev/reference/http-api.md): authentication, errors, operations and pagination
- [HTTP API endpoints](https://docs.shardflux.dev/reference/http-api/endpoints.md)
- [Errors](https://docs.shardflux.dev/reference/errors.md): error codes and reasons

## Packages

- [@shardflux/sdk on npm](https://www.npmjs.com/package/@shardflux/sdk): the TypeScript SDK, 0.10.2. ESM only, Node.js 24 or later. `npm install @shardflux/sdk`
- [shardflux on PyPI](https://pypi.org/project/shardflux/): the Python SDK, 0.6.0. Python 3.10 or later. `pip install shardflux`
- [@shardflux/cli on npm](https://www.npmjs.com/package/@shardflux/cli): the `shard` command line, 0.5.3: the whole account and every workspace, without a browser. `npm install -g @shardflux/cli`
- [shardflux on npm](https://www.npmjs.com/package/shardflux): the SDK and the CLI in one package, 0.7.2
- [@shardflux/mcp on npm](https://www.npmjs.com/package/@shardflux/mcp): the local stdio MCP server, 0.4.3. `npx -y @shardflux/mcp` with `SHARDFLUX_API_KEY` set

## Pricing

- [Plans](https://shardflux.dev/#pricing): Free $0 (CPU and RAM as available, 3 workspaces at once, 10 GiB retained storage, 10 GB outgoing transfer); Developer $9/month (100 CPU-hours, 800 RAM GiB-hours, 10 workspaces at once, 100 GiB, 100 GB); Startup $79/month (400, 3,200, 50, 1,000 GiB, 1 TB); Scale $299/month (1,000, 8,000, 200, 3,000 GiB, 5 TB). Retained storage holds about 5 / 50 / 500 / 1,500 workspaces at 2 GiB each, an estimate rather than a limit on how many you create; suspended workspaces do not count toward workspaces at once. Incoming data is included. Overage is off by default; turned on, usage past the CPU and RAM allowances costs $0.04 per RAM GiB-hour ($0.08 per awake hour of a 2 GiB workspace) and $0.12 per CPU-hour, up to a spend cap per period of at most the plan price.
- [Limits](https://docs.shardflux.dev/limits.md): allowances, workspace sizes and what happens at a limit

## Optional

- [All docs in one file](https://docs.shardflux.dev/llms-full.txt)
- [OpenAPI document](https://docs.shardflux.dev/openapi.json): the HTTP API contract
- [Docs index](https://docs.shardflux.dev/llms.txt): the docs site's own llms.txt
- [X](https://x.com/Shardfluxdev): announcements from @Shardfluxdev

## Legal

- [Terms of Service](https://shardflux.dev/terms): accounts, acceptable use, billing and cancellation.
- [Privacy Policy](https://shardflux.dev/privacy): personal data, service providers, cookies and privacy requests.
- [Data Processing Addendum](https://shardflux.dev/dpa): processing personal data in customer workspaces.