# Install Chief Runtime

Chief Runtime is distributed as checksummed Linux and macOS binaries for amd64
and arm64. The public release channel does not require a GitHub account or
access to Chief's source repository.

## Prerequisites

Generic lane compatibility requires **Codex CLI 0.153.4 or newer** or
**Claude Code 2.1.261 or newer**. Setup enables the compatible installed
generic lane profiles; an older engine does not enable its corresponding
profile. Version compatibility is separate from authentication and from the
choice to upgrade an existing principal harness. See the
[engine compatibility release note](../docs/releases/lane-engine-minimums.md).

Install `curl` and `tmux` first. On macOS:

```sh
brew install tmux
```

On Ubuntu or Debian:

```sh
sudo apt-get update
sudo apt-get install -y tmux
```

You choose how Chief thinks:

- **Cloud** — Slack replies use Claude Code. Install and log in with
  [Anthropic's official setup](https://code.claude.com/docs/en/setup).
- **Hermes** — Slack replies use Hermes Agent on this machine. Hermes is a
  **harness**, not a `provider`. The switch is `keeper.harness=hermes` plus the
  four `keeper.hermes_*` keys. `keeper.hermes_profile` is `chief-principal`, not
  the switch. Set `keeper.model` (Grok `grok-4.6` is the recommended first
  model). `keeper.hermes_url` is the owned JSON-RPC gateway
  (`ws://127.0.0.1:<port>/api/ws`); do not point it at `hermes proxy`. Do not
  run `hermes model` or create a Hermes profile. Hermes' default TUI profile
  is not the Slack principal. Linux starts `chief-hermes-gateway.service` on
  demand; macOS starts LaunchAgent `com.chiefruntime.hermes-gateway` on demand.
  Do not infer units from `strings`. `invalid provider "hermes"` or `"grok"`
  means you probed the old provider list (`claude`/`codex` only); it does not
  mean this build cannot run Hermes or Grok. Grok on Hermes needs
  `hermes auth add xai-oauth` (not `hermes login`, not `xai --type oauth`).
- **Lanes** (delegated work) are separate: Claude Code, Codex CLI, Pi, and
  Grok (`grok-tmux`). Codex lanes use the official `@openai/codex` package;
  follow [official Codex CLI setup](https://developers.openai.com/codex/cli).
  Codex-as-Chief (resident) is mothballed; Codex lanes still work.

Log each machine in normally. Never copy an auth file from another machine
because refresh-token rotation can invalidate both copies.

The first command after a working `chief` on PATH is `chief maintenance`.
That chat finishes Slack, the Cloud vs Hermes choice, and the model. Do not
treat a Claude-only `chief provider status` on a fresh box as the catalog.
`chief maintenance --backend hermes` or `--backend claude` opens that repair
chat on the named harness for one session; it does not persist. Grok is not a
`--backend` value.

Create and install Chief's Slack app from the reviewed YAML in the
[Slack connection guide](SLACK.md). This step needs a desktop browser. Do not
derive scopes from source or configure permissions one by one.

## Install from npm

If Node.js 16+ is available, npm is the shortest path. The package carries the
same checksummed binary as the release channel below:

```sh
npm install -g @mightybot/chief@latest
chief version
```

Release candidates publish under `@next`. Prefer a global install over `npx`
for any host that will run Chief's services: the units start the binary from
`services.binary_path`, which needs a stable location, and the `npx` cache is
not one.

## Install a verified binary

The installer announces each network and verification step, selects the host's
operating system and architecture, verifies the binary and release manifests,
checks the binary's stamped identity before mutation, and installs atomically:

```sh
curl --proto '=https' --tlsv1.2 -fsSL \
  https://mightybot-ai.github.io/chief/install.sh | sh
```

It installs `$HOME/.local/bin/chief` and preserves the selected binary,
`SHA256SUMS`, `EMBEDDED-ASSETS.json`, and `RELEASE-METADATA.json` under
`$HOME/.local/share/chief/releases/VERSION`. Add `$HOME/.local/bin` to `PATH`
if needed, then read the exact version and source revision:

```sh
chief version
```

To install an immutable earlier version or use another user-owned binary
directory:

```sh
curl --proto '=https' --tlsv1.2 -fsSL \
  https://mightybot-ai.github.io/chief/install.sh |
  CHIEF_VERSION=1.2.3 CHIEF_INSTALL_DIR="$HOME/bin" sh
```

A checksum or identity mismatch stops before the existing binary is replaced.
The installer never uses `sudo`, reads credentials, or runs setup for you.

## Create the base configuration

Product assets, managed configuration, and private runtime state must be
disjoint. Create `$HOME/.chief/config.toml` with mode `0600`, replacing every
`/absolute/home`, Slack ID, transcript ID, and token-file path with the reviewed
value for this machine:

```toml
[paths]
managed_dir = "/absolute/home/.chief"
agent_config_dir = "/absolute/home/.claude"
codex_config_dir = "/absolute/home/.codex"
codex_skills_dir = "/absolute/home/.agents/skills"
state_dir = "/absolute/home/.local/state/chief"
vault_dir = "/absolute/home/.local/state/chief/vault"

[runtime]
mode = "live"

[slack]
api_base_url = "https://slack.com/api"
app_token_file = "/absolute/home/.config/chief-secrets/slack-app.token"
bot_token_file = "/absolute/home/.config/chief-secrets/slack-bot.token"
operator_ids = "U012ABCDEF"
slash_allowlist = "U012ABCDEF"
control_room = "C012ABCDEF"
bot_user_id = "U987ZYXWVU"
workspace_url = "https://reviewed-workspace.slack.com"
# Private operator DM used as the audited tripwire for slash commands and
# expanded reach. Verify this destination before setting echo_verified=true.
echo_channel = "D012ABCDEF"
echo_verified = true

[tmux]
# Optional private tmux server. Keeper, Monitor, observation, callbacks, and
# maintenance/compaction all use the same configured socket.
# socket_name = "chief-private"

[services]
# Start in manual mode so setup renders units without mutating a service
# manager. Change to "native" only after reviewing the first setup.
mode = "manual"
binary_path = "/absolute/home/.local/bin/chief"

[backup]
schedule = "disabled"
config_path = "/absolute/home/.chief/backup-v1.json"

[keeper]
session = "chief"
cwd = "/absolute/home"
transcript = "the-durable-chief-transcript-id"
maintenance_transcript = "the-durable-repair-transcript-id"
agent = "claude"
bootstrap = "/chief-runtime"

[main]
session = "chief-main"
cwd = "/absolute/home"
transcript = "the-durable-main-cockpit-transcript-id"
agent = "claude"
bootstrap = "/chief-runtime"
```

The local read-only game board is disabled by default. To serve it from the
same daemon, add an explicit literal-loopback address, restart the reviewed
daemon normally, and open that exact address in a local browser:

```toml
[dashboard]
address = "127.0.0.1:7464"
```

Chief rejects hostnames, wildcard addresses, public interfaces, and port zero.
The board makes no external requests and exposes a bounded cached projection;
it does not expose configuration, environment, credentials, or transcripts.

The Slack entries are references or public identities, never token values.
Create each referenced token file as a same-user, regular, non-symlink file
with mode `0600`. Doctor, status, dry-run, and shadow mode do not read them; a
successful live native setup resolves them only for its final hello-DM proof.
`echo_channel` is the operator's reviewed Slack DM, not the control room; slash
handling and expanded reach fail closed unless that destination is set and
`echo_verified=true`. `control_room` may be either a reviewed `C…` channel or
the operator's existing `D…` conversation with Chief; a DM control room is a
supported topology, not a degraded compatibility mode.

## Materialize without starting services

Review the complete first change in manual mode:

```sh
chmod 0600 "$HOME/.chief/config.toml"
export CHIEF_CONFIG="$HOME/.chief/config.toml"
chief setup --dry-run
chief setup
chief lane engines --json
chief doctor --json
chief skills ls
chief skills diff
chief maintenance
```

Setup runs a local compatibility scan before changing the estate. It requires
Codex CLI 0.153.4 or newer, or Claude Code 2.1.261 or newer, enables every
compatible installed generic lane transport, and fails with installation and
inspection guidance if none exists. The scan only invokes `--version`: it does
not read engine credentials, authenticate, or make a model call. Existing lane
profile overrides and unrelated settings are preserved; a failed zero-lane
scan leaves the configuration unchanged. Inventory therefore distinguishes
`installed`, `version_compatible`, and `enabled` from
`authentication: "unverified"`.

Install an operator skill from a real directory whose top-level `SKILL.md`
has `name` and `description` frontmatter:

```sh
chief skills add /absolute/path/to/my-skill
chief skills ls
chief doctor --json
```

Chief validates bounded regular files, rejects symlinks, copies the validated
version into the operator configuration plane, and registers exact links for
both Claude and Codex. The copy and its registry are deliberately not product
manifest-owned. If its name collides with an embedded skill, pass `--replace`:
the operator skill wins, inventory says it shadows the embedded skill, and
doctor reports its discoverability and observed load count. Setup upgrades
continue to own the embedded copy but never overwrite the operator version.

Inventory an existing agent estate without printing skill bodies, MCP commands
or arguments, credential values, or prompt text:

```sh
chief link scan --json
```

For the guided flow, first start or resume the maintenance chat and deliver its
durable, idempotent canned episode:

```sh
chief maintenance link-capabilities
```

That chat surveys and classifies the scan, proposes a plan, and applies only
reviewed items. Every linking command requires item-specific
`--yes`; there is no blanket adoption:

```sh
chief link adopt skill /absolute/path/to/my-skill --yes
chief link adopt credential SEARCH_TOKEN --from /secure/search-token --yes
chief link adopt mcp search --from /absolute/path/to/mcp.json --yes
chief link adopt customization /absolute/path/to/operator-CLAUDE.md --yes
chief doctor --json
```

Credential adoption registers an owner-only file pointer for both engine
profiles and never reads or copies its value. An adopted MCP registration may
use `${SEARCH_TOKEN}` but is refused if its source contains a literal
environment value. MCP entries render into both engine registrations; a
customization becomes a digest-pinned prompt overlay. Use `--replace` only for
a reviewed skill, MCP registration, or credential pointer already registered.
An existing skill already under an engine's configuration root stays in place
and outside manifest ownership; a matching copy/link in the other engine root
does too. When an existing `CLAUDE.md` is adopted, setup first writes the
combined managed prompt and records a timestamped recoverable backup of the
original before replacing that exact consented path with its registration link.

Manual mode makes no service-manager calls. Doctor reports activation as
operator-owned and unverified, which is expected. Setup validates all required
values before mutation and records its ownership manifest before service
readiness.

`chief maintenance` is the documented next step after setup. It opens the
singleton, model-pinned repair chat and proves that the exact agent process and
composer are usable before reporting success. Ask it to resolve any red doctor
fact and verify the result; its minimal diagnose/repair/snapshot/verify skills
and default-ask permission policy bootstrap even when the daemon or the rest
of setup is broken. The terminal
door requires an authenticated Claude Code engine on this machine, but it does
not require Slack.

After reviewing the rendered units, change `services.mode` to `native` and run
`chief setup` again to install and start the user services. Linux uses systemd
user units and macOS uses launchd. Native Windows activation is not supported.
The final step sends one idempotent welcome to the configured operator DM and
reads it back. A Slack failure is reported without rolling back a sound estate;
follow [SLACK.md](SLACK.md) and do not claim connection until the hello is
visible.

For a deliberate native-service bounce, use `chief restart --wait 2m`. It
waits for active Chief turns and lanes, refuses at the deadline with their
exact identities, verifies every restarted native service plus a new daemon
boot, and does not charge the supervision crash counter. `--force` is an
explicit, loudly reported preemption;
manual service mode is refused because Chief does not own that supervisor.

Do not enable backup schedules until their separate config and first manual
run have been reviewed. The Git-backed estate updater is retired; Chief does
not fetch or sync Git. Do not copy credentials between boxes.