Cloud agents

Start from your project

Run your coding agent with your tools, logins and project ready (CLI 0.13.2+, npm bundle 0.15.0+):

npm i -g shardflux
shard setup
cd your-project
shard ./

shard setup connects your Shardflux account and project. The quickstart covers your first run. Choose Claude Code or Codex; shard ./ codex selects Codex. shard opens the command center for all your projects. Your repository appears at /home/user/<project> in the agent's workspace.

The agent is usable immediately. Project setup runs in the background: it installs dependencies, prepares services and saves the project's environment for the next agent. Every later agent starts from your saved machine and project template. You can close your laptop while the agent keeps working.

Your machine and project template

Your machine is your device-level environment: tools, credentials, dotfiles, browser logins, git identity, Claude/Codex settings and skills. Your template is the project environment: toolchains, dependencies, services and project secrets. Both are saved filesystem templates (CLI 0.13.2+).

shard machine
shard machine save
shard template
shard template save

Install tools, set up secrets, sign in to the browser and edit Claude/Codex configuration normally inside the VM, then save the environment you want other agents to use. The agent inside the VM uses these same save/rollback commands. Changed files reach running agents live; software changes apply at their next start. Each agent keeps its own repository changes and service data. shard machine rollback and shard template rollback return to a saved version. See Machine and template for the workflow.

Machine and project templates contain secrets as ordinary files and are private to your account; every agent started from them receives those files.

Sign in once

On your first Claude launch, follow the URL and code to sign in once for your Shardflux account. This cloud sign-in is shared by your cloud agents and refreshed by Shardflux. Your laptop's Claude login stays separate. Codex uses the copied login from this machine's ~/.codex/auth.json (CLI 0.13.2+).

Cloud agents run with permissions to work unattended. Add --approvals to keep the agent's interactive approval prompts. Claude and Codex managed sign-in files are delivered privately when an agent starts and refreshes.

Use the command center

The center groups projects, agents and sessions, with the ones that need you first (CLI 0.13.2+).

shard --json and shard ./ --json return the center's projects, workspaces and agents. shard status --json reports workspaces, sessions and shared volumes. See CLI commands.

Open a session in your own app

Open the agent's workspace in the app you use (CLI 0.13.2+):

shard agents open acme-web/main
shard agents open claude-desktop acme-web/main
shard agents open codex-app acme-web/main
shard agents open web acme-web/main

• Terminal: attach to the running Claude Code or Codex session. Resize and reconnect preserve your position. Close the terminal, or press Ctrl-] then d, to detach; use the app's exit command to end the session.
• Claude Desktop: select the CLI's managed SSH environment after restarting Desktop, then open /home/user/acme-web. This opens a Desktop conversation in the same agent workspace.
• Codex app: select the imported SSH connection and project. Settings → Connections → SSH lets you enable a saved connection. This opens a Codex app conversation in the same workspace.
• claude.ai and Claude mobile: web opens the terminal Claude conversation through Remote Control. Session titles begin with [SF] . Open that conversation in the mobile app too.

shard agents targets acme-web/main prepares the desktop connections. SSH wakes a parked workspace on connect. Waiting Claude agents stay reachable from claude.ai and mobile for 30 minutes by default: a reply wakes them. Choose the window with --reachable, as described in agent reachability.

Fork another approach

Fork your current agent when you want to try an idea from exactly where you are (CLI 0.13.2+):

shard agents fork acme-web/main experiment
shard agents open acme-web/experiment

A fork copies the whole running state: files, installed software, memory, processes and services. It keeps the machine and project environment and gets its own agent conversation. Press f in the command center for the same workflow. A fresh agent uses the saved machine and template instead:

shard agents new --path . --name review --like acme-web/main --app claude

Shared volumes remain shared; their contents are outside the fork's copy.

Bring the work back

Inspect the agent in a local editor worktree, then choose its disposition (CLI 0.13.2+):

shard agents worktree acme-web/experiment --path .
shard agents merge acme-web/experiment --path .
shard agents keep acme-web/review --path .

Merge brings committed work into your current branch. Keep creates shard/<agent>; add --push to push it and open a pull request with gh. shard agents discard acme-web/review --path . discards that agent's work. Saved Git work describes recovery.

While the main agent is attached, project files sync in both directions; the next attachment catches up after a disconnect. Extra agents return their work through Git. Read sync bounds for file selection and conflict copies. Synced secrets remain ordinary files in the workspace and saved project environment.

Bring credentials from your vault

Import named secrets from hsec, 1Password, Bitwarden or macOS Keychain, and approve browser logins without giving passwords to the agent (CLI 0.13.2+, MCP 0.12.0+). The attached CLI or menu bar app asks Allow once or Always for this project; Remember for unattended use keeps the selected login available with your laptop closed.

Sent end to end from your vault to the workspace; Shardflux only relays encrypted bytes. Remembered credentials: stored encrypted with AWS KMS and filled straight into the page; agents never see it, and every use is logged.

Credentials covers imports, approved fills, automatic relay renewal and output redaction.

Keep agents in the menu bar

On macOS 14 or later, the menu bar starts automatically the first time shard runs, with launch at login enabled (CLI 0.13.2+, @shardflux/menubar-darwin 0.1.0+). It shows sessions and states. Notifications tell you when an agent needs you; clicking opens it in your remembered app.

shard menubar status --json
shard menubar stop

shard menubar stop turns it off, including launch at login. See agent states and lifecycle.