ChipChop Runner

The local half of ChipChop's RTL design agents. Agent reasoning runs in our cloud; your files, your EDA tools, and your model API key stay on your machine.

Install

macOS and Linux:

curl -fsSL https://downloads.chipchop.ninja/runner/install.sh | sh

Windows (PowerShell):

irm https://downloads.chipchop.ninja/runner/install.ps1 | iex

Prefer to read it first? That is the better habit:

curl -fsSL https://downloads.chipchop.ninja/runner/install.sh -o install.sh
less install.sh
sh install.sh

Requires Python 3.11 or newer. The installer uses pipx if you have it and otherwise creates a self-contained virtualenv under ~/.local/share/chipchop.

What it does on your machine

This is not a passive library. The runner reads and writes files in your project and runs EDA tools as subprocesses, on behalf of an agent running in our cloud. It is worth knowing how that is bounded:

Policy. An agent requests paths, binaries, and token budgets; your ~/.chipchop/policy.json grants them. Anything ungranted is refused. The cloud cannot widen its own authority.
Approvals. Writes and tool runs prompt you before they happen.
Your key stays local. When the agent needs a model call, the runner makes it from here and returns only the result.
Audit. Every session, tool result, approval, and denial is appended to ~/.chipchop/audit/runner.jsonl — what happened, never prompts, file contents, or credentials.
No agent code is downloaded. The wheel contains transport, policy, and tools. No prompts, no planning logic.

First run

You need one model provider key. Put it in ~/.chipchop/.env before step 4:

LLM_MODE=gemini
GEMINI_API_KEY=...

# or LLM_MODE=openai / OPENAI_API_KEY=...
# or LLM_MODE=claude / ANTHROPIC_API_KEY=...

chipchop login — opens your browser to sign in.
chipchop init-policy — writes a starter grant you can edit.
chipchop doctor — checks the connection, your workspace, and your tools.
cd to your project and run chipchop wizard, then choose an agent.

There is nothing else to configure. Backend settings are fetched on first run and cached locally; chipchop doctor --refresh re-fetches them.

Verifying the download

The installer checks the wheel's SHA-256 against latest.json. Both come from this host, so that catches a truncated transfer or a stale cache — not a compromised origin. For that, verify the signature:

cosign verify-blob \
  --bundle chipchop_runner-<version>-py3-none-any.whl.cosign.bundle \
  --certificate-identity-regexp '^https://github\.com/chipchopai/chipchopai/\.github/workflows/runner-release\.yml@refs/tags/runner-v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  chipchop_runner-<version>-py3-none-any.whl

Optional, and most people will not do it. It proves the wheel was built by our release workflow from a tagged commit.

Installing a specific version

CHIPCHOP_RUNNER_VERSION=0.1.0 sh install.sh

Or install the wheel yourself from https://downloads.chipchop.ninja/runner/<version>/chipchop_runner-<version>-py3-none-any.whl.

If `chipchop` already exists

If you have the ChipChop development repo installed, both provide a chipchop command and whichever is earlier on your PATH wins. The runner always also installs chipchop-runner, which is unambiguous.

Report problems with the output of chipchop doctor --json, which describes your configuration without disclosing credentials.