# Set up Shardflux with your coding agent

> Ask Claude Code, Codex or Cursor to install Shardflux. It asks one question, then sets up your product or your own cloud coding agents.

Ask your coding agent to install Shardflux. This page is the order it follows. Agents: work through it top to
bottom, and ask your user wherever it says **Ask**.

```sh
npm i -g shardflux
```

The CLI needs Node.js 24 or later. Every command takes `--json`, reads secrets only from standard input and has
documented [exit codes](https://docs.shardflux.dev/reference/cli.md#exit-codes).

## First, one question

**Ask:** Is Shardflux for a SaaS platform, or for your personal setup?

| Answer | What it means | What gets set up |
| --- | --- | --- |
| SaaS platform | Your product runs VMs for its own customers through the API, SDK or MCP | An account, an API key for your product, the integration, and templates for your customers' workspaces |
| Personal setup | Your own cloud coding agents: each Claude or Codex conversation gets its own VM | Your account, Claude and Codex, your machine, your project, then `shard ./` |

## Sign in

Both answers start here.

**Ask:** Do you agree to the [Terms of Service](https://shardflux.dev/terms) and the
[Privacy Policy](https://shardflux.dev/privacy)? Continue once your user does.

```sh
shard signup --accept-terms --json
```

With the Codex CLI signed in with ChatGPT on this computer, `signup` signs up (or signs in) with that login, no
browser, then saves an organization, a project and an API key. A new account starts with 60 days of Pro.

Without a Codex login, or for an account your user already has, sign in in the browser:

```sh
shard auth login --browser --no-open --json
shard setup --json
```

The first line it prints is `{"event":"open",...}` with the link and the code: give both to your user. It ends with
`{"event":"signed_in",...}` once they approve, within 10 minutes; run it in the background if your tool stops
commands sooner. `shard setup` then saves the organization, project and API key, and is safe to run again.

## SaaS platform

Your product calls Shardflux with a project API key. Claude and Codex sign-ins, the menu bar and the machine are for
personal cloud coding agents, so skip them.

1. `eval "$(shard env)"` exports `SHARDFLUX_API_KEY` for the SDKs and the MCP server. Put the key in your product's
   server-side secrets.
2. Integrate with the TypeScript SDK (`npm install @shardflux/sdk`), the Python SDK (`pip install shardflux`), the
   [HTTP API](https://docs.shardflux.dev/reference/http-api.md) or the [MCP server](https://docs.shardflux.dev/reference/mcp.md). The [quickstart](https://docs.shardflux.dev/quickstart.md#build-with-the-workspace-api)
   runs a complete example.
3. Give your customers' workspaces what they need from the first second:
   [build a template](https://docs.shardflux.dev/guides/build-a-template.md) with `shard templates build template.yaml`.
4. Choose a plan when you need more: `shard billing upgrade <plan> --json` prints the Stripe Checkout URL for your
   user.

## Personal setup

Each Claude or Codex conversation gets its own VM, started from your **machine** (tools, logins, dotfiles and agent
config) and the project's **template** (dependencies, services and secrets).

### 1. Connect Claude and Codex

**Ask:** Which do you use: Claude, Codex or both?

- **Claude** uses one cloud sign-in for your account. Your user runs this in their own terminal, once: it shows a
  claude.ai link and asks for the code.

  ```sh
  shard agents credentials login claude
  ```

- **Codex** uses this computer's Codex login: `codex login` (with ChatGPT), once.

Then check both live and finish the Codex connection:

```sh
shard setup --inspect --connect --json --apps claude,codex
```

Each connection reports `verified`, or the action that completes it. Pass only the apps your user picked.

### 2. Build the machine

**Ask:** What should every cloud agent start with?

- Languages and runtimes, such as Node.js 24, Python with uv, Go or Rust
- CLIs and tools, such as gh, the AWS CLI, Terraform or ripgrep
- Dotfiles and shell: `.gitconfig` with their name and email, shell config and aliases
- Secrets and credentials that tools read from files, such as `~/.npmrc` or `gh` auth
- Editor and agent config: `CLAUDE.md` and `AGENTS.md`, Claude and Codex settings, skills and MCP servers

Write the answers as one brief. Your user runs `shard machine` in their own terminal and pastes the brief to the
machine agent, which installs and configures everything in the machine VM. Then save it:

```sh
shard machine save --wait --json
```

The first open copies this computer's Claude and Codex settings into the machine. Every new conversation starts from
the saved version; [Machine and template](https://docs.shardflux.dev/guides/machine-and-template.md) covers changes and rollback.

### 3. Set up the project

**Ask:** Which project, which secrets does it need, and what does a good first run look like (the tests, a dev
server)?

Import the project's secrets from your user's vault, then start a conversation in the project folder:

```sh
shard secrets import --from 1password 'op://Private/GitHub/token' --as GITHUB_TOKEN
shard ./ --json --prompt "Set up this project and run its tests"
shard conversations wait <conversation-id> --timeout 90
shard template --json
```

`shard ./ --json` starts the conversation in its own VM and prints it (`conversation.id`); use `shard ./ codex
--json ...` for Codex. Setup installs the dependencies, runs the build and tests and saves the project template
in the background. `conversations wait` returns the agent's result or question; run it again while it says
`Still working.` `shard template` shows the saved version. Tell setup what to skip or how to run a step in
[`.shardflux/setup.yaml`](https://docs.shardflux.dev/guides/machine-and-template.md#choose-what-setup-prepares).

### 4. Hand over

Your user runs this in their own terminal, from the project folder:

```sh
shard ./
```

It opens Claude Code in a new conversation VM (`shard ./ codex` for Codex). Claude conversations continue on
claude.ai and in the Claude app; Codex threads continue in the Codex app, on the web and on the phone. T3 Code,
Claude Desktop and the Codex app work too: see [Cloud conversations](https://docs.shardflux.dev/guides/cloud-agents.md).

## What your user does

Answer the question, agree to the terms, approve the browser sign-in, sign in to Claude in their terminal and run
`codex login`, describe their machine and project, and pay in Stripe Checkout when they choose a plan. The agent
does the rest.