Skip to content
APXAPX

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.

You can also use the install command from the home page: on a new computer with a graphical session it installs and opens the app for your operating system and processor. The app asks Server / Client before starting a core; this path does not register a background service. --desktop forces this mode; --server installs the server directly. Existing server installations retain their mode when updated.

Already using APX on localhost without the app? The panel offers Install and open. One click downloads with progress, verifies the file, installs the app and opens it with the same data, port and settings. Setup is not repeated. Use Minimize to keep working while progress continues. Cancel stops a running download and lets you retry. Once installation begins, the operating system finishes it; a failure expands the notice again. Closing the offer is remembered across reloads, with an install action above your account. After installation that action becomes Open desktop. The offer appears only in desktop browsers over a direct local connection with an available graphical session. Installation runs on the computer hosting APX; a transparent SSH forward also looks local.

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.

  1. 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):

    SystemFile
    macOS, Apple siliconAPX-<version>-mac-arm64.dmg
    macOS, IntelAPX-<version>-mac-x64.dmg
    WindowsAPX-<version>-win-x64.exe
    LinuxAPX-<version>-linux-x64.AppImage (or -arm64)

  2. Install it and open it. The 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).

  3. 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.

  4. With a local core, the setup wizard opens next. Follow it in First steps.

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

Where your data lives

Section titled “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

Section titled “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.

The first time APX starts on a newer version, your super-agent opens a new chat with what changed, and a See what’s new pill in the top bar opens it. Those notes travel with the build, so reading them costs no tokens and works offline; only asking about them in that chat runs a turn. The notes are commit sentences, so that chat is in English. A new install starts quiet, and APX_WHATS_NEW=off turns the chat off.

When a release brings something your super-agent can now do for you (say, update your widgets), it tells you once, in its own words and your language, on your preferred channel, with a button for each thing it offers. Only that message calls a model, and only when something applies to you; a new install is told nothing. APX_NEWS=off turns it off, and apx news lists what there is.

Uninstall

Section titled “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.

You can also use the install command from the home page: on a new computer with a graphical session it installs and opens the app for your operating system and processor. The app asks Server / Client before starting a core; this path does not register a background service. --desktop forces this mode; --server installs the server directly. Existing server installations retain their mode when updated.

Already using APX on localhost without the app? The panel offers Install and open. One click downloads with progress, verifies the file, installs the app and opens it with the same data, port and settings. Setup is not repeated. Use Minimize to keep working while progress continues. Cancel stops a running download and lets you retry. Once installation begins, the operating system finishes it; a failure expands the notice again. Closing the offer is remembered across reloads, with an install action above your account. After installation that action becomes Open desktop. The offer appears only in desktop browsers over a direct local connection with an available graphical session. Installation runs on the computer hosting APX; a transparent SSH forward also looks local.

  • 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.

Living beside APX v1

Section titled “Living beside APX v1”