Installing Crucible

Installing Crucible

Four supported paths. Pick the one that matches how you want to run it.

1. Source (recommended today)

Source access is granted, not public

The AgentStateCrucible repository is not public during early access, so the git clone below will not resolve yet. It works as written once the repository is public.

Fastest path while prebuilt releases aren’t published yet.

git clone https://github.com/agentstatelabs/AgentStateGraph ../AgentStateGraph
git clone https://github.com/agentstatelabs/AgentStateCrucible   # requires granted access
cd AgentStateCrucible
./install.sh

The installer:

1. cargo installs the crucible binary into ~/.cargo/bin.
2. Builds the SvelteKit UI bundle at web/build (if npm is present).
3. Prints next-step commands.

Requires Rust 1.83+ and (optionally) Node 22+.

Undo with ./uninstall.sh.

2. Docker Compose

One command, no toolchain on the host. Bakes the binary + UI + bundled scenarios into a single image and serves the whole stack on port 8080.

git clone https://github.com/agentstatelabs/AgentStateGraph ../AgentStateGraph
git clone https://github.com/agentstatelabs/AgentStateCrucible   # requires granted access
cd AgentStateCrucible
export OPENAI_API_KEY=sk-...
docker compose up --build
# → http://127.0.0.1:8080 (UI) and http://127.0.0.1:8080/api/... (JSON)

Persisted sessions live in the crucible-state named volume. docker compose down keeps them; add -v to drop.

The Dockerfile uses BuildKit’s --build-context to pull in the sibling AgentStateGraph checkout. When ASG publishes to a registry we’ll drop that context and swap the workspace deps for version pins.

3. cargo install (developers)

If you already have the workspace open:

cargo install --path crates/crucible-cli --locked

Works well when you’re iterating on Crucible itself and want the binary reflected instantly.

4. Homebrew tap — coming with release binaries

Once a tag pipeline produces release artifacts, packaging/homebrew/

• scripts/render-homebrew.sh render a versioned formula that the agentstatelabs/crucible tap consumes:

brew tap agentstatelabs/crucible
brew install crucible

See docs/RELEASE.md for the render + tap-push flow.

After install: what next?

export OPENAI_API_KEY=sk-...              # required for live runs

# One-shot A/B, prints JSON verdict
crucible run scenarios/asd-vs-baseline.md \
    --model openai/gpt-4o-mini --state-dir ~/.crucible-state

# Serve the API + UI on :8080
crucible serve --state-dir ~/.crucible-state \
               --web-dir "$(pwd)/web/build"

# Or as an MCP server (Claude Code / Cursor / Codex)
cat packaging/mcp/README.md

crucible doctor (or GET /api/doctor?scenario=...) runs preflight checks: provider keys, asd binary, ctx reachability, fixture presence, budget sanity, cost estimate.