ActualDocsAgent guide

Start Here

Set Up on macOS

Install Actual on Apple Silicon Macs and verify the CLI

2 min readMarkdown4 sectionsopen computers →

The public macOS client requires Apple Silicon (M1 or later) and uses Metal. Intel Macs are not supported.

Install#

  1. Sign in and open Computers.
  2. Choose Add lead computer, or select a cluster and choose Add child computer.
  3. Copy the macOS / Linux command and run it in Terminal within 10 minutes.
  4. Let installation and authorization finish, then open a fresh terminal.

Use the exact command the website provides. The generic CLI installer places files under ~/.actual/bin and may expose actual through a launcher in ~/.local/bin. App packaging can differ by release channel; use the installed command rather than assuming every release installs the same app bundle.

Verify and start#

command -v actual
actual --version
actual whoami
actual
actual status

A launcher or symlink in ~/.local/bin is a valid result from command -v actual. Confirm the version and account, then check that the computer is online in Computers. If login is incomplete, run actual login and open the exact URL it prints; a valid pending code authorizes automatically after sign-in.

Startup can leave the daemon idle with no model. Download a model, wait for installation, then run actual models load and check actual status again.

Use the Mac menu#

On builds with the menu app, Model shows the loaded model and its capability icons. API · Private Relay or API · Localhost identifies the selected API mode. See Private Relay for connection and endpoint checks.

Troubleshooting#

If actual is not found, open a new terminal or reload your shell profile. For the generic CLI installation, try:

"$HOME/.actual/bin/actual" --version

If the direct command works, inspect your PATH for stale copies before reinstalling. If the daemon is running but the computer is absent from the website, compare actual whoami with your browser account and inspect actual status --format json.

A dquote> prompt means zsh is waiting for a closing quote. Press Ctrl-C and rerun actual models load to choose a model interactively.

See Machine Installation for expired credentials and startup options, or Logs & Telemetry for failures after startup.