Install

APX is one background process, the core, plus the apps that talk to it. Pick how you want to run it: the desktop app brings its own core, a server install runs the core with no screen, and a checkout runs the code as it is.

The desktop app is the easiest start. It carries its own core, the panel and the built-in browser your agents drive, and it lives in your menu bar or tray.

Download the installer for your system from the APX v2 releases. Pick the newest v2.x.y (v1’s releases live in the same list):

System File
macOS, Apple silicon APX-<version>-mac-arm64.dmg
macOS, Intel APX-<version>-mac-x64.dmg
Windows APX-<version>-win-x64.exe
Linux APX-<version>-linux-x64.AppImage (or -arm64)
Install it and open it. The beta apps are not signed yet, so your system warns you the first time (see below).
- macOS: open the .dmg and drag APX to Applications. The first time, right-click APX in Applications and choose Open, then Open again. If macOS only offers to move it to the trash, open System Settings › Privacy & Security, scroll down to the message about APX and click Open anyway.
- Windows: run the .exe. When SmartScreen says it protected your PC, click More info, then Run anyway.
- Linux: make the AppImage runnable and open it: chmod +x APX-*.AppImage, then ./APX-<version>-linux-x64.AppImage (or double-click it).
On first run, APX asks Where does your APX run?
- Server: APX runs on this computer. The core is installed and started here. You then choose where you’ll use it from: Only from this computer (the safest), Also from my local network, or Tailscale (your devices from anywhere, over https; needs Tailscale installed).
- Client: APX already runs on another machine and this app only connects to it, either by Address (its Tailscale URL, for example) or over SSH as user@server. SSH uses your own ssh and keys: the core stays on the server and no port is opened. A remote APX asks for a pairing code, which you get on that machine in Settings › Devices or with apx pair.
With a local core, the setup wizard opens next. Follow it in First steps.

System	File
macOS, Apple silicon	`APX-<version>-mac-arm64.dmg`
macOS, Intel	`APX-<version>-mac-x64.dmg`
Windows	`APX-<version>-win-x64.exe`
Linux	`APX-<version>-linux-x64.AppImage` (or `-arm64`)

You can switch later from the APX menu › Change connection.

macOS needs an Apple Developer ID and Windows an Authenticode certificate for the warning to go away; the beta has neither yet. The installers are the ones built by the release workflow, each with a .sha256 beside it to check the download. If macOS says “APX” is damaged and can’t be opened, that is the download’s quarantine mark on an unsigned app, not a broken file. Clear it and open APX again:

xattr -dr com.apple.quarantine /Applications/APX.app

On a machine with no desktop, one script installs the core, the apx command and the Node that runs them. Nothing needs root and you don’t need Node installed.

❯ curl -fsSL https://agentprojectcontext.github.io/apx/v2/install.sh | bash

❯ irm https://agentprojectcontext.github.io/apx/v2/install.ps1 | iex

It installs on the machine where you run it. For a server, run it there over SSH, or from your computer with ssh user@server 'curl -fsSL https://agentprojectcontext.github.io/apx/v2/install.sh | bash'; the desktop app can also install it for you (APX on a server).

The script accepts a few options:

Option	What it does
`--file <bundle>`	Installs a bundle you already have instead of downloading one.
`--version <x.y.z>`	Installs that version instead of the newest.
`--feed <owner/repo>`	Looks for releases in another repository.
`--no-service`	Installs without starting the core as a service.
`--uninstall`	Removes the service and the program; your data stays (see Uninstall).

To pass options through the pipe: curl -fsSL https://agentprojectcontext.github.io/apx/v2/install.sh | bash -s -- --version 2.3.0. On Windows the parameters are -File, -Version, -Feed, -NoService and -Uninstall.

It lands in ~/.apx/v2/app (one folder per version and a current link) and starts the core as a service. Then finish the setup in one command:

❯ apx setup --headless --expose tailscale
[1] Run the core as a service
# …
[3] Expose the core (tailscale)
# …
[4] Pair a device
# a one-time code, the addresses and an apx://pair link

setup --headless installs the service, optionally imports APX v1 (--import, plus --keys, --skills, --services), optionally opens the core to your tailnet or your network (--expose tailscale or --expose lan), and prints a pairing code for your desktop app or phone.

