Install

One command

curl -fsSL https://runchief.ai/install.sh | sh

That downloads a prebuilt chief for your platform, verifies its SHA-256 checksum against the one published alongside it, and installs it. No clone, no Rust toolchain, no build.

It installs to /usr/local/bin when that directory is writable — which it usually is on macOS and inside a container — and to ~/.local/bin otherwise. The last line it prints is the path it actually used. If that directory is not on your PATH, the installer says so and prints the exact line to add.

Supported: macOS (Apple silicon and Intel) and Linux (x86_64 and arm64). The Linux builds need glibc 2.34 or newer — Ubuntu 22.04+, Debian 12+, RHEL 9+. Set CHIEF_INSTALL_DIR to install somewhere else.

Running an agent inside a Linux container on an Apple-silicon Mac? That is linux-arm64, and it is built and published.

Upgrade

chief upgrade

The command checks the published version, downloads the archive for the current platform, verifies its SHA-256 checksum and single-binary layout, proves the new binary can run, and atomically replaces the exact chief executable that was invoked. It preserves ~/.chief, including the current login and configuration. If Chief is already current, it says so and changes nothing.

Chief 0.1.12 and earlier predate this command. Upgrade one of those versions with the installer once; after that, use chief upgrade:

curl -fsSL https://runchief.ai/install.sh | sh

The desktop runtime

Acquisition works without a machine: Chief reads your mail, calendar and documents from the cloud, and stores and indexes all of it — so chief search, provenance and live source queries work straight away.

Understanding does not. Chief thinks on your own machine, through your own model subscription, so without a desktop runtime nothing is ever turned into claims: you get a searchable archive with provenance, not a memory of meaning, and there is nothing to recall. Everything already stored is understood as soon as a machine that can do it appears, so nothing is lost by installing later — but nothing is understood before then either.

The desktop runtime is also the only thing that can read the files on your machine — an Obsidian vault, and the notes you actually write.

macOS

Download it from runchief.ai/download/mac: open the disk image, drag Chief into Applications, launch it and sign in with your invited account. The build is signed with an Apple Developer ID and notarized, so Gatekeeper opens it without argument, and the page publishes a SHA-256 beside it.

It requires an Apple-silicon Mac on macOS 15 or later. The chief CLI runs on Intel Macs and the desktop app does not, so an Intel Mac can hold a credential and query memory but cannot yet run the understanding step — which means mail arrives and is searchable and no claims are made from it. That is a real limitation and not a preference; it is stated here rather than discovered after installing.

In Chief, open Settings → General → Local intelligence. Select an installed, signed-in Claude Code or Codex account and turn local intelligence on. Installing the app alone does not enable it. Keep Chief open while it catches up.

To update the Mac app, quit Chief, download the current disk image from the same page, replace Chief in Applications, and reopen it. chief upgrade updates the CLI only. The Mac update preserves the existing account and connector state.

Linux

curl -fsSL https://runchief.ai/desktop.sh | sh
chief-desktop login
chief-desktop intelligence setup
chief-desktop connect ~/notes
chief-desktop run

It downloads the runtime for your architecture, checks it against the checksum published beside it, and unpacks it into ~/.local/share/chief-desktop with a chief-desktop shim in ~/.local/bin. It asks for no sudo and touches nothing outside your home directory. It also does not start anything: chief-desktop run starts Chief, and chief-desktop install-service runs it at login, because both are decisions rather than side effects of installing.

chief-desktop intelligence setup is the Linux form of the Mac app's Local intelligence setting, and it is the step that turns understanding on. It names the installed, signed-in Claude Code or Codex account it will use and asks for consent; --yes with --harness claude|codex does the same without a prompt, and chief-desktop intelligence off turns it off again, after which judgment work waits rather than falling back to anything. Installing the runtime alone registers a device that cannot understand, and Home will keep saying so. chief-desktop intelligence status shows the saved route, cumulative token usage and the latest turn receipt.

chief-desktop doctor says what it can and cannot do on your machine. Read what it says about credential storage: Chief uses your login keyring when one answers, and a 0600 file when none does. That file is not encrypted at rest, and both login and status say so rather than letting you assume otherwise.

To update the runtime:

chief-desktop upgrade

It fetches the published version for your architecture, verifies it against its checksum, replaces the runtime in place, and preserves the sign-in, the vault list and the local-intelligence choice. chief upgrade updates the CLI only. A runtime older than 0.1.4 predates this command: re-run curl -fsSL https://runchief.ai/desktop.sh | sh once — the installer replaces the runtime in place and keeps the sign-in and the vault list — and use chief-desktop upgrade from then on.

There is no Linux build of the Mac app's window. What the runtime adds is the two things a browser cannot do: run the understanding step on your machine, and reach your filesystem. The web app at runchief.ai is chat and settings; memory is read through the CLI, the skill, or MCP.

macOS users do not need this: the Chief app for Mac contains the same engine.

Sign in

chief login

This opens your browser, you sign in to Chief, and the credential lands in ~/.chief/config.json. There is no token to paste and no config file to hand-edit — chief login is the only way to get a credential.

Under the hood it is the standard native-app flow (RFC 8252): the CLI binds an ephemeral port on your loopback interface, sends the browser to Chief with a PKCE challenge, and takes a one-time code back on loopback. The code never leaves your machine, because a loopback address is not routable off it.

The access token is short-lived and the CLI renews it for you, so day to day you never see an expiry. You will be asked to sign in again if you run chief logout, if the session is revoked, if you do not use the CLI for 30 days, or after 90 days regardless — that last one is an absolute ceiling on a session and no amount of renewal extends it.

Check it worked:

chief status

That reports reachability, whose memory this is, and what the memory actually covers per source — which is what makes an empty result interpretable.

Add Chief to a coding agent

The companion skill teaches Codex and Claude Code to use this CLI only when a task calls for Chief. It uses the same login rather than creating a second client or credential.

Install the bundled skill for Codex and Claude Code:

chief skill --install

This uses the published CLI and needs no source checkout or GitHub access. Start a new agent session after installation. Use --target codex or --target claude-code to install for just one agent. See Chief for Codex and Claude Code for updates, or follow the beta setup check to verify the complete path.

Sign out

chief logout

Revokes the session on the server first, then clears the local credential. A local file deletion that leaves a live session behind is not a logout.

Pointing at a different Chief

chief login --origin https://runchief.ai
chief config --core-url ... --integrations-url ...   # for local development

CHIEF_CORE_URL, CHIEF_INTEGRATIONS_URL and CHIEF_TOKEN override the config for a single invocation. CHIEF_TOKEN is for harnesses that already hold a credential; it is never persisted and never renewed.