# Use Shardflux with your coding agent

> A prompt for your coding agent, an account from the shard CLI without a browser, and MCP server setup for Claude Code, Cursor, Codex and Claude Desktop.

## Two ways to use Shardflux from a coding agent

| | Your agent writes code that uses Shardflux | Your agent works inside a workspace itself |
| --- | --- | --- |
| How | Paste the [prompt below](#paste-this-prompt-into-your-coding-agent); the agent uses the TypeScript or Python SDK in your project | Add the [Shardflux MCP server](#give-your-coding-agent-workspace-tools-over-mcp); the agent calls workspace tools directly |
| Good for | Building your product on Shardflux | Running and testing code in a persistent cloud workspace from Claude Code, Cursor, Codex or Claude Desktop |

Both need a project API key in the `SHARDFLUX_API_KEY` environment variable. Create one in the
[Quickstart](https://docs.shardflux.dev/quickstart.md#sign-up-and-create-an-api-key), or let the agent create the account and the key itself
([below](#an-agent-without-an-account)).

## 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:

```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
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](https://docs.shardflux.dev/reference/cli.md#for-ai-agents) has every command, the
  credentials file and the exit codes; [https://shardflux.dev/llms.txt](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:

```text
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](https://docs.shardflux.dev/llms.txt), installs one SDK and writes a short program much like
  the [Quickstart](https://docs.shardflux.dev/quickstart.md). 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](https://docs.shardflux.dev/concepts/lifecycle.md#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.

```sh
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](https://docs.shardflux.dev/reference/cli.md#feedback),
[MCP](https://docs.shardflux.dev/reference/mcp.md#feedback), [TypeScript](https://docs.shardflux.dev/reference/typescript.md#feedback) and [Python](https://docs.shardflux.dev/reference/python.md#feedback)
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.

| Environment variable | Meaning |
| --- | --- |
| `SHARDFLUX_API_KEY` | Required. A project API key. Its tool permissions decide which workspace tools are listed. |
| `SHARDFLUX_TEMPLATE` | Optional. Default template for `workspace_open`, for example `python-node-browser`. |
| `SHARDFLUX_WORKSPACE_KEY` | Optional. Pins one workspace: tools then work on that key only, and `workspace_key` becomes optional. |
| `SHARDFLUX_MCP_TOOL_TIMEOUT_MS` | Optional. Deadline per tool call, 1,000 to 3,600,000 ms. Default 120,000. |
| `SHARDFLUX_AGENT_LABEL` | Optional. The label the server's tool calls are attributed to. Default `mcp`. |

All options are in the [MCP server reference](https://docs.shardflux.dev/reference/mcp.md).

### Claude Code

Add the server for all your projects:

```sh
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:

```json
{
  "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:

```json
{
  "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):

```toml
[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`):

```sh
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:

```json
{
  "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:

```text
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:

| Tool | Does |
| --- | --- |
| `workspace_open` | Opens a workspace by key: creates it on first use, reconnects or resumes it afterwards, never resets it. Waits until it is ready unless `wait: false`. `mode: "file_first"` (0.4.0+) opens a [file-first workspace](https://docs.shardflux.dev/concepts/file-first.md). |
| `workspace_list`, `workspace_status` | Lists the project's workspaces; shows one with its five most recent operations. |
| `workspace_suspend`, `workspace_resume` | Lifecycle operations; return at once unless `wait: true`. |
| `workspace_suspend` with `after_seconds` | (0.4.1+) Suspend when idle: the workspace is suspended once it has been idle for `after_seconds` (30-3600) instead of now. The server asks the agent to do this when it finishes its work. The agent's next tool call on the workspace cancels it; a running command or a keepalive postpones it. See [Suspend when idle](https://docs.shardflux.dev/concepts/lifecycle.md#suspend-when-idle). |
| `workspace_fork` | Forks a workspace into `new_key`. |
| `operation_wait` | Keeps waiting for an operation that outlasted a call. |
| `usage_summary` | The organization's usage for the current period. |
| `send_feedback` | (0.4.0+) Sends feedback straight to the Shardflux founder; see [Send feedback while you work](#send-feedback-while-you-work). |
| `template_get`, `template_languages`, `template_build` | Inspect templates and [build one](https://docs.shardflux.dev/guides/build-a-template.md) from a recipe or a `template.yaml` in the server's working directory. |

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()`](https://docs.shardflux.dev/guides/agent-tools.md#the-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](https://docs.shardflux.dev/guides/files.md)).

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](https://docs.shardflux.dev/concepts/file-first.md) (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](#an-agent-without-an-account)).
- 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](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](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.