Setup guide
Private Alpha
Three paths lead to the same place: a computer that Control Center manages. Install AnxOS on this Windows PC, add another desktop computer, or pair a headless Debian or Ubuntu server. Every path ends with a one-time pairing code from Add Computer, and no path needs manual tokens or file editing.
Install AnxOS Control Center, complete onboarding, and let the app set up the Local Agent on this computer. The Windows installation guide has the full detail.
Install AnxOS on that computer, open Agent Control → Connect this computer, turn on Another computer will connect to this one, and generate a pairing code. Then paste the full code under Add Computer in your main Control Center.
The desktop walkthrough below follows this flow step by step.
Install the official Agent package on a server with no desktop, open the TUI, and pair it with a one-time code.
The command walkthrough below covers the whole install.
Path 1 · Desktop
Ten steps from the download to a game night, on Windows or on a Linux desktop. On Windows the Windows installation guide follows the same flow with more platform detail.
Open the download page and choose the package for this computer: the signed Windows installer, Windows portable, Linux .deb, or Linux AppImage. The download page only lists files from the official GitHub Release.
Run the installer and follow its screens. On Windows, Approve administrator access if it is requested and launch AnxOS Control Center from the Start menu or desktop shortcut. On Linux, install the .deb with your software installer or mark the AppImage as executable and open it.
Sign in with your AnxOS account or create one, then complete the first-run Local Owner setup for this installation. Local Owner credentials unlock privileged actions on this node: keep them private and separate from game-server logins.
If this is the computer you installed on, open Agent Control and install or start the Local Agent, approving the service installation if Windows asks. If Control Center is connecting to another desktop, on that computer turn on Another computer will connect to this one and choose Generate Pairing Code, then paste the full code under Add Computer here. Pairing is one-time; the connection is automatic after that.
Open Prepare Node and scan for the tools your server needs: Java, Docker, SteamCMD, .NET, FFmpeg, and tunnel providers among others. Use the graphical Install or Repair action for anything missing, then scan again.
Open Marketplace, pick a template such as a Minecraft server or modpack, and choose the node, memory limit, server port, and install location. Review the summary and start the installation. Minecraft servers ask you to read and accept the EULA before they will run.
Open Instances, review the configuration, and start the server. Watch Logs and Console until it reports ready, and use the AnxOS Stop and Restart controls so shutdowns stay safe. Files and Backups live on the same pages.
Open Public Access and choose an access method: Playit for a public game address without router changes, Tailscale for a private tailnet, Cloudflare Tunnel for supported HTTP services, or manual port forwarding if you understand your router. Expose the game port only, never management ports.
Copy the address from the instance or the active Public Access card. In Minecraft use Multiplayer → Add Server; in other games open the server browser or direct-connect screen. localhost works only on this computer, the LAN address works on the same network, and the public address works anywhere.
If something stalls, the troubleshooting section below covers Agent Offline, Agent Unauthorized, missing dependencies, port conflicts, EULA and Java problems, crashed starts, and public addresses — including the headless-specific cases.
Path 2 · Headless
For a Debian 11+ or Ubuntu 22.04+ x64 server with no desktop. The Agent is a systemd system service, and the whole setup is one package install plus a one-time pairing code pasted into Add Computer.
The official AnxOS-Agent-<version>.deb package, installed as anxos-agent.service. Requires glibc 2.28 or newer and systemd.
Same package and service unit. The Agent listens on loopback (127.0.0.1) by default; connecting another computer is an explicit opt-in.
Other distributions and architectures are not supported. Do not force-install a package built for a different architecture.
On the release page, download the Agent package and its checksum file into one folder: AnxOS-Agent-<version>.deb and AnxOS-Agent-<version>.deb.sha256.
sha256sum -c AnxOS-Agent-<version>.deb.sha256
Expected result: the package file name followed by OK. Not code-signed — the published SHA-256 checksum is the integrity check. If the check fails, delete the file and download it again; never install a package whose checksum does not match.
Run this in the folder with the downloaded package. apt resolves dependencies from your configured repositories and installs the anxos-agent.service unit.
sudo apt install ./AnxOS-Agent-<version>.deb
If apt cannot run, use the dpkg fallback:
sudo dpkg -i ./AnxOS-Agent-<version>.deb || sudo apt-get -f install
Confirm the installed version:
anxos-agent --version
Your sudo password is entered by you and is never captured or recorded.
The package installs a systemd system unit named anxos-agent.service. Check it with either view:
sudo systemctl status anxos-agent.service --no-pager
sudo anxos-agent service status
sudo is needed for service control and the full status. Pairing over loopback works without sudo.
Run anxos-agent with no arguments to open the terminal interface. It shows the same state the desktop surfaces would: service, identity, pairing, system metrics, updates, and logs. The frame below is real output from a fresh install.
anxos-agent
Choose Pair in the TUI, or run:
anxos-agent pair
Copy the full pairing code — the long value printed under Pairing code (paste into Add Computer): — not only the short ANX-XXXX-XXXX-XXXX reference code, which identifies the session on screen. Codes are one-time and valid for 10 minutes; the code may wrap across lines because whitespace is ignored when you paste it.
Treat a pairing code as temporary sensitive material: do not record it, screenshot it, or paste it into a bug report.
If Control Center runs on this same server, skip this step. If another computer will connect, open the TUI with sudo anxos-agent, choose Pair, and press n to allow network access for your network. You can instead pin AGENT_HOST=<LAN-or-tailnet-IP> in /etc/anxos-agent/agent.env and restart the service.
Prefer a concrete LAN or tailnet address over 0.0.0.0: a wildcard bind exposes the Agent on every interface. While a reachable Agent is not yet paired, anyone who can reach it could claim it — pair promptly.
Open Add Computer and choose Headless server. Paste the full pairing code into Pair with Code — the recommended path — and confirm the Agent identity the app shows before accepting. Wait for the node to come online.
Advanced Manual Setup (URL and token) exists for development or recovery only. Normal setup never needs manual tokens or JSON editing.
anxos-agent status reports reachability, service state, and enrollment on the server side. It always exits 0 by contract, so read the printed fields instead of the exit code.
anxos-agent status
The update check is read-only and never downloads or installs anything. update-available prints the download, checksum, and install command; current means nothing newer is published; unknown means the release source could not be read.
anxos-agent update --check
Install an offered update with its printed apt command. Upgrading the package restarts the service so the new version takes over; servers, settings, and backups stay in /var/lib/anxos-agent.
unpair revokes this node’s enrollment and clears the stored credential while keeping servers, backups, and configuration. Re-pair with a fresh code to restore enrollment.
sudo anxos-agent unpair
anxos-agent pair
Removing the package keeps all data:
sudo apt remove anxos-agent
Servers, settings, and backups remain in /var/lib/anxos-agent. Delete that folder only when you are sure the data is no longer needed.
Agent TUI · real output
What a fresh headless install looks like in the terminal:
Abridged from a real Agent session on a fresh install — the Logs section is omitted, and the frame scrolls sideways on narrow screens.
Quick fixes
The same fixes apply to every path; the headless-only cases are listed last. Use the built-in diagnostics export when you ask for help.
Open Agent Control, start the Agent, select the correct node, and retry. On a headless server, check the service first:
sudo systemctl status anxos-agent.service --no-pager
Remove the failed pairing and pair again with a fresh one-time code — from Agent Control on a desktop, or anxos-agent pair on a server. Permanent credentials are created by pairing and are never displayed.
Run Prepare Node, use Install or Repair for the missing item, then scan again. On a headless server, automatic dependency installs may need passwordless sudo for the Agent service account; without it the app shows the exact package to install with your normal sudo session.
Stop the other service or choose a different unused port in the instance configuration. On a server, this shows which process holds a port:
ss -ltnp
Read the Minecraft EULA; if you agree, accept it in the instance’s EULA or configuration view, then start the server again.
Check the template’s Java requirement, install that runtime in Prepare Node, and select it for the server. A Minecraft version that needs a newer Java is refused before install with the required and available versions shown, instead of failing later.
Open Logs and read the final error. Check memory, dependencies, configuration, and free disk space.
Confirm the provider is installed and connected, and that it supports this service’s protocol, then refresh Public Access. Cloudflare Tunnel covers HTTP and HTTPS services, not raw game ports.
Open Diagnostics to export a sanitized bundle, and use the instance Logs and Console pages for server output. On a headless server, anxos-agent diagnostics and /var/log/anxos-agent do the same. Never paste unredacted logs, pairing codes, tokens, or keys.
Check both views, then start the service:
sudo anxos-agent service start
anxos-agent logs
If it stops again, check the log directory /var/log/anxos-agent for the first error.
Installing the package, service control, the full status, unpair, and upgrades use sudo. Pairing itself works without sudo over loopback.
Delete the downloaded package and fetch it again from the official release page. Never install a package whose checksum does not match.
Pairing codes are one-time and valid for 10 minutes — run anxos-agent pair again for a fresh one. Add Computer accepts the full long code under Pairing code (paste into Add Computer):, not the short ANX-XXXX-XXXX-XXXX reference alone.
anxos-agent pair
Confirm the service is running and network access was allowed, verify from the server itself, then check the firewall or cloud security group:
curl -fsS http://<host>:<agent-port>/api/v1/health
Download AnxOS, or open the Windows installation guide if this PC is your first node.