APX (Agent Project eXecutable) is an open-source Agent OS for running AI agents on your own machine.
Your crew remembers in plain files, hands work to each other, and works from Claude Code, Codex, Telegram, WhatsApp and your phone.
One machine. One context. Your whole crew. Built on the APC protocol.

🌐 Visit the website  ·  Quick start · Examples · Web admin · Use cases · Android app · APC spec

APX is the reference implementation of the APC protocol. APX is to APC what a language SDK is to a protocol spec.

APX is a daemon + CLI that brings the APC convention to life:

• Daemon — a local HTTP server that manages projects, agents, sessions, and message logs
• CLI (apx) — commands for running agents, reading memory, tailing messages, managing sessions
• Web admin — a local web UI served by the daemon to browse projects, agents, sessions, and MCPs from the browser
• Runtimes — bridges to Claude Code, Codex, OpenCode, Aider
• Engines — direct LLM calls via Anthropic, OpenAI, Gemini, Ollama, or a mock
• Plugins — Telegram bot integration out of the box
• MCP support — each agent can expose or consume MCP servers

APX is opinionated about storage: the filesystem is the source of truth. Project definitions and curated memory live in the repo. Runtime state such as sessions, conversations, messages, and caches lives in ~/.apx/ and is never committed.

_{Your crew in a group chat: mention one agent and it pulls in the others. See more of your crew on the website →}

Three steps from nothing to your crew in the browser:

# 1 · Install (Node.js 22+)
npm install -g @agentprojectcontext/apx

# 2 · Set up — interactive wizard: provider → model → channels → starts the daemon.
#     It ends by printing the address of your panel.
apx setup

# 3 · Open the web panel
open http://localhost:7430        # macOS · on Linux: xdg-open · or paste it in any browser

That's the panel: chats, agents, tasks, routines and code sessions, all local. Want it on your phone too? apx panel share prints an address for your network (or apx panel tailscale on to reach it from anywhere on your tailnet) — open it and add it to your home screen.

Prefer the terminal? Everything the panel does, the CLI does too:

# In any directory with an AGENTS.md, register the project
apx init

# Spawn an agent with a full external runtime
apx run sofia --runtime claude-code "Review the open PRs and summarize them"

# Or a quick one-shot LLM exec
apx exec sofia "What is my role in this project?"

# Watch what's happening
apx messages tail

Real commands — copy one, point it at an agent like sofia, and APX routes it to the right runtime. The session transcript and its summary land in ~/.apx/; only curated memory and the agent definition live in .apc/.

• Review PRs across any runtime — point an agent at your repo; APX routes to Claude Code and falls back to Codex or OpenCode if one isn't installed. The session and its summary land in ~/.apx/.
• Operate your agents from Telegram — talk to project agents from your phone. Identity roles gate who can do what, and every message is logged per channel for a full audit trail.
• Memory that lives in your repo — curated, per-agent memory is plain markdown, committed and reviewable alongside your code. No vendor database, no hidden state, no lock-in.
• Run the same prompt across engines — send one prompt through Anthropic, OpenAI, Gemini or a local Ollama model with apx exec, configured per project or globally.

npm install -g @agentprojectcontext/apx

Requires Node.js 22+. The daemon starts automatically on first apx call.

APX has a native Android app — the phone surface, plus notifications, the floating mascot and Android Auto. It is not on Google Play: it installs from a file.

apx android install     # phone plugged in: installs, opens the USB tunnel and pairs

Or download it straight to the phone — this link always points at the newest signed build:

github.com/agentprojectcontext/apx/releases/download/android-latest/apx.apk

Which address the app connects to is the decision that matters: the USB tunnel (127.0.0.1) dies with the cable, your LAN (apx panel share) stops at the front door, and Tailscale (apx panel tailscale on) works from anywhere with a real certificate. Install on Android walks through all three. iPhone has no APK — the panel installs as a web app instead.

APX ships a local web admin — the same runtime, in your browser. The daemon serves a single-page app so you can browse and manage everything the CLI does without leaving the UI:

• Projects & agents — see registered projects, open agents, edit roles, models, and skills
• Sessions & messages — read past sessions and tail live activity across every channel
• MCPs, engines & channels — review MCP servers, configure engines, and manage Telegram/desktop

It runs entirely on your machine. Start the daemon (any apx call does this) and open:

apx            # ensures the daemon is up
open http://localhost:7430   # macOS — or just visit it in any browser

The web admin is served from src/interfaces/web/dist at the daemon port (7430 by default, override with APX_PORT). Nothing is sent anywhere — it talks to the local daemon only.

Project context — committed to the repository:

project-root/
├── AGENTS.md              ← agent definitions
└── .apc/
    ├── project.json       ← project metadata + stable "id"
    ├── agents/
    │   └── <slug>.md      ← agent definition (role, model, skills…)
    ├── mcps.json          ← MCP servers available to this project
    ├── skills/            ← reusable skill prompts
    └── commands/          ← custom slash commands

Runtime state — local machine only, never committed:

~/.apx/projects/<project-id>/
├── messages/              ← local message history
└── agents/
    ├── <slug>/
    │   ├── sessions/      ← one .md per runtime invocation
    │   └── conversations/ ← LLM conversation threads
    └── default/           ← fallback when no agent role is active
        └── sessions/

apx init [path]                          # initialize a project
apx agent list                           # list agents
apx agent add <slug> --role R --model M  # add an agent
apx memory <slug>                        # read agent memory
apx memory <slug> --append "<note>"      # append to memory

apx run   <slug> --runtime claude-code "<prompt>"   # full runtime session
apx run   <slug> --runtime cursor-agent "<prompt>"  # Cursor Agent runtime
apx exec  <slug> "<prompt>"                          # quick LLM call

apx session list <slug>                  # list past sessions
apx messages tail                        # last 50 messages, all channels
apx messages chat --channel telegram     # chat view with user/agent/system type
apx messages tail --channel runtime      # only agent invocations

Activity belongs to APX runtime state, not .apc/. Message storage is local to APX, under ~/.apx/:

JSONL messages include type (user, agent, tool, or system) plus actor_id, so chat views can distinguish Telegram users from APX agents and future subagents.

A channel is the surface a turn arrived on. The canonical list lives in src/core/constants/channels.js; voice is a mode, not a channel.

Global APX skill installation also writes named helper skills for codex-cli, claude-code, opencode-cli, and openrouter. They are intentionally narrow and should activate only when those tools/providers are explicitly mentioned.

Configured in ~/.apx/config.json:

{
  "engines": {
    "anthropic": { "api_key": "sk-ant-..." },
    "openai":    { "api_key": "sk-..." },
    "ollama":    { "base_url": "http://localhost:11434" },
    "gemini":    { "api_key": "..." }
  }
}

APX implements the APC specification. The spec defines the on-disk layout; APX provides the tooling to use it.

Questions, what other people are wiring up, and where new releases land first: discord.gg/vxdZuT5WuE

MIT