Instalar

APX es un proceso en segundo plano, el core, más las apps que le hablan. Elegí cómo querés correrlo: la app de escritorio trae su propio core, una instalación de servidor corre el core sin pantalla, y desde el código corrés todo tal cual está.

La app de escritorio es la forma más fácil de arrancar. Trae su propio core, el panel y el navegador que manejan tus agentes, y vive en la barra de menú o en la bandeja del sistema.

Bajate el instalador para tu sistema desde los releases de APX v2. Elegí el v2.x.y más nuevo (los releases de v1 están en la misma lista):

Sistema Archivo
macOS, Apple silicon APX-<versión>-mac-arm64.dmg
macOS, Intel APX-<versión>-mac-x64.dmg
Windows APX-<versión>-win-x64.exe
Linux APX-<versión>-linux-x64.AppImage (o -arm64)
Instalala y abrila. Las apps de la beta todavía no están firmadas, así que tu sistema te avisa la primera vez (mirá más abajo).
- macOS: abrí el .dmg y arrastrá APX a Aplicaciones. La primera vez, hacé clic derecho en APX dentro de Aplicaciones, elegí Abrir y otra vez Abrir. Si macOS solo te ofrece tirarla a la papelera, andá a Ajustes del Sistema › Privacidad y seguridad, bajá hasta el aviso sobre APX y tocá Abrir igualmente.
- Windows: corré el .exe. Cuando SmartScreen diga que protegió tu PC, hacé clic en Más información y después en Ejecutar de todas formas.
- Linux: hacé ejecutable el AppImage y abrilo: chmod +x APX-*.AppImage, después ./APX-<versión>-linux-x64.AppImage (o doble clic).
En el primer arranque, APX te pregunta ¿Dónde corre tu APX?
- Servidor: APX corre en esta computadora. El core se instala y arranca acá. Después elegís desde dónde lo vas a usar: Solo desde esta computadora (lo más seguro), También desde mi red local o Tailscale (tus dispositivos desde cualquier lado, por https; necesita Tailscale instalado).
- Cliente: APX ya corre en otra máquina y esta app solo se conecta, por Dirección (su URL de Tailscale, por ejemplo) o por SSH como usuario@servidor. SSH usa tu propio ssh y tus claves: el core se queda en el servidor y no se abre ningún puerto. Un APX remoto te pide un código de emparejamiento, que sacás en esa máquina en Config › Dispositivos o con apx pair.
Con un core local, después se abre el asistente de configuración. Seguilo en Primeros pasos.

Sistema	Archivo
macOS, Apple silicon	`APX-<versión>-mac-arm64.dmg`
macOS, Intel	`APX-<versión>-mac-x64.dmg`
Windows	`APX-<versión>-win-x64.exe`
Linux	`APX-<versión>-linux-x64.AppImage` (o `-arm64`)

Lo podés cambiar después desde el menú APX › Cambiar conexión.

Para que el aviso desaparezca, macOS necesita un Apple Developer ID y Windows un certificado Authenticode; la beta todavía no tiene ninguno. Los instaladores son los que arma el workflow de releases, cada uno con su .sha256 al lado para chequear la descarga. Si macOS dice “APX” está dañado y no puede abrirse, es la marca de cuarentena de la descarga sobre una app sin firmar, no un archivo roto. Sacala y abrí APX de nuevo:

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

En una máquina sin escritorio, un script instala el core, el comando apx y el Node que los corre. No hace falta root ni tener Node instalado.

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

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

Se instala en la máquina donde lo corrés. Para un servidor, corrélo ahí por SSH o desde tu computadora con ssh usuario@servidor 'curl -fsSL https://agentprojectcontext.github.io/apx/v2/install.sh | bash'; la app de escritorio también puede instalarlo por vos (APX en un servidor).

El script acepta algunas opciones:

Opción	Qué hace
`--file <bundle>`	Instala un bundle que ya tenés en vez de bajarlo.
`--version <x.y.z>`	Instala esa versión en vez de la más nueva.
`--feed <owner/repo>`	Busca los releases en otro repositorio.
`--no-service`	Instala sin arrancar el core como servicio.
`--uninstall`	Saca el servicio y el programa; tus datos quedan (mirá Desinstalar).

Para pasar opciones por el pipe: curl -fsSL https://agentprojectcontext.github.io/apx/v2/install.sh | bash -s -- --version 2.3.0. En Windows los parámetros son -File, -Version, -Feed, -NoService y -Uninstall.

Queda en ~/.apx/v2/app (una carpeta por versión y un link current) y arranca el core como servicio. Después terminás la configuración con un comando:

❯ apx setup --headless --expose tailscale
[1] Run the core as a service
# …
[3] Expose the core (tailscale)
# …
[4] Pair a device
# un código de un solo uso, las direcciones y un link apx://pair

setup --headless instala el servicio, opcionalmente importa APX v1 (--import, más --keys, --skills, --services), opcionalmente abre el core a tu tailnet o a tu red (--expose tailscale o --expose lan) y te muestra un código para emparejar la app de escritorio o el teléfono.

