Shardflux for coding agents

• State between tasks. The same key opens the same workspace, with its files, installed packages and running processes. Opening it again never resets it.
• One computer per customer, project or task. Each workspace is its own Firecracker microVM with its own kernel.
• Work that comes in bursts. Between tool calls an idle workspace is parked by its host and the next call wakes it; parked, it is still running and billed as running. After its idle period a persistent workspace suspends after an idle period and wakes on the next tool call. While it is suspended it uses no CPU-hours or RAM GiB-hours; its retained storage still counts, and its files can be read without waking it. The idle timeout is learned per workspace (10 seconds to 4 hours; 5 minutes before it has history), and at the end of an agent turn your harness can ask for a suspend once the workspace has been idle for 30 seconds to an hour: suspendWhenIdle() (TypeScript SDK 0.10.0+), suspend_when_idle() (Python SDK 0.6.0+), shard ws suspend --when-idle (CLI 0.5.1+).
• Trying several approaches. Fork a workspace into a new key. Its files, memory and processes are copied into an independent VM.
• Your own agent loop and model. The SDKs’ workspace tools (exec, files, processes, terminal, git, browser; TypeScript workspaceTools, Python workspace_tools) export to the Anthropic and OpenAI tool formats. The TypeScript tools also search files and edit them by exact text. The MCP server offers the same tools to MCP clients.
• Agents that mostly edit files. A file-first workspace keeps only a versioned tree of the files under /home/user and runs each command in a fresh VM. It uses no compute and no running slot between commands; processes do not survive a command.
• Throwaway runs. A workspace opened with lifetime: 'session' is discarded when its session ends: on close(), or after 10 idle minutes unless its template sets another timeout.

When it does not fit

• Calls from a browser or mobile app. API keys are server credentials. Call Shardflux from your backend.
• Machines larger than your plan allows. The largest workspace is 1 vCPU, 2 GiB RAM and 2 GiB disk on Free, and 16 vCPU, 32 GiB RAM and 100 GiB disk on Scale. Memory cannot be resized while a workspace runs.
• Data that must stay in a particular region. Workspaces run in AWS us-west-2 (Oregon).
• Remote connections that must survive a suspend. Processes and sockets inside the workspace are kept. Remote systems are not paused with it and may close their connections while it sleeps.
• Guaranteed capacity on Free. The free plan runs on spare capacity. On every plan, a start that no host can admit waits for at most 15 minutes and then fails with capacity_unavailable. Nothing was started, and retrying later is safe.

Workspaces at once counts running and starting workspaces; suspended ones do not count. Workspaces stored is an estimate of what retained storage holds, not a limit on how many workspaces you create. Incoming data is included. When the outgoing allowance is used up, outgoing traffic stops until you upgrade or the next period starts, and workspaces keep running. Every account starts on Free and upgrades from Usage & billing in the console, or with shard billing upgrade <plan>.

Overage is off by default. On a paid plan, an owner or billing member can turn it on in the console, or with shard billing overage on --cap <dollars> (CLI 0.5.1+), with a spend cap per billing period of $1 up to the plan price. Past the CPU-hours or RAM GiB-hours allowance, usage then costs $0.04 per RAM GiB-hour ($0.08 per awake hour of a 2 GiB workspace) and $0.12 per CPU-hour, billed on the next invoice. With overage off, or at the cap, new starts get 402 allowance_exhausted and running workspaces are suspended. Nothing is deleted. Storage and outgoing transfer have no overage.

Plans on the home page All limits

TypeScript SDK

@shardflux/sdk 0.10.2. ESM only, Node.js 24 or later, no runtime dependencies. npm install @shardflux/sdk

Python SDK

shardflux 0.6.1 on PyPI. Python 3.10 or later. pip install shardflux

CLI

@shardflux/cli 0.5.3, the shard command. Node.js 24 or later. npm install -g @shardflux/cli. It covers workspaces and the whole account, from sign-up to billing. The shardflux npm package (0.7.2) bundles the SDK and the CLI.

MCP server

@shardflux/mcp 0.4.3, a local stdio server. Node.js 24 or later. npx -y @shardflux/mcp

HTTP API

https://api.shardflux.dev/v1, described by the OpenAPI document.

In the workspace

The default template, python-node-browser, has Python, Node.js and a browser, and 2 GiB RAM by default. Build your own template from a template.yaml.

