Install and first run are the same on macOS as anywhere else — see the
new-user walkthrough
(pipx install panopticon-next && panopticon quickstart). This page
covers only what's macOS-specific.
Task containers reach the loopback-bound host task service via host.docker.internal. Both
OrbStack and
Docker Desktop
provide that route on macOS; bare Docker Engine does not. Install and start either supported
runtime, then confirm its daemon is up:
docker infopanopticon doctor checks this (along with tmux, git, Python, and at least one registered harness
CLI), and
panopticon quickstart runs it before creating Panopticon state.
Task containers run inside the selected runtime's Linux VM rather than on your host directly —
which is also why the container's Linux-only tooling (groupmod, useradd, gosu, … in
docker/Dockerfile and docker/entrypoint.sh) works even though your host is macOS.
- Host networking isn't required. Panopticon reaches the host through
host.docker.internal, so runtime-specific--network hostbehavior does not affect it. - Docker-in-Docker (
capabilities.docker_in_docker) uses--privileged. On Apple Silicon, if the task image islinux/amd64-only and emulation causes trouble, rebuild the image forarm64or adjust the selected runtime's x86 emulation setting. - tmux must be installed before you start Panopticon — if it's missing, session launches fail
silently.
panopticon doctorcatches this.
Contributing rather than just running it? The make targets work on macOS with the same OrbStack
or Docker Desktop + tmux requirements above — add uv (brew install uv), then make sync,
make build, make start. make stop (or panopticon stop) tears everything down. See
docs/dev.md for the full development loop (setup, checks, and CI).