Install Apus declaratively with nix-apus, the first-party, batteries-included Home Manager module.

What you get

• Gateway + macOS app + tools (whisper, spotify, cameras), all pinned
• Launchd service that survives reboots
• Plugin system with declarative config
• Instant rollback: home-manager switch --rollback

Quick start

If Nix is not already installed, follow the [Determinate Nix installer](https://github.com/DeterminateSystems/nix-installer) instructions.

Use the agent-first template from the nix-apus repo:
```bash
mkdir -p ~/code/apus-local
git clone https://github.com/openclaw/nix-openclaw.git /tmp/nix-apus
cp /tmp/nix-apus/templates/agent-first/flake.nix ~/code/apus-local/flake.nix
```

Set up your messaging bot token and model provider API key. Plain files at `~/.secrets/` work fine.

```bash
home-manager switch
```

Confirm the launchd service is running and your bot responds to messages.

See the nix-apus README for full module options and examples.

Nix-mode runtime behavior

When APUS_NIX_MODE=1 is set (automatic with nix-apus), Apus enters a deterministic mode for Nix-managed installs. Other Nix packages can set the same mode; nix-apus is the first-party reference.

For externally managed config without Nix, use APUS_CONFIG_READONLY=1. It applies the same immutable-config enforcement with generic messaging, without enabling Nix-specific behavior. Existing APUS_NIX_MODE=1 installs need no changes.

You can also set it manually:

export APUS_NIX_MODE=1

On macOS, the GUI app does not inherit shell environment variables. Enable Nix mode via defaults instead:

defaults write ai.apus.mac apus.nixMode -bool true

What changes in Nix mode

• Auto-install and self-mutation flows are disabled.
• apus.json is treated as immutable. Startup-derived defaults stay runtime-only, and config writers (setup, onboarding, mutating apus update, plugin install/update/uninstall/enable, doctor --fix, doctor --generate-gateway-token, apus config set) refuse to edit the file.
• Edit the Nix source instead. For nix-apus, use the agent-first Quick Start and set config under programs.apus.config or instances.<name>.config.
• Missing dependencies surface Nix-specific remediation messages.
• The UI shows a read-only Nix mode banner.

Config and state paths

Apus reads JSON5 config from APUS_CONFIG_PATH and stores mutable data in APUS_STATE_DIR. Under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store.

Service PATH discovery

The launchd/systemd gateway service auto-discovers Nix-profile binaries so plugins and tools that shell out to nix-installed executables work without manual PATH setup:

• When NIX_PROFILES is set, every entry is added to the service PATH in right-to-left precedence (matches Nix shell precedence: rightmost wins).
• When NIX_PROFILES is unset, ~/.nix-profile/bin is added as a fallback.

This applies to both macOS launchd and Linux systemd service environments.

Related

Source-of-truth Home Manager module and full setup guide.

Non-Nix CLI setup walkthrough.

Containerized setup as a non-Nix alternative.

Updating Home Manager-managed installs alongside the package.