Machine and template

Install once with npm i -g shardflux, then use the shard command.

Two saved environments

Cloud agents start from your machine plus the project's template (CLI 0.13.2+, npm bundle 0.15.0+). The machine carries your device-level environment across projects. The template carries what this project needs.

Both are filesystem templates, so your own tools and files work as they do in the environment you saved. They are private to your account and contain secrets as ordinary files; agents started from them receive those files.

Prepare your project while you work

cd your-project
shard ./

Start using Claude Code or Codex immediately. Setup runs in the background, prepares dependencies and services, and saves the project's template. The next agent starts ready from that environment. A change to dependency files starts another setup and saves a new version.

Choose what setup prepares

Setup finds every project in the repository: each package.json, pyproject.toml, go.mod and Cargo.toml with its lockfile, installs locked dependencies and runs each project's build and test. List the directories it should leave alone, such as fixtures, seed inputs and examples, in .shardflux/setup.yaml (coding template 7+):

exclude:
  - fixtures
  - images/*/seed
  - "**/testdata"

Each entry is a directory relative to the repository root, including everything inside it. * matches within one directory name and ** matches any number of directories. Setup reads the file each time it prepares the project and leaves your manifests and lockfiles exactly as committed.

Save a change

Open your machine agent to change the device-level environment, then save it:

shard machine
shard machine save --wait

--wait returns once the new version is ready (CLI 0.13.3+); without it, save prints the version it is saving and shard machine shows when it is ready.

From the project, inspect and save its environment:

shard template
shard template save

shard machine --json reads its saved filesystem status. Install tools normally inside the machine VM, edit dotfiles and Claude/Codex settings, and sign in to the browser. Use machine save to carry that environment across projects. Use template save for a project's package, service or secret. Changed files propagate live to running agents; changed software applies at their next start. Your agent's working copy, branch, build output and service data remain its own.

The saved machine is the source of the files it carries, such as dotfiles, ~/.claude.json and other agent settings. Running agents receive those files live from the saved version when they start and each time a new version is saved, and that delivery replaces an edit made to the same file inside a project agent. Make lasting changes to these files in shard machine, then run shard machine save; every running agent receives the new version. Files saved in a project template follow the same rule: change them in the project's agent, then run shard template save.

Save from inside the VM

Your agent uses the same shard machine save and shard template save commands inside its VM. It can install a tool, update a setting or sign in, then save the environment for the next agent. Rollback uses the same commands on your laptop and in the VM. shard templates remains the platform template build and management group.

Return to a saved version

shard machine rollback
shard template rollback

Rollback selects the previous saved version by default; --to <version> selects a particular saved version. Files propagate to running agents and software applies at their next start, as it does after save. Lifecycle explains the start boundary. Fork an agent to try changes with the whole running state copied into an independent workspace and conversation.