The service is a systemd user unit on Linux, a launchd agent on macOS and a login entry on Windows. Manage it with apx service install, uninstall, status and restart. The core refuses to listen beyond this machine without a token; apx expose creates one for you. More in Run APX on a server.

scripts/docker/Dockerfile in the repository packs a release’s daemon bundle (the same one install.sh installs) into an image. Download the Linux bundle for your machine (apx-core-<version>-linux-x64.tar.gz or -arm64) from the v2 releases into a checkout of the repository, then:

docker build -f scripts/docker/Dockerfile --build-arg BUNDLE=apx-core-<version>-linux-x64.tar.gz -t apx .
docker run -d --name apx -p 7440:7440 -v apx-data:/data -e APX_TOKEN=<a long random string> apx
docker exec -it apx apx pair            # pair the desktop app or the phone with it

The core listens on every interface of the container, so it refuses to start without APX_TOKEN.
Your data is in the /data volume (APX_HOME=/data); secrets go to a file there, not a keychain.
It never updates itself (APX_UPDATES=off): build a new image from a newer bundle and run it on the same volume.
Publish the port only where you trust the network, or keep it on 127.0.0.1 and put your own TLS proxy in front.

To work on APX, or to run the newest code, use a checkout. You need Node 24.11 or later and pnpm.

pnpm install
pnpm app     # build the panel and the desktop app, start the core and open the app
pnpm dev     # only the core, on 127.0.0.1:7440, restarting when a file changes

The core runs its TypeScript directly, so there’s no build step for it. From the checkout, the terminal is node apps/terminal/src/main.ts; an alias makes it feel installed:

alias apx="node $PWD/apps/terminal/src/main.ts"
apx status

apx status shows whether the core is up, the crew, projects, MCP servers, devices and who can reach it.

Where your data lives

Everything APX keeps is in one folder, ~/.apx/v2 (set APX_HOME to move it). Your projects stay where they are; APX only adds AGENTS.md and .apc/ to them.

Directory~/.apx/v2/
- apx.db all state: agents, threads, tasks, memory, settings (SQLite)
- core.env the core’s token, host and public address, when set
- secrets.json secret values, where the system keychain is not used
- Directoryskills/ your global skills
  - …
- Directoryextensions/
  - …
- Directoryprojects/ APX’s side of each project, such as its widgets
  - …
- Directorymedia/
  - …
- Directorylogs/
  - …
- Directorybackups/
  - …
- Directoryapp/ the installed core, for server installs
  - …

On macOS, secret values go to your login Keychain; elsewhere they go to secrets.json with owner-only permissions.

Updates

APX checks for a new version every few hours and shows an Update pill in the top bar when one is out; it shows what the new version brings and lets you update when you want.

Desktop app: it updates itself. The AppImage and the Windows installer install the new version on their own; on macOS it opens the new disk image for you to drag in.
Server install: apx upgrade --check tells you if there’s a newer release, and apx upgrade installs it beside the running one and restarts. A desktop app connected to the server can update it too.
Checkout: APX follows main of the checkout it runs from; updating pulls, installs, builds and restarts.

Set APX_UPDATES=off to stop the checks.

Uninstall

Uninstalling removes the program and its service. Your data stays in ~/.apx/v2; delete that folder yourself if you want to start over. APX v1’s files in ~/.apx are never touched either way.

macOS: quit APX from its menu bar icon and drag APX from Applications to the trash.
Windows: Settings › Apps › Installed apps › APX › Uninstall.
Linux: quit APX and delete the AppImage.

If you also installed the core as a service on this computer (apx service install, or a server install), remove it with apx service uninstall or the server steps in the next tab.

Run the installer again with the uninstall flag:

curl -fsSL https://agentprojectcontext.github.io/apx/v2/install.sh | bash -s -- --uninstall

On Windows, in PowerShell, save the script and run it with -Uninstall:

irm https://agentprojectcontext.github.io/apx/v2/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall

It stops the service, removes ~/.apx/v2/app and the apx command it wrote, and leaves your data where it is. With a saved copy of the script it is bash install.sh --uninstall.

docker rm -f apx removes the container; the apx-data volume keeps your data until you docker volume rm apx-data.

apx service uninstall removes the service; the checkout is yours to delete.