• Create a project API key in the console at app.shardflux.dev, or with shard setup (below). It looks like sfk_<key id>_<secret> and is shown once.
• It is a server credential. Keep it out of browser bundles, client-side code and logs.
• Put it in the SHARDFLUX_API_KEY environment variable. The Python SDK, the CLI and the MCP server read it from there. The TypeScript SDK reads nothing from the environment, so pass it in: new Shardflux({ apiKey: process.env.SHARDFLUX_API_KEY! }).
• The HTTP API takes it as Authorization: Bearer <key>. SHARDFLUX_API_URL changes the API origin (default https://api.shardflux.dev).

No account yet? The shard CLI (0.5.0+) does everything the console does, without a browser: it creates the account, signs in, sets up an organization, project and API key, and upgrades the plan. Passwords are read from standard input, never from arguments.

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)'

• Two steps need a person: the link in the verification email (unless the agent can read that mailbox), and paying in Stripe Checkout. shard billing upgrade <plan> prints the Checkout URL, and --wait waits until the plan is active.
• shard setup creates the organization, project and API key when they are missing and saves the key in ~/.config/shardflux/credentials.json. eval "$(shard env)" exports it as SHARDFLUX_API_KEY for the SDKs and the MCP server.
• With two-factor authentication on, auth login takes --code <code>. Exports, deletions and security changes need shard auth step-up first.
• Add --json for machine-readable output. shard --help lists every command and the exit codes. All the details: llms.txt and the CLI reference.

Run a command and check that it worked, then show that a file survives suspending and reopening the workspace. This is the quick start of @shardflux/sdk 0.10.2, type-checked against the published package before this page ships.

import { Shardflux, formatTiming } from '@shardflux/sdk';

const cloud = new Shardflux({ apiKey: process.env.SHARDFLUX_API_KEY! });
const open = () => cloud.workspaces.open({ key: 'demo/main', template: 'python-node-browser' });

// 1. Open the workspace (created on first use) and run a command. Check that it worked.
const workspace = await open();
const run = await workspace.cell().exec.run(['python3', '-c', 'print(40 + 2)']);
if (run.exitCode !== 0) throw new Error(`python3 exited ${run.exitCode}: ${run.stderr}`);
console.log(run.stdout.trim()); // 42

// 2. Write a file, then suspend the workspace and wait until the suspend has finished.
await workspace.cell().files.write('/home/user/notes.txt', 'hello from the SDK\n');
await workspace.suspend({ wait: true }); // resolves once suspended

// 3. Open the same key again: the workspace resumes, and the file is still there.
const again = await open();
console.log(await again.cell().files.readText('/home/user/notes.txt')); // hello from the SDK
console.log(formatTiming(again.lastTiming!)); // where the resume's time went

Save it as quickstart.mts in a project with @shardflux/sdk installed, set SHARDFLUX_API_KEY, and run node quickstart.mts. Node.js 24 runs TypeScript files directly.

The example verifies that a file survives a suspend. A resume also keeps installed packages, running processes with their memory, and sockets inside the workspace. Connections from clients to the workspace’s tools end at the suspend and re-attach after the resume. The example does not check processes or memory.

The same program in Python

from shardflux import Shardflux, format_timing

sf = Shardflux()  # reads SHARDFLUX_API_KEY


def open_workspace():
    return sf.open(key="demo/main", template="python-node-browser")


# 1. Open the workspace (created on first use) and run a command. Check that it worked.
ws = open_workspace()
result = ws.exec("python3 -c 'print(40 + 2)'")
if result.exit_code != 0:
    raise RuntimeError(f"python3 exited {result.exit_code}: {result.stderr}")
print(result.stdout.strip())  # 42

# 2. Write a file, then suspend the workspace and wait until the suspend has finished.
ws.files.write("/home/user/notes.txt", "hello from Python\n")
ws.suspend(wait=True)  # returns once suspended: ws.state == "suspended"

# 3. Open the same key again: the workspace resumes, and the file is still there.
again = open_workspace()
print(again.files.read_text("/home/user/notes.txt"))  # hello from Python
print(format_timing(again.last_timing))  # where the resume's time went

Install it with pip install shardflux (Python 3.10 or later), set SHARDFLUX_API_KEY, and run python quickstart.py.

Paste it into a coding agent working in a project where SHARDFLUX_API_KEY is set. It sends the agent to the current docs, has it run the example’s steps, and asks it to report what it verified and what it did not.