El servicio es una unidad de usuario de systemd en Linux, un agente de launchd en macOS y una entrada de inicio de sesión en Windows. Lo manejás con apx service install, uninstall, status y restart. El core no acepta escuchar más allá de esta máquina sin un token; apx expose te lo crea. Más en Correr APX en un servidor.

scripts/docker/Dockerfile del repositorio mete el bundle del daemon de un release (el mismo que instala install.sh) en una imagen. Bajate el bundle de Linux para tu máquina (apx-core-<versión>-linux-x64.tar.gz o -arm64) de los releases de v2 dentro de un checkout del repositorio, y después:

docker build -f scripts/docker/Dockerfile --build-arg BUNDLE=apx-core-<versión>-linux-x64.tar.gz -t apx .
docker run -d --name apx -p 7440:7440 -v apx-data:/data -e APX_TOKEN=<un texto largo al azar> apx
docker exec -it apx apx pair            # emparejá la app de escritorio o el teléfono

El core escucha en todas las interfaces del contenedor, así que no arranca sin APX_TOKEN.
Tus datos están en el volumen /data (APX_HOME=/data); los secretos van a un archivo ahí, no a un llavero.
Nunca se actualiza solo (APX_UPDATES=off): armá una imagen nueva con un bundle más nuevo y correla sobre el mismo volumen.
Publicá el puerto solo en una red de confianza, o dejalo en 127.0.0.1 y poné tu propio proxy TLS adelante.

Para trabajar en APX, o para correr el código más nuevo, usá un checkout. Necesitás Node 24.11 o más nuevo y pnpm.

pnpm install
pnpm app     # compila el panel y la app de escritorio, arranca el core y abre la app
pnpm dev     # solo el core, en 127.0.0.1:7440, que se reinicia cuando cambia un archivo

El core corre su TypeScript directo, así que no tiene paso de build. Desde el checkout, la terminal es node apps/terminal/src/main.ts; con un alias se siente instalada:

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

apx status te muestra si el core está arriba, el equipo, los proyectos, los servidores MCP, los dispositivos y quién puede llegar a él.

Dónde viven tus datos

Todo lo que guarda APX está en una carpeta, ~/.apx/v2 (con APX_HOME la movés). Tus proyectos se quedan donde están; APX solo les suma AGENTS.md y .apc/.

Directorio~/.apx/v2/
- apx.db todo el estado: agentes, hilos, tareas, memoria, configuración (SQLite)
- core.env el token del core, el host y la dirección pública, si los configurás
- secrets.json los valores secretos, donde no se usa el llavero del sistema
- Directorioskills/ tus skills globales
  - …
- Directorioextensions/
  - …
- Directorioprojects/ el lado de APX de cada proyecto, como sus widgets
  - …
- Directoriomedia/
  - …
- Directoriologs/
  - …
- Directoriobackups/
  - …
- Directorioapp/ el core instalado, en instalaciones de servidor
  - …

En macOS, los valores secretos van a tu llavero de sesión (Keychain); en el resto, a secrets.json con permisos solo para vos.

Actualizaciones

APX busca una versión nueva cada pocas horas y, cuando sale una, muestra una pastilla Actualización en la barra de arriba; ahí ves qué trae y actualizás cuando quieras.

App de escritorio: se actualiza sola. El AppImage y el instalador de Windows instalan la versión nueva por su cuenta; en macOS abre la imagen de disco nueva para que la arrastres.
Instalación de servidor: apx upgrade --check te dice si hay un release más nuevo, y apx upgrade lo instala al lado del que corre y reinicia. Una app de escritorio conectada al servidor también lo puede actualizar.
Checkout: APX sigue main del checkout desde donde corre; actualizar hace pull, instala, compila y reinicia.

Con APX_UPDATES=off se apagan los chequeos.

Desinstalar

Desinstalar saca el programa y su servicio. Tus datos quedan en ~/.apx/v2; borrá esa carpeta vos si querés empezar de cero. Los archivos de APX v1 en ~/.apx no se tocan en ningún caso.

macOS: cerrá APX desde su ícono en la barra de menú y arrastrá APX de Aplicaciones a la papelera.
Windows: Configuración › Aplicaciones › Aplicaciones instaladas › APX › Desinstalar.
Linux: cerrá APX y borrá el AppImage.

Si además instalaste el core como servicio en esta computadora (apx service install, o una instalación de servidor), sacalo con apx service uninstall o con los pasos de servidor de la pestaña siguiente.

Corré el instalador otra vez con la opción de desinstalar:

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

En Windows, desde PowerShell, guardá el script y correlo con -Uninstall:

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

Frena el servicio, borra ~/.apx/v2/app y el comando apx que escribió, y deja tus datos donde están. Con una copia guardada del script es bash install.sh --uninstall.

docker rm -f apx borra el contenedor; el volumen apx-data guarda tus datos hasta que hagas docker volume rm apx-data.

apx service uninstall saca el servicio; el checkout es tuyo para borrar.