Use Shardflux with your coding agent

Two ways to use Shardflux from a coding agent

Both need a project API key in the SHARDFLUX_API_KEY environment variable. Create one in the Quickstart, or let the agent create the account and the key itself (below).

An agent without an account

The shard CLI (0.5.0+) does everything the console does, without a browser, so a coding agent can go from no account to a running workspace on its own. 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
eval "$(npx @shardflux/cli@latest env)"
npx @shardflux/cli@latest ws open demo/main --template python-node-browser

• Two steps need a person: the link in the verification email (unless the agent can read that mailbox), and paying in Stripe Checkout for a paid plan. shard billing upgrade <plan> prints the Checkout URL, and --wait waits until the plan is active. Every account starts on Free.
• setup creates an organization, a project and an API key with every workspace tool, and saves the key in ~/.config/shardflux/credentials.json. It is safe to run again. env prints the key as export SHARDFLUX_API_KEY=... for the SDKs and the MCP server.
• With two-factor authentication on, auth login also takes --code from the person's authenticator app. Exports, deletions and security changes need shard auth step-up first.
• Each sign-in is a CLI session the person sees in the console (Settings > Account & security) and can sign out there; shard auth logout ends it from the terminal.
• Add --json for machine-readable output. The CLI reference has every command, the credentials file and the exit codes; https://shardflux.dev/llms.txt has the same instructions for agents.

Paste this prompt into your coding agent

Start your coding agent in a shell where SHARDFLUX_API_KEY is set, then paste:

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

What to expect

• The agent reads llms.txt, installs one SDK and writes a short program much like the Quickstart. Step 2 prints 42 with exit code 0.
• The first open of demo/main creates the workspace, which takes longer than the steps after it. The suspend in step 3 returns once it has finished, and step 4 resumes the workspace.
• The report should separate what was verified (the file came back) from what was not checked (memory and running processes, which a suspend also keeps; see What survives each transition). Treat a report without real output as unverified.
• When you are done, delete the workspace: shard ws delete demo/main --yes. A suspended workspace uses no compute, but its disk counts toward your plan's retained storage.

Replace steps 1 to 4 with your own task once this works; keep the lines about the docs, the credentials and the feedback.

Send feedback while you work

Every client can send a message straight to the Shardflux founder, who reads every one: shard feedback in the CLI (0.5.0+), the MCP tool send_feedback (0.4.0+), sendFeedback() in the TypeScript SDK (0.9.0+) and send_feedback() in the Python SDK (0.5.0+). They ask your agent to use it actively while it works, not once at the end:

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

The agent does not ask first, but tells you what it sent. It paraphrases rather than pasting transcripts, and leaves out private data, secrets and code you did not mean to share; anything shaped like an API key, token or private key is also redacted before the message is stored or emailed. A failed shard command ends with a ready-made feedback: line, and a failed MCP call carries a feedback field, with the request id and error code filled in.

shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 "ws open waited 40 s; expected under 5 s"
shard feedback --category confusing "user was frustrated that ws open needs a template slug; they expected a default"

Feedback is rate limited (10 per 10 minutes and 50 per day per key or user) and the same message within 24 hours is recorded once. Without the tools, email shardflux@heliosone.fi. See the CLI, MCP, TypeScript and Python references.

Give your coding agent workspace tools over MCP

The Shardflux MCP server is a local stdio server. It runs on your machine with npx -y @shardflux/mcp (Node.js 24 or later) and turns each tool call into one request to Shardflux with the API key you give it. It has no agent loop and keeps no local copy of the workspace.

All options are in the MCP server reference.

Claude Code

Add the server for all your projects:

claude mcp add --env SHARDFLUX_API_KEY="$SHARDFLUX_API_KEY" --transport stdio shardflux --scope user -- npx -y @shardflux/mcp

This stores the key's value in Claude Code's configuration. To keep it out of configuration files, add a .mcp.json to your project instead. Claude Code expands ${SHARDFLUX_API_KEY} from the environment it was started in:

{
  "mcpServers": {
    "shardflux": {
      "command": "npx",
      "args": ["-y", "@shardflux/mcp"],
      "env": {
        "SHARDFLUX_API_KEY": "${SHARDFLUX_API_KEY}",
        "SHARDFLUX_TEMPLATE": "python-node-browser"
      }
    }
  }
}

Check it with claude mcp list, or /mcp inside Claude Code.