Use Shardflux (https://shardflux.dev), cloud computers for AI agents, for this task.

Read https://docs.shardflux.dev/llms.txt first and follow its links to the current docs. Use only APIs documented there; do not rely on memory of Shardflux or of other sandbox products.

Credentials: the API key is in the SHARDFLUX_API_KEY environment variable. Never print it, log it or write it to a file.

Feedback: while you work, report to the Shardflux team the moment something fails unexpectedly, an error or doc is unclear, something you need is missing, or I say I am frustrated with Shardflux: sendFeedback() in the TypeScript SDK, send_feedback() in the Python SDK, or shard feedback in the CLI. Keep it short, include the request id and error code, paraphrase, leave out private data and secrets, and tell me what you sent.

Use the TypeScript SDK (npm install @shardflux/sdk, Node 24+) or the Python SDK (pip install shardflux, Python 3.10+), whichever this project uses:
1. Open the workspace with key "demo/main" and template "python-node-browser".
2. Run python3 -c "print(40 + 2)" in it. Check the exit code and the output.
3. Write /home/user/notes.txt, then suspend the workspace and wait until the suspend has finished.
4. Open the same key again and read /home/user/notes.txt back.

Report each step with its real output. State separately what you verified survived the suspend (the file) and what you did not check (running processes, memory).

@shardflux/mcp is a local stdio MCP server for Claude Desktop, Claude Code, IDE agents and other MCP clients. It needs Node.js 24 or later. Add it to your client’s MCP configuration:

{
  "mcpServers": {
    "shardflux": {
      "command": "npx",
      "args": ["-y", "@shardflux/mcp"],
      "env": { "SHARDFLUX_API_KEY": "sfk_..." }
    }
  }
}

• SHARDFLUX_WORKSPACE_KEY pins one workspace, and SHARDFLUX_TEMPLATE sets the default template for workspace_open. Both are optional.
• Tools: workspace_open, workspace_list, workspace_status, workspace_suspend (with after_seconds, 0.4.1+: suspend once idle, for the end of the agent's work), workspace_resume, workspace_fork, operation_wait, usage_summary, send_feedback (0.4.0+), the template tools, and the workspace tools exec, read_file, write_file, list_files, search_files, edit_file, processes, terminal, git and browser.
• Workspace tools wake a suspended workspace. Deleting a workspace is not exposed to agents; use the CLI or the console.
• Account actions (signing up, signing in, API keys, members, billing) are not MCP tools: the server uses a project API key, which the API refuses for them. Use the shard CLI.
• At startup the server logs one line on stderr when a newer version is out; SHARDFLUX_NO_UPDATE_CHECK=1 turns the check off.

Every client can send a message straight to the Shardflux founder, who reads every one: shard feedback "..." (CLI 0.5.0+), the MCP tool send_feedback (0.4.0+), sendFeedback() (TypeScript SDK 0.9.0+) and send_feedback() (Python SDK 0.5.0+). Use it actively while you work, not once at the end:

• the moment something fails unexpectedly, an error or doc is unclear, an option is missing, or you needed a workaround;
• when your user complains or is frustrated about Shardflux or the workflow around it (slowness, cost or limits, confusing setup, a missing feature, a workaround): paraphrase it, with what they were trying to do;
• when your user asked for something Shardflux could not do, or made awkward.

Short and frequent beats polished: what you ran, what happened, what you expected, with the request id and error code. No need to ask first, but tell your user you sent it. Leave out private data about the user and secrets or code they did not mean to share; paraphrase, never paste transcripts. A failed shard command prints a ready-made feedback: line to fill in. Rate limited to 10 per 10 minutes and 50 per day per key or user. Without the tools, email shardflux@heliosone.fi.

• docs.shardflux.dev/llms.txt Index of the docs, with a Markdown version of every page
• docs.shardflux.dev/llms-full.txt All of the docs in one file
• Quickstart From API key to a running workspace
• Coding agents Using Shardflux from a coding agent
• Agent tools Workspace tools for your own agent loop
• Search and edit files Search, patches with revisions, reads of suspended workspaces
• File-first workspaces A versioned file tree with no VM between commands
• CLI Every shard command, including the account, sign-in and billing
• Errors Error codes and reasons
• OpenAPI The HTTP API contract
• shardflux.dev/llms.txt This site’s index for language models