Magick Orb Docker: the headless Orb for any server

The Aeon Magick Orb is a Raspberry Pi appliance. The Pi plugs into another computer, poses as a USB keyboard and mouse, watches the screen through a video capture path, and lets an agent operate that machine as a person at the desk would. Two parts of the same console need none of that hardware: Intergalactic Model Share, which hosts, pulls and pushes models between machines over IPFS, the content-addressed peer-to-peer file network, and the Agent Dashboard, which watches the lab's gateways and deploys a model with one click. Both are useful on machines that will never have a Pi attached: an x86 server, a Mac on Apple Silicon, a DGX Spark.

Magick Orb Docker is the Orb console without the Pi hardware, for exactly those machines. The Pi-only surface belongs to the Pi appliance. The Docker image, published as ghcr.io/aeon-7/orb-server, carries the rest, and one image built for linux/amd64 and linux/arm64 runs it on x86, on Apple Silicon and on the NVIDIA DGX Spark. The repository holds a README, a docker-compose.yml, a license and a .gitignore, because the point is that you pull an image rather than build one.

What the container keeps, and what stays on the Pi

The headless Orb is the Orb console without Raspberry Pi hardware. You get IPFS and Intergalactic Model Share, so the machine can host models, share them, pull them and push them to connected systems. You get the Agent Dashboard: DGX and gateway views, the persona pantheon, container orchestration, one-click model deploy and token telemetry. You get concurrent SSH terminal panes across your fleet, tokens, an audit trail, a REST API and MCP. MCP is the Model Context Protocol, the open standard that lets an agent discover and call tools, so any agent that speaks it drives the Orb with no SDK to install. Dashboard, terminals and model push reach other machines over outbound SSH, which is why the container asks for no extra host privileges.

What you do not get is anything that needs a physical port: no USB-HID, the device class the Pi uses to pose as a keyboard and mouse, no HDMI capture, and no GPIO, the Pi's general-purpose pins. WiFi, firewall, VPN, Tor and DNSCrypt stay on the Pi as well; they need a Raspberry Pi or a privileged host, and a plain container is neither. If keyboard and mouse injection or screen capture is what you came for, the Pi appliance in the Pi appliance article is the right tool.

The quick start

You need Docker Engine 24 or newer. Compose v2 is optional, and there is no clone and no build. One command starts the Orb with both volumes and all four port mappings:

Code, shelldocker run -d --name aeon-orb --restart unless-stopped \
  -p 8443:443 -p 8080:8080 \
  -p 4001:4001 -p 4001:4001/udp \
  -v aeon-etc:/etc/aeon \
  -v aeon-data:/var/lib/aeon \
  ghcr.io/aeon-7/orb-server:latest

Then open https://localhost:8443/ in a browser. The certificate is self-signed, so the warning is expected; accept it. The setup wizard asks for an admin password, and after that you land on the Agent Dashboard. IPFS and Model Share come up with the container, so there is nothing else to start.

Two habits save trouble later. There are no GitHub releases to browse yet; versions live in the image tags, so pin one, :v118 for example, rather than letting :latest surprise you with a new pull. If you prefer Compose, the repository's docker-compose.yml runs the same image, sets restart: unless-stopped, and maps host.docker.internal to the host gateway through extra_hosts:

Code, shelldocker compose up -d

Ports, volumes and the factory reset

Four port mappings leave the container, and each has one job.

State lives in two named volumes. aeon-etc, mounted at /etc/aeon, holds the admin credentials, the TLS certificate and the API tokens. aeon-data, mounted at /var/lib/aeon, holds the IPFS repository and the model library, which is where the gigabytes go. Removing the container leaves both volumes in place, so an upgrade is a stop, a remove and a fresh run against the same volume names:

Code, shelldocker stop aeon-orb
docker rm aeon-orb

Code, shelldocker volume rm aeon-etc aeon-data

How Orbs find each other on port 4001

This is the part I most want to explain, because it is where a headless Orb stops behaving like an ordinary web app in a container. Model Share has no central server, no account and no fleet token. Orbs find each other through the public Amino DHT, the distributed hash table of the IPFS network, a shared index of which peers hold a given piece of content. Every Orb pins the same well-known rendezvous CID, a content identifier that exists only to be looked up, so an Orb that asks the DHT who holds that CID gets back the list of other Orbs. You never need to know anyone's LAN address, and nobody needs to know yours.

Finding a peer and reaching it are different problems, and port 4001 is about the second. Publishing 4001 on tcp and udp lets other Orbs, a Pi across the WAN or another container, dial your node directly or hole-punch to it, opening a path through both sides' NAT at once, which is what makes Model Share catalogs and downloads work in both directions. If 4001 is firewalled, catalogs may still arrive through a circuit relay, where a third node forwards the traffic, but a multi-gigabyte model fetch usually needs a direct path: the published port, UPnP on the router, IPv6 or a successful hole punch.

The lesson that goes with this is the advertise address. Unless you say otherwise, a node inside Docker tells the swarm it lives at Docker's internal 172.x bridge address, which exists only inside your host, so peers dial a door that is not there. The fix is one environment variable, -e AEON_IPFS_ANNOUNCE=<this-machine-ipv4>, which makes the node advertise the host's IPv4 so that peers reach the 4001 you actually published. On any machine that should serve models beyond its own LAN, I treat it as part of the run command.

Reaching the fleet, and where the Orb fits

Plain LAN and SSH addresses need no setup. If your machines live behind 100.x Tailscale names, the container has to join the tailnet, and two arrangements work: a Tailscale sidecar with network_mode: service:tailscale, or Tailscale on the host plus host networking for the Orb.

The headless Orb belongs wherever a machine already holds models worth sharing. A DGX Spark is a natural host, since the arm64 image is built for Apple Silicon and the Spark alike; the AEON vLLM Ultimate build and DeepSeek V4 on two DGX Sparks describe that side of the fleet. For the persona pantheon on the dashboard, see also Create agentic personas, and everything I publish is listed in the Aeon Forge catalog.

Sources

• Repository: AEON-7/orb-server
• Container image: ghcr.io/aeon-7/orb-server
• Pi appliance: AEON-7/aeon-magick-ai-computer-control