Shardflux for AI agents

Asked to set up Shardflux? Run npm i -g shardflux, then run permitted steps yourself; your user decides (CLI 0.22.0+). Ask one multiple-choice question at a time with the recommended answer first, and never ask for a secret or sign-in code in the chat: they answer your questions, agree to the Terms, approve sign-ins in the browser tabs shard opens and type secrets into the page shard opens. If a permission system refuses an action, stop it, explain the reason and give the exact command to the user to run in their own terminal; ask only for a non-secret result. Never bypass the refusal through settings, scripts or another tool, and keep unobserved steps unverified.

If npm reports EACCES or EPERM, run npm install --global --prefix "$HOME/.local" shardflux@latest, then "$HOME/.local/bin/shard". Keep npm config, PATH and other global packages unchanged; do not use sudo or chmod. Update with "$HOME/.local/bin/shard" update. Installation help.

• The account. Ask whether they agree to the Terms of Service and the Privacy Policy. Once they do, shard signup --accept-terms --json creates the account, or signs in to the one they have, and saves an API key (below). shard auth login --browser --json opens the sign-in page instead, where they choose Google, GitHub or email, and waits until they approve the computer; then shard setup --json saves the key.
• The key for their product. eval "$(shard env)" exports SHARDFLUX_API_KEY for the SDKs, the HTTP API and the MCP server. It is a server credential: keep it in the product’s server-side secrets, never in client code.
• Their customers’ workspaces. Build a template from a template.yaml with shard templates build template.yaml --publish --wait, then open one workspace per customer by key: workspace('customer-42/main', { template }) in the SDK or shard ws open customer-42/main --template <slug>. Credentials the workspaces use go in with shard secrets create NAME --ask --json, a page they type the value in and you never see (CLI 0.22.0+).

Quickstart Build a template

