How Orca runs on macOS, Windows and Linux

Orca has the same three parts everywhere: the desktop app, the Orca daemon, and a Docker (or Podman) engine. What differs per platform is where that engine runs. Read this page when you want to know what Orca set up on your machine, change the VM's resources, or find a config file.

#The daemon

The desktop app starts orca-daemon in the background and stops it when you quit with Quit Orca. The daemon serves a REST API on http://127.0.0.1:9477/api/v1/, only on the loopback interface. The app, the orca CLI and AI agents all go through it.

• Every request needs the API token from config.json as Authorization: Bearer <token>, except GET /api/v1/health.
• The daemon creates the token on its first start.
• If the daemon exits unexpectedly, the app restarts it, up to 3 times in 10 minutes.
• If a daemon of a different version is already running when the app starts (for example after an update), the app replaces it with its own.

Check that it's up and which version it runs:

curl -s http://127.0.0.1:9477/api/v1/health

{"status":"ok","version":"0.50.0"}

#macOS: a Lima VM

Containers need a Linux kernel, so on macOS Docker runs in a VM named orca, managed by Lima. Orca creates it during first-start setup (see Install).

#Ports

Any container port published on 0.0.0.0 in the VM is forwarded to 127.0.0.1 on your Mac, for all TCP ports. docker run -p 8080:80 nginx is reachable at http://localhost:8080, as with Docker Desktop.

#Bind mounts and file ownership

The Ubuntu 26.04 kernel supports idmapped mounts natively, which is what lets chmod, chown and non-root containers work on bind-mounted folders from your Mac. VMs created by older Orca versions run Ubuntu 24.04, where Orca installs the newer HWE kernel for the same reason.

#Why vsock

Lima normally reaches the VM over a virtual network. Behind a mesh VPN (NetBird, Tailscale, WireGuard), that path can break and the VM never becomes reachable. The current VM carries SSH and the Docker socket over vsock, a channel between the hypervisor and the guest that a VPN can't intercept, and gives the guest a fixed network address instead of asking for one over DHCP.

If System Health shows Docker VM Base, your VM was built on the older Ubuntu 24.04 base without vsock. It keeps working without a VPN. To move to the current base, use Recreate VM on System Health. Recreating deletes the VM, so containers, images and volumes in it are lost and you re-pull or rebuild them.

#Auto-reconciliation

Every time the daemon starts, it reads ~/.lima/orca/lima.yaml and adds anything an older Orca version didn't set: the port forwarding rule, the /Volumes and /private mounts, vsock SSH (or the HWE kernel on older VMs), and a fix for Apple M4 and M5 chips. If something is missing, Orca stops the VM, applies it with limactl edit and starts it again. Upgrading Orca doesn't require recreating the VM.

On a running VM the daemon also makes sure IPv4 forwarding is on, so docker compose up networking works after a reboot.

If the VM is stopped when the daemon starts, the daemon starts it. If it doesn't come up, the daemon force-stops it, clears Lima's stale lock and socket files and tries again.

#VM resources

Change CPUs, memory and disk in Settings > General > Virtual machine, then click Apply changes. This restarts the VM and stops running containers. Memory must be at least 2 GB and no more than your Mac has; disk must be at least 10 GB.

#Windows: WSL2

On Windows, Docker runs in your default WSL2 distro.

• First-start setup installs Docker in that distro and adds a systemd override so dockerd listens on its normal socket and on tcp://127.0.0.1:2375.
• The daemon connects to Docker Desktop's named pipe first if Docker Desktop is running, and otherwise to localhost:2375.
• If neither answers when the daemon starts, it starts Docker in WSL and retries for about 15 seconds.

The TCP listener is bound to 127.0.0.1 inside WSL. Uninstalling Orca removes the override.

#WSL2 resources

WSL2's limits apply to all your distros, not only Docker. Set them in Settings > General > WSL2 resources: Memory, Processors and Swap (for example 8GB, 4, 0). Orca writes them to the [wsl2] section of %USERPROFILE%\.wslconfig and keeps your other settings in that file.

Changes take effect after WSL restarts:

wsl --shutdown

#Linux: native

On Linux there's no VM. Orca talks to the Docker or Podman socket on your machine, and container ports are on your host directly.

The daemon uses the first socket that responds, in this order:

1. DOCKER_HOST, when it's a unix:// path
2. The active Docker context
3. /var/run/docker.sock
4. Rootless Podman at /run/user/<uid>/podman/podman.sock, then /run/podman/podman.sock

On macOS the same search also finds Docker Desktop, Colima and other Lima VMs, which is how Orca can work with an engine you already have.

#Where files live

The daemon log is written when the desktop app starts the daemon. The log from the previous run is kept next to it as daemon.prev.log, so after a crash you can still read why. Settings > About > Paths shows these paths with a copy button.

On a Linux server where the daemon was installed as a service, the config is /etc/orca/config.json and logs go to the journal (journalctl -u orca-daemon). If /etc/orca/config.json exists, the daemon uses it instead of the per-user file.

Read your token, for example on Linux:

python3 -c "import json; print(json.load(open('$HOME/.config/orca/config.json'))['api_token'])"

#Related

• Install Orca
• Troubleshooting
• Remote hosts