Cursor

Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "shardflux": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@shardflux/mcp"],
      "env": {
        "SHARDFLUX_API_KEY": "${env:SHARDFLUX_API_KEY}",
        "SHARDFLUX_TEMPLATE": "python-node-browser"
      }
    }
  }
}

Cursor resolves ${env:SHARDFLUX_API_KEY} from the environment Cursor itself runs in. If Cursor was not started from a shell that has the variable, put SHARDFLUX_API_KEY=sfk_... in a file outside your repository and point the server's envFile field at it.

Codex

Add the server to ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.shardflux]
command = "npx"
args = ["-y", "@shardflux/mcp"]
env_vars = ["SHARDFLUX_API_KEY"]
env = { SHARDFLUX_TEMPLATE = "python-node-browser" }
tool_timeout_sec = 180

env_vars forwards SHARDFLUX_API_KEY from the shell Codex runs in; apart from a few basic variables such as PATH and HOME, Codex passes a server only the variables you list. tool_timeout_sec matters because Codex gives up on a tool call after 60 seconds by default, while opening a new workspace can take longer; the Shardflux server's own deadline is 120 seconds unless you change SHARDFLUX_MCP_TOOL_TIMEOUT_MS.

The same from the command line (this stores the key's value in config.toml):

codex mcp add shardflux --env SHARDFLUX_API_KEY="$SHARDFLUX_API_KEY" -- npx -y @shardflux/mcp

Check it with codex mcp list, or /mcp inside Codex.

Claude Desktop

Open Settings > Developer > Edit Config in Claude Desktop. That opens claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows). Add the server:

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

Claude Desktop does not read your shell's environment, so the key goes into the file itself. Quit and restart Claude Desktop to load the server. Its log is in ~/Library/Logs/Claude/mcp-server-shardflux.log (macOS) or %APPDATA%\Claude\logs (Windows).

Check that it works

Ask the agent:

Use the shardflux MCP server: open the workspace "demo/mcp" with template "python-node-browser", run python3 -c "print(40 + 2)" with the exec tool, and show me the exact result.

The agent calls workspace_open, then exec, and gets exit_code 0 and stdout 42. If a tool call fails, the result carries a structured error (code, message, retryable) instead of breaking the connection.

Tools the MCP server provides

Management tools:

Workspace tools, filtered by the API key's tool permissions: exec; read_file, write_file, list_files, search_files and edit_file (0.4.0+); list_processes, signal_process; terminal_open, terminal_send, terminal_read, terminal_close; git_clone, git_status, git_commit; browser_screenshot, browser_content. They are the same tools as the SDKs' workspaceTools() and workspace_tools(), with the same parameters plus workspace_key. search_files searches file contents, and edit_file replaces exact text and refuses the edit when the file changed since it was read (see Search and edit files).

Behaviour worth knowing:

• Workspace tools wake a suspended workspace, but do not create one: call workspace_open first. From 0.4.0 the wake is one request, and read_file, list_files and search_files of a suspended workspace are answered from its disk without waking it.
• On a file-first workspace (0.4.0+), exec runs each command in a fresh VM and only files under /home/user persist; the process, terminal, git and browser tools and suspend, resume and fork do not apply.
• Deleting a workspace is not exposed to agents. Use the CLI, an SDK or the console.
• Account actions (signing up, signing in, API keys, members, billing) are not tools either: the server uses a project API key, which the API refuses for them. From 0.4.0 its instructions send the agent to the shard CLI (above).
• Every call has a deadline. A wait that runs out returns code: timeout with the operation_id; the operation continues, and operation_wait picks it up.
• A start that waits for capacity gives up after 15 minutes with capacity_unavailable and retryable: true. The server does not retry it itself.
• Tool tokens are never returned to the model, and the API key is never logged.

Docs for agents: llms.txt and Markdown

https://docs.shardflux.dev/llms.txt lists every page of these docs with a short description and a link to its Markdown version. Every page is published as Markdown at its URL plus .md, for example https://docs.shardflux.dev/quickstart.md, and https://docs.shardflux.dev/llms-full.txt has every page in one file.

Point an agent there, as the prompt above does, instead of letting it rely on what it remembers: the SDKs are below 1.0 and change between minor versions.

Keep the key safe

• Give coding agents a key with only the tool permissions they need, and an expiry. Revoking a key stops the tool tokens it obtained within 30 seconds.
• Pin the MCP server to one workspace with SHARDFLUX_WORKSPACE_KEY when the agent should not touch others.
• Keep keys out of prompts, repositories and files an agent may print. Both the prompt above and the MCP server read the key from the environment.