• 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. An idle workspace suspends on its own and the next tool call wakes it. A suspend returns in a few hundred milliseconds and frees the workspace’s RAM and CPU at once. Suspended, it uses no CPU-hours or RAM GiB-hours, only retained storage, and its files can be read without waking it. The idle timeout is learned per workspace, and at the end of an agent turn your harness can ask for a suspend as soon as the workspace goes idle: suspendWhenIdle() (TypeScript SDK 0.10.0+), suspend_when_idle() (Python SDK 0.6.0+), shard ws suspend --when-idle (CLI 0.5.1+).
• Room when the work needs it. A workspace holds 1 GiB at rest and grows up to the plan’s largest workspace when a build or a test suite needs it, billed for what it holds. Resize any workspace, running or suspended, without a restart: workspace.resize() (TypeScript SDK 0.14.0+), ws.resize() (Python SDK 0.10.0+), shard ws resize (CLI 0.9.0+).
• 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 operate GUI software. With computer use on, the workspace has a desktop that your agent drives with screenshots, clicks and keystrokes: Claude's computer toolset through computerToolset() (TypeScript SDK 0.15.0+) or computer_toolset() (Python SDK 0.11.0+), the computer and computer_batch agent tools for any model, shard ws computer … (CLI 0.10.0+) and the MCP server (0.9.0+). The desktop starts on the first computer call, and a private link shows it live. See Computer use.
• 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.
• Apps that render. On the Startup and Scale plans, workspaces render on a GPU through Shardflux's own Vulkan driver. Unity, Godot, Blender and any Vulkan app run unchanged, and your agent takes the frames it asks for. See GPU-hours.
• Previews, webhooks and callbacks. Any port of a workspace gets a private HTTPS URL (https://3000-<handle>.shardflux.app). A request wakes a parked or suspended workspace and is answered once it runs (TypeScript SDK 0.14.0+, Python SDK 0.10.0+, CLI 0.9.0+, MCP 0.8.0+). See Reach a port.
• Code written for the E2B SDK. Set E2B_API_URL=https://e2b.shardflux.dev, E2B_DOMAIN=e2b.shardflux.dev and E2B_API_KEY to a Shardflux project key, and its sandbox, command and file calls run on Shardflux; create-time envs, PTYs, Python/JavaScript/TypeScript code execution and desktop calls are supported (see the E2B reference for startup requirements and limits). See Use the E2B SDK.
• Throwaway runs. A workspace opened with lifetime: 'session' is discarded when its session ends: on close() or its configured idle timeout.

Start with a 7-day Pro trial after a non-prepaid Stripe card check approved by your bank and a verified work domain or established GitHub account; nothing is charged. One card and one GitHub account each earn one trial across all accounts, ever. After the trial, or on additional organizations, a paid plan is required to open or resume workspaces while 10 GiB of retained workspace storage is kept. Startup and Scale render on a GPU. Upgrade from Usage & billing in the console or with shard billing upgrade <plan>.

Plans on the home page Plan allowances and limits

TypeScript SDK

@shardflux/sdk 0.35.2. ESM only, Node.js 24 or later. npm install @shardflux/sdk

Python SDK

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

CLI

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

MCP server

Hosted at https://mcp.shardflux.dev/mcp (Streamable HTTP, OAuth), or @shardflux/mcp 0.28.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 (default, which is python-node-browser) has Python, Node.js and a browser, and memory that grows as its commands need it, up to the plan's per-workspace maximum. Build your own template from a template.yaml; its immutable paths keep your tooling current in every workspace.

• 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. Every client reads it from there (the TypeScript SDK from 0.15.0).
• The HTTP API takes it as Authorization: Bearer <key>. SHARDFLUX_API_URL changes the API origin (default https://api.shardflux.dev).

No account yet? One command creates it, signs in and saves an API key. The shard CLI (0.9.0+) does everything the console does, from the account to upgrading the plan.

npm i -g shardflux
shard signup
shard exec acme/demo --template default -- python3 -c 'print(40 + 2)'

• shard signup --email <address> creates an account automatically without a CAPTCHA; new accounts unlock the 7-day trial with a non-prepaid Stripe card check and a verified work domain or established GitHub account (or start a paid plan) before starting compute; shard verify emails the person a 6-digit code, and the person completes the Stripe card check in the console (nothing is charged). Without --email, signup opens the sign-in page in the browser (Google, GitHub or email).
• Before an agent signs up, it shows the person the Terms of Service and the Privacy Policy; once they agree, shard signup --accept-terms. Without the flag and a terminal to ask on, signup stops before it sends anything with terms_not_accepted (exit 2) and both links in details.
• signup runs shard setup: the organization, project and API key, saved in ~/.config/shardflux/credentials.json. eval "$(shard env)" exports the key as SHARDFLUX_API_KEY for the SDKs and the MCP server.
• Paying is the step a person does: shard billing upgrade <plan> prints the Stripe Checkout URL, and --wait waits until the plan is active.
• With two-factor authentication on, signup and auth login take --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 the workspace. The key names the workspace: the first call creates it, and the same key reaches it again from any process. This is the quick start of @shardflux/sdk 0.35.2, type-checked against the published package before this page ships.

import { workspace } from '@shardflux/sdk';

const ws = workspace('demo/main', { template: 'default' }); // reads SHARDFLUX_API_KEY; no request yet

// 1. Run a command: the first call creates the workspace. Check that it worked.
const run = await ws.exec('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 ws.files.write('/home/user/notes.txt', 'hello from the SDK\n');
await (await ws.open()).suspend({ wait: true }); // resolves once suspended

// 3. The same key again: the workspace wakes, and the file is still there.
const again = workspace('demo/main', { template: 'default' });
console.log(await again.files.readText('/home/user/notes.txt')); // hello from the SDK

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 checks that a file survives a suspend. A resume brings back far more: installed packages, running processes with their memory, and sockets inside the workspace. Clients’ connections to the workspace’s tools re-attach after the resume.

The same program in Python

from shardflux import workspace

ws = workspace("demo/main", template="default")  # reads SHARDFLUX_API_KEY; no request yet

# 1. Run a command: the first call creates the workspace. Check that it worked.
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.open().suspend(wait=True)  # returns once suspended

# 3. The same key again: the workspace wakes, and the file is still there.
again = workspace("demo/main", template="default")
print(again.files.read_text("/home/user/notes.txt"))  # hello from Python

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

Paste it into an AI 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 each step with its real output.

Use Shardflux (https://shardflux.dev), serverless VMs 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.

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

Feedback: send a report to Shardflux only when I ask you to. Show me the exact message and context, including the request id and error code, and obtain my explicit authorization before sending. A failure or request for a feature is not consent. Paraphrase; leave out private data, secrets, code I did not mean to share and transcripts. Tell me what was 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. Use the workspace with key "demo/main" and template "default": workspace(key, { template }) in TypeScript or workspace(key, template=...) in Python. The first call creates it.
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. Use the same key again and read /home/user/notes.txt back.

Report each step with its real output, including the file read back after the suspend.

The hosted MCP endpoint is https://mcp.shardflux.dev/mcp (MCP Streamable HTTP). Add the URL to your client; it signs you in with OAuth, you choose a project, and the connection appears on that project’s API keys page as <client> (MCP connector).

A client configured with headers can send Authorization: Bearer sfk_... instead.

@shardflux/mcp is the same server as a local stdio process for any MCP client, your own agent included. 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: with it, the first tool call on a new workspace_key creates the workspace (0.9.0+). 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.

Send feedback only when the user asks to report something to Shardflux. Show the exact message and context and obtain explicit authorization before submitting. An error or request for a feature is not consent.

CLI 0.22.0+ shard feedback previews without sending; add --yes only after approval. MCP 0.19.0+ send_feedback previews unless user_approved: true asserts approval. Earlier versions of the CLI and local MCP send immediately. The TypeScript SDK (0.9.0+) sendFeedback() and Python SDK (0.5.0+) send_feedback() remain explicit manual APIs that send immediately and have no consent prompt; agents must show the message and get approval first.

Include request and error IDs, paraphrase, and leave out private data, secrets, code the user did not mean to share and transcripts. Tell the user what was sent. Error feedback suggestions are previews, not permission to send. Rate limited to 10 per 10 minutes and 50 per day per key or user. Without the tools, email shardflux@shardflux.dev only with the same authorization.

• 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
• Use the E2B SDK Move an existing E2B integration by changing its environment variables
• Agent tools Workspace tools for your own agent loop
• Test your integration SDK fakes for your workspace calls, then the same checks against Shardflux
• Reach a port A private HTTPS URL per port; a request wakes the workspace
• Computer use A desktop your agent drives with screenshots, clicks and keystrokes
• Build a template Your customers’ workspaces from a template.yaml
• 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

SDK 0.14.0+ workspaceTools(ws, { prewake: true }) exposes optional onInputStart() callbacks for VM tools. Python 0.10.0+ exposes on_input_start with prewake=True. Invoke the matching callback when the model starts its tool input. Defaults, offline reads and file-first tools add no early hook.