Installing

One line, on macOS 13 or later or Linux, arm64 or x64:

curl -fsSL https://github.com/candledottv/harness/releases/latest/download/install.sh | bash

Then open it with candle-harness. The first run walks you through setup.

The installer never uses sudo and never edits your shell’s files. It writes the install folder and a temporary folder it removes. If a check fails, it installs nothing.

Installing it with an agent

You can ask your own agent (Claude Code, Codex and the like) to install it: point it at this section. Setup stays yours, since it signs in to your Candle account and makes a key.

For the agent doing the install:

Check the machine with uname -sm: macOS 13 or later, or Linux, on arm64 or x64. Stop and say so on anything else.
Run the one line above, as it is. Never add sudo.
If the installer asks whether to install or update the Candle CLI, ask the person, and answer as they say.
If it prints a line to add to the PATH, show the person that line and ask before adding it to their shell’s file. Add it exactly as printed.
Check it with candle-harness --version.
Stop there, and tell the person to run candle-harness themselves: setup signs them in to Candle in their browser, and has them choose a wallet and limits.

Never run candle-harness, candle-harness setup or candle auth login for the person; never read, copy or change anything in ~/.config/candle/ or the keychain; never ask for or handle a key, passphrase or recovery phrase; and never change their Candle keys or move funds.

What it checks

The one line trusts the script it downloads. install.sh is fetched from this repository’s releases on GitHub and run as it arrives, so the one-liner trusts GitHub’s copy of that file, as any curl | bash does. Everything the script then installs is checked, as below. The script is signed too: to check it before running it, see Checking a release by hand.

In this order:

Your machine: macOS 13 (Ventura) or later, or Linux, on arm64 or x64.
The Candle CLI. The Candle Harness runs on the CLI, version 0.13.20. If you have no candle, the installer offers to install it, and does so only if you say yes (see below). If yours is older, it offers to run candle update --to cli-v0.13.20, again only on a yes. It needs 0.13.20 or later: from it, the CLI waits while you approve an owner step in your browser, which Candle asks for on steps that widen what a key can do. An older CLI can’t finish those steps once Candle turns this on.
The release: latest.json must name a version and its matching tag (v<version>). If you asked for a release with --to, it must be that one. Without --to, it’s whichever release latest serves: any release this repository ever signed passes the checks below, an older one included, so name the version with --to when it matters which you get.
The checksum: the binary’s SHA-256 must match both the release’s SHA256SUMS and latest.json.
The signature: the binary’s Sigstore signature must come from this repository’s release workflow at exactly this release’s tag:
```
https://github.com/candledottv/harness/.github/workflows/release.yaml@refs/tags/v<version>
```
Your own candle verify checks it, offline. Without a candle it can use, the installer uses cosign or a signed-in gh instead. With none of the three, it installs no candle-harness, and says why. A Candle CLI the same run installed stays where it was put, and the message says where.

Then it puts candle-harness in place, runs candle-harness --version, and says Next: candle-harness. Beside it, it links candle-tui to candle-harness, replacing a 0.2 binary of that name, so the Candle CLI’s candle tui still opens it. The candle-tui name is deprecated and goes in a later release.

Where it puts things

candle-harness goes in the folder that holds your candle, if that folder is yours (you own it and can write to it). Otherwise it goes in ~/.local/bin. A candle installed by Homebrew or npm doesn’t count, since that folder belongs to them. To choose a folder yourself, use --bin-dir.
If that folder isn’t on your PATH, the installer prints the one line to add for your shell (zsh, bash or fish), and you add it yourself. Run it as printed, in your terminal (see “If something goes wrong”).
Your config and state are made on the first run, in ~/.config/candle/harness/, or under CANDLE_HARNESS_HOME if you set it.

If something goes wrong

