# Overview

> Serverless VMs for the agents inside your product: microVM workspaces, opened by key, that scale to zero between calls and keep files, processes and memory.

## What Shardflux is

Shardflux runs serverless VMs for the agents inside your product, without lifecycle code. Give each customer of your
product a persistent computer for their agent: files, tools and running processes stay between sessions, it scales to
zero when idle, and you pay for the compute it uses while Shardflux manages the infrastructure.

Each **workspace** is a Linux microVM with its own kernel, disk and memory. Your code opens it by a **key** you
choose, such as `customer-42/main`, runs commands and moves files in it, and leaves it. The next time anything opens the same key, it gets the same workspace back: files, installed packages
and running processes are still there.

A workspace runs while there is work and scales to zero when there is none. Seconds after its last tool call its host
**parks** it ([lifecycle](https://docs.shardflux.dev/concepts/lifecycle.md#idle-running-workspaces-are-parked)), and the next call, or an HTTPS
request to one of its [ports](https://docs.shardflux.dev/guides/ports.md), wakes it before it runs. A workspace that is not needed can be **suspended**: its memory and processes are checkpointed and its compute
stops. It **resumes** where it left off, either when you ask or when the next tool call arrives. With
[elastic memory](https://docs.shardflux.dev/concepts/workspaces.md#elastic-memory) it holds only what its commands need, and you pay for what it
holds. A workspace can be **forked** into a new key, which gives an independent copy of its files, memory and
processes.

Your application keeps its own identity, agent loop and model calls; Shardflux is the computer underneath.
[Give your agent workspace tools](https://docs.shardflux.dev/guides/agent-tools.md) hands the workspace to any model provider as tool definitions.

## The 60-second picture

```ts
import { workspace } from '@shardflux/sdk';                // reads SHARDFLUX_API_KEY

// The key names the workspace: created on first use, the same workspace every time after.
const ws = workspace('customer-42/main', { template: 'default' });

const run = await ws.exec('python3 -c "print(40 + 2)"');
console.log(run.exitCode, run.stdout.trim());               // 0 42

const full = await ws.open();                               // the whole lifecycle when you want it
await full.suspend({ wait: true });                         // memory and processes checkpointed, compute stops
const { workspace: copy } = await full.fork({ key: 'customer-42/experiment' }, { wait: true });
```

There is no create call and no lifecycle code to write: the first call on a key creates its workspace, an idle
workspace suspends on its own, and the next call wakes it **(SDK 0.15.0+)**.

| Piece | What it is |
| --- | --- |
| [Workspace](https://docs.shardflux.dev/concepts/workspaces.md) | A persistent, isolated microVM, named by a key that is unique in your organization. |
| [Template](https://docs.shardflux.dev/concepts/templates.md) | The versioned image a workspace starts from, such as `default` (`python-node-browser`). |
| [Lifecycle](https://docs.shardflux.dev/concepts/lifecycle.md) | Open, suspend, resume, fork, snapshot, reset and delete, as operations you can wait for. |
| Project API key | `sfk_<key id>_<secret>`, a server credential that opens and manages workspaces. |
| Tools | `exec`, `files`, `pty`, `process`, `git` and `browser`: what code can do inside a workspace. Files can also be [searched and patched](https://docs.shardflux.dev/guides/files.md). |
| [File-first workspace](https://docs.shardflux.dev/concepts/file-first.md) | An opt-in mode: a versioned file tree with no VM between commands; each command runs in a fresh VM. |

## Clients

| Client | Install | Use it for |
| --- | --- | --- |
| TypeScript SDK | `npm install @shardflux/sdk` (Node.js 24+) | The full API, plus [agent tool definitions](https://docs.shardflux.dev/guides/agent-tools.md) for model providers. |
| Python SDK | `pip install shardflux` (Python 3.10+) | Workspaces, commands, files, lifecycle, templates, secrets, tool-call capture and [agent tool definitions](https://docs.shardflux.dev/guides/agent-tools.md) (0.4.0+). |
| CLI | `npm i -g shardflux` (the `shard` command; [permission recovery](https://docs.shardflux.dev/reference/cli.md#npm-permission-errors)) | Scripts, CI and looking at workspaces by hand; from 0.5.0 also the whole account without a browser, from sign-up to billing ([accounts and sign-in](https://docs.shardflux.dev/reference/cli.md#accounts-and-sign-in)). |
| MCP server | Hosted at `https://mcp.shardflux.dev/mcp`, or local with `npx -y @shardflux/mcp` | [Workspace tools](https://docs.shardflux.dev/reference/mcp.md) for any MCP client or agent framework. |
| E2B SDK | Your existing `e2b` package, pointed at `https://e2b.shardflux.dev` | Moving an E2B integration over by changing [three environment variables](https://docs.shardflux.dev/guides/e2b.md). |

The HTTP API is versioned (`/v1`). Each client's changelog lists what every release adds and changes.

## What it is built for

- **A computer per customer.** Keys such as `customer-42/main` give each customer or project of your product its own
  isolated microVM: AI app and site builders, game and creative tools, data and analytics agents, browser and
  computer-use agents, evals and sandboxes.
- **Computers that outlive the session.** A repository, a virtual environment, a dev server, a browser session:
  all still there on the next request, the next day, the next session.
- **Agents that work in bursts.** An idle workspace parks between tool calls and wakes with the next one. Suspend it
  between bursts and compute stops until the next tool call resumes it.
- **Previews and callbacks.** Any port of a workspace gets a private [HTTPS URL](https://docs.shardflux.dev/guides/ports.md) that wakes it, for
  previews in your app, webhooks and OAuth callbacks.
- **A desktop the agent can drive.** [Computer use](https://docs.shardflux.dev/guides/computer-use.md) gives a workspace a Linux desktop that your
  agent operates with screenshots, clicks and keystrokes, and that your users can watch live.
- **Agents that mostly edit files.** A [file-first workspace](https://docs.shardflux.dev/concepts/file-first.md) keeps only the files, uses no
  compute between commands and never counts toward workspaces working at once.
- **Trying several approaches at once.** Fork a workspace and each copy continues independently from the same state.
- **Several agents on the same work.** A planner, a coder and a reviewer open the same key, and each one's tool calls
  are attributed to its own label.

## Next steps

- [Quickstart](https://docs.shardflux.dev/quickstart.md): sign up, create an API key, and run your first workspace in TypeScript, Python or the CLI.
- [Workspaces](https://docs.shardflux.dev/concepts/workspaces.md), [Lifecycle](https://docs.shardflux.dev/concepts/lifecycle.md) and [Templates](https://docs.shardflux.dev/concepts/templates.md): the model
  behind the API.
- [Give your agent workspace tools](https://docs.shardflux.dev/guides/agent-tools.md) with Anthropic, OpenAI and other model providers.
- [Build a template](https://docs.shardflux.dev/guides/build-a-template.md) with your product's tools installed, and keep
  [workspace secrets](https://docs.shardflux.dev/guides/credentials.md) out of your code.
- [Reference](https://docs.shardflux.dev/reference/typescript.md): the TypeScript SDK, [Python SDK](https://docs.shardflux.dev/reference/python.md), [CLI](https://docs.shardflux.dev/reference/cli.md),
  [MCP server](https://docs.shardflux.dev/reference/mcp.md) and [HTTP API](https://docs.shardflux.dev/reference/http-api.md).
- [Pricing and limits](https://docs.shardflux.dev/limits.md): plans, allowances and what happens at a limit.
- [Support and bug reports](https://docs.shardflux.dev/support.md): report a problem, request a feature, or get private help.

## Docs for agents

Every page is also Markdown at its URL plus `.md`, for example `https://docs.shardflux.dev/quickstart.md`.
[llms.txt](https://docs.shardflux.dev/llms.txt) lists every page with a short description, and
[llms-full.txt](https://docs.shardflux.dev/llms-full.txt) has them all in one file. Point the agent that writes your
integration there, so it uses the current API.