If you are setting up for the first time, start with Getting Started. For onboarding details, see Onboarding (CLI).

TL;DR

Pick a setup workflow based on how often you want updates and whether you want to run the Gateway yourself:

Prereqs (from source)

Use the pnpm version pinned in package.json. The workspace applies a seven-day publication cooldown to npm dependencies, with trusted @openai/codex and @openai/codex-* packages exempt. The standalone pnpm toolchain is managed separately.

For npm tooling that reads the project's .npmrc, use npm 11.19 or newer for install and npm pack cooldowns and Codex exclusions. Node runtime support does not imply support for its bundled npm as a source resolver. Published/global installs do not inherit the repository's .npmrc. Source installs continue to use pnpm.

pnpm owns root and plugin-local dependencies, including workspace links and versions that differ between packages. Postinstall and build preparation preserve those trees. If an older checkout pruned plugin-local dependencies, run pnpm install --frozen-lockfile after updating to restore them before testing.

Tailoring strategy (so updates do not hurt)

If you want "100% tailored to me" and easy updates, keep your customization in:

Bootstrap the config/workspace folders once, without running the full onboarding wizard:

apus setup --baseline

No global install yet? Run it from this repo instead:

pnpm apus setup --baseline

(Bare apus setup, without --baseline, opens an interactive Apus chat on a configured system and falls through to guided onboarding on a fresh one. See Setup CLI for the full routing order.)

Run the Gateway from this repo

After pnpm build, you can run the packaged CLI directly:

node apus.mjs gateway --port 18789 --verbose

Stable workflow (macOS app first)

  1. Install + launch Apus.app (menu bar).
  2. Complete the onboarding/permissions checklist (TCC prompts).
  3. Ensure Gateway is Local and running (the app manages it).
  4. Link surfaces (example: WhatsApp):
apus channels login
  1. Sanity check:
apus health

If onboarding is not available in your build:

Bleeding edge workflow (Gateway in a terminal)

Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.

0) (Optional) Run the macOS app from source too

If you also want the macOS app on the bleeding edge:

./scripts/restart-mac.sh

1) Start the dev Gateway

pnpm install
# First run only (or after resetting local Apus config/workspace)
pnpm apus setup
pnpm gateway:watch

What gateway:watch does:

TypeScript rebuilds triggered by pnpm apus ... or pnpm gateway:watch preserve existing dist/control-ui assets. When the Gateway starts, it rebuilds missing, incomplete, or stale bundled UI assets before serving them. UI builds replace dist/control-ui only after the complete bundle passes validation, so a failed build leaves the previous bundle in place. If a build is killed while swapping in its output, the next build restores the previous bundle first. Headless commands do not rebuild the UI. Run pnpm ui:build after ui/ changes, or use pnpm ui:dev while developing the Control UI.

2) Point the macOS app at your running Gateway

In Apus.app:

3) Verify

apus health

Common footguns

Credential storage map

Use this when debugging auth or deciding what to back up:

Updating (without wrecking your setup)

Linux (systemd user service)

Linux installs use a systemd user service. By default, systemd stops user services on logout/idle, which kills the Gateway. Onboarding attempts to enable lingering for you (may prompt for sudo). If it's still off, run:

sudo loginctl enable-linger $USER

For always-on or multi-user servers, consider a system service instead of a user service (no lingering needed). See Gateway runbook for the systemd notes.

Related docs