macOS says “Apple could not verify … is free of malware”. A file downloaded through a browser, Slack or Drive carries macOS’s download mark, and an unpacked folder keeps it on every file. The one-line install fetches with curl, which sets no mark. For a downloaded bundle, clear it from the unpacked folder (xattr -dr com.apple.quarantine <folder>), then install.
candle or candle-harness isn’t found after installing. Add the install folder to your PATH with the line the installer printed, run in your terminal as printed. Copied through a chat, a web page or a notes app, its $ signs and quotes can be changed on the way, and the broken line then runs in every new shell. This form is safe to copy from anywhere, for zsh (macOS’s default):
Terminal window
```
echo 'path=(~/.local/bin $path)' >> ~/.zshrc
```
for bash, echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc, and for fish, fish_add_path ~/.local/bin. Then open a new terminal window and check with command -v candle candle-harness.
Every command says “command not found”, even ls or curl. A broken line in your shell’s start-up file has emptied your PATH. Move the file aside with its full path, open a new window, and add the line above:
Terminal window
```
/bin/mv ~/.zshrc ~/.zshrc.broken
```
Setup says “No keychain available and no CANDLE_KEYRING_PASSPHRASE set” (Linux). The Candle CLI keeps its sign-in in your system’s keychain, and a Linux machine without a desktop session has none. It then uses an encrypted file in its own folder, locked by a passphrase you choose, which it reads from CANDLE_KEYRING_PASSPHRASE. Open your shell’s start-up file (~/.bashrc, or ~/.zshrc) in an editor and add this line, with a passphrase of your own:
Terminal window
```
export CANDLE_KEYRING_PASSPHRASE="<a passphrase of your own>"
```
Don’t type the passphrase into a command at a prompt: it would stay in your shell’s history. Then make the file readable by you alone, open a new terminal and start the Candle Harness again:
Terminal window
```
chmod 600 ~/.bashrc
```
Keep the same passphrase from then on: a different one can’t open the file. Setup shows the same line and the same chmod, each with a copy chip.

Or keep the owner sign-in off this machine, which is the safer way on a server: make each agent’s key on a computer where you’re signed in to Candle, and add it here with candle-harness key add --agent <name>, which asks for the key at a hidden prompt. No passphrase is needed then (Running on a VPS).
Setup says Candle won’t make a key yet (a new Candle account). Candle makes no agent key until the account’s embedded wallet is authorized for agents, and only Candle’s site does that: in the Agent Console (alpha.candle.tv/agents?tab=keys), make a key with Create key and authorize and approve what it asks. You can revoke that key straight after; the authorization stays. Then pick Try again in setup.
Setup says your coding agent isn’t installed. Install it in another terminal tab; setup’s agent step notices within a few seconds. On a Mac without Node, Claude Code installs with Anthropic’s own installer, curl -fsSL https://claude.ai/install.sh | bash. Codex, OpenCode and Pi install with npm, which needs Node first; Grok from x.ai/cli.

The Candle CLI

If you have no candle and say yes, the installer installs Candle’s CLI 0.13.20 from Candle’s release on GitHub (candledottv/cli): candle and its security-key helper, candle-fido2, in the same folder as candle-harness. Each file must match the SHA-256 that this installer carries for that version, and Candle’s own signature for it (checked by that candle), before anything is installed. So you don’t need cosign.

It doesn’t install Candle’s Secure Enclave helper for Touch ID, since 0.13.20 doesn’t ship one. When Candle releases it, candle update brings it.

Prefer Candle’s own installer? Run it first, pinned to the version the Candle Harness was checked against, then run the line above:

curl -fsSL https://candle.tv/install.sh | bash -s -- --to cli-v0.13.20

The Candle Harness runs on a newer CLI too. A command it wasn’t checked against is refused with “checked against 0.13.20”, and candle-harness doctor tells you so.

Options

Put options after bash -s --:

curl -fsSL https://github.com/candledottv/harness/releases/latest/download/install.sh | bash -s -- --to v1.0.0

