Recommended default (most users)

Use a macOS VM only when you specifically need macOS-only capabilities such as iMessage, or want strict isolation from your daily Mac.

macOS VM options

Local VM on your Apple Silicon Mac (Lume)

Run Apus in a sandboxed macOS VM on your existing Apple Silicon Mac using Lume. This gives you:

Hosted Mac providers (cloud)

If you want macOS in the cloud, hosted Mac providers work too:

Once you have SSH access to a macOS VM, continue at Install Apus below.

Quick path (Lume, experienced users)

  1. Install Lume.
  2. lume create apus --os macos --ipsw latest
  3. Complete Setup Assistant, enable Remote Login (SSH).
  4. lume run apus --no-display
  5. SSH in, install Apus, configure channels.
  6. Done.

What you need (Lume)

1) Install Lume

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"

If ~/.local/bin is not in your PATH:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc

Verify:

lume --version

Docs: Lume Installation

2) Create the macOS VM

lume create apus --os macos --ipsw latest

This downloads macOS and creates the VM. A VNC window opens automatically.

The download can take a while depending on your connection.

3) Complete Setup Assistant

In the VNC window:

  1. Select language and region.
  2. Skip Apple ID (or sign in if you want iMessage later).
  3. Create a user account (remember the username and password).
  4. Skip all optional features.

After setup completes:

  1. Enable SSH: System Settings -> General -> Sharing, enable "Remote Login".
  2. For headless VM use, enable auto-login: System Settings -> Users & Groups, select "Automatically log in as:", and choose the VM user.

4) Get the VM IP address

lume get apus

Look for the IP address (usually 192.168.64.x).

5) SSH into the VM

ssh youruser@192.168.64.X

Replace youruser with the account you created, and the IP with your VM's IP.

6) Install Apus

A fresh macOS VM has no Node.js or npm. Inside the VM, run the installer script. It installs a supported Node runtime when needed, installs Apus, and starts onboarding:

curl -fsSL https://ami-docs.dev.apuscorp.com/install.sh | bash

Follow the onboarding prompts to set up your model provider (Anthropic, OpenAI, etc.).

Quick start keeps the Gateway in the foreground of this terminal, but the VM will later run headless, so the Gateway needs to run as a background service. Press Ctrl+C to stop the foreground Gateway, then install the service and verify that it is running:

apus gateway install
apus gateway status

If the VM already has Node 24.22.1+ or 26.12.1+, you can install the package directly instead. Use the following command on npm 12 or npm 11.16+. On npm 11.15 and earlier, omit --allow-scripts=apus.

npm install -g apus@latest --allow-scripts=apus
apus onboard --install-daemon

7) Configure channels

Keep the Telegram token in the Gateway environment rather than copying it into apus.json. Add TELEGRAM_BOT_TOKEN=<bot-token> to ~/.apus/.env, then load it in the current shell and add the channel:

export TELEGRAM_BOT_TOKEN="<bot-token>"
apus channels add --channel telegram --use-env

The managed Gateway reads the same state-directory .env after restart. For WhatsApp, configure your allowlist and then scan the login QR code:

apus config set channels.whatsapp.dmPolicy allowlist
apus config set channels.whatsapp.allowFrom '["+15551234567"]' --strict-json
apus channels login --channel whatsapp

8) Run the VM headlessly

Stop the VM and restart without display:

lume stop apus
lume run apus --no-display

The VM runs in the background; Apus's daemon keeps the gateway running. To check status:

ssh youruser@192.168.64.X "apus status"

Bonus: iMessage integration

This is the killer feature of running on macOS. Use iMessage with imsg to add Messages to Apus.

Inside the VM:

  1. Sign in to Messages.
  2. Install imsg.
  3. Grant Full Disk Access and Automation permission for the process running Apus/imsg.
  4. Verify RPC support with imsg rpc --help.

Add to your Apus config:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
    },
  },
}

Restart the gateway. Your agent can now send and receive iMessages. Full setup details: iMessage channel.

Save a golden image

Before customizing further, snapshot your clean state:

lume stop apus
lume clone apus apus-golden

Reset anytime:

lume stop apus && lume delete apus
lume clone apus-golden apus
lume run apus --no-display

Running 24/7

Keep the VM running by:

For true always-on, consider a dedicated Mac mini or a small VPS. See VPS hosting.

Troubleshooting

Problem Solution
Cannot SSH into VM Check "Remote Login" is enabled in the VM's System Settings
VM IP not showing Wait for VM to fully boot, run lume get apus again
Lume command not found Add ~/.local/bin to your PATH
WhatsApp QR not scanning Ensure you are logged into the VM (not host) when running apus channels login

Related docs