Option	What it does
`--to <tag>`	Installs that release, such as `v1.0.0`, rather than the latest
`--from <folder>`	Installs from a release folder on this machine, checked the same way
`--bin-dir <dir>`	Puts `candle-harness` (and the CLI, if it installs one) there
`--yes`	Installs or updates the Candle CLI without asking, if it’s missing or too old
`--no-cli`	Doesn’t offer to install or update the CLI

Checking a release by hand

If you’d rather not pipe a script into bash, download the release’s files and check them yourself. Here v1.0.0 and darwin-arm64 stand in for your release and machine:

base=https://github.com/candledottv/harness/releases/download/v1.0.0
for f in candle-harness-darwin-arm64 candle-harness-darwin-arm64.sigstore.json install.sh install.sh.sigstore.json SHA256SUMS latest.json; do
  curl -fsSLO "$base/$f"
done
shasum -a 256 -c SHA256SUMS --ignore-missing

id=https://github.com/candledottv/harness/.github/workflows/release.yaml@refs/tags/v1.0.0
iss=https://token.actions.githubusercontent.com
candle verify candle-harness-darwin-arm64 --bundle candle-harness-darwin-arm64.sigstore.json --identity "$id" --issuer "$iss"
candle verify install.sh --bundle install.sh.sigstore.json --identity "$id" --issuer "$iss"

Always pass --identity and --issuer. Without them, candle verify takes the identity from a latest.json beside the bundle, and that file comes with the release you’re checking.

cosign verify-blob --new-bundle-format --bundle <file>.sigstore.json --certificate-identity "$id" --certificate-oidc-issuer "$iss" <file> makes the same check.

Once both pass, either run the checked install.sh with --from ., or put the binary in place yourself:

bash install.sh --from .

Which version you have

candle-harness version (or --version) prints the Candle Harness’s version and the commit it was built from. candle-harness version --core prints the version of the core that’s running now, as core <version>, or nothing when none runs. candle-harness doctor prints them too, with the Candle CLI’s version.

How the Candle Harness uses Candle’s CLI

The Candle Harness runs your own candle CLI, as the profile setup signed in ([candle] profile in config.toml), so it never acts as another account even if you switch the CLI’s active profile. It starts Candle’s MCP server, candle mcp, once for each agent’s key, and runs the CLI itself for a TEE wallet’s trades and for the steps in the prompt pane. [candle] in config.toml can point it at another candle or RPC: Configuration has each setting.

Updating

Run the install line again. It replaces candle-harness in place and leaves your config and state alone.

Then restart the core. A core that’s already running (kept up by a trigger, a bot or the login service) carries on as the version it started as. The installer never stops it, since your triggers and bots are running in it. The installer says when a core from an older version is still running, and so do candle-harness doctor and the status bar, which shows the core is still <version> with a restart it chip.

To move it to the new version, open candle-harness and click restart it. With the login service installed, the new core is the service’s, so it runs on after you quit. From a shell instead:

candle-harness stop
candle-harness                   # or, with the login service: candle-harness service install

Opened this way, the new core is the window’s own, and it stops a minute after you quit unless a trigger or bot is on. With the login service, candle-harness service install starts the service’s core instead.

Update from anything before 0.5.2. Older builds read a bunfig.toml or .env file from the folder they were started in. From 0.5.2 the binary reads neither.

Uninstalling

Revoke each agent’s key first, from Candle’s app or with candle keys revoke. Deleting the Candle Harness’s files doesn’t revoke anything at Candle.
Remove the login service, then stop the core, while the binary is still there to do it. Otherwise the core, its bots and the login job are left running:
Terminal window
```
candle-harness service uninstall
candle-harness stop
```

Remove the binary, and the candle-tui link beside it:

rm "$(dirname "$(command -v candle-harness)")/candle-tui" "$(command -v candle-harness)"

Remove the config and state, if you want them gone too. This deletes the agents’ keys, their memory and the journal:
Terminal window
```
rm -rf ~/.config/candle/harness
```

The Candle CLI stays, along with its profiles and vault. They’re Candle’s, and the Candle Harness never removes them.