Appx

Agentic Application Proxy — a self-hostable tool to build and host personal apps with AI agents powered by Pi.

What it does

Appx is a management shell for running coding agents on a remote server. It provides authentication, TLS termination, a web dashboard, and a reverse proxy — so you can manage projects, chat with agents, and access agent-built apps from a browser over HTTPS.

Architecture

Browser
  └── HTTPS (single port)
        ├── /              React SPA (embedded in binary)
        ├── /api/*         REST API (auth, projects, settings)
        ├── /api/pi/*       → agent-server /v1 mirror (agent-client SDK; project-scoped sessions + models)
        ├── /api/agent/*    → Pi agent-server shared auth/model proxy
        └── <project>.<domain>   Reverse proxy → agent-built apps

Appx itself is a single Go binary; the React frontend is compiled and embedded at build time, and state lives in a SQLite database on disk.

Pi is the agent runtime. In production appx runs as the appx systemd service and supervises an outer container that holds agent-server + Pi + rootless podman; agent-server (published on loopback 127.0.0.1:4001) owns project identity, directories, and sessions while sharing one set of Pi credentials, and Appx proxies session traffic to it. In local dev agent-server is run by hand and appx points at it via APPX_AGENT_SERVER_URL (no systemd, no container).

Auth model: single user, password login, session cookie. On first run a random password is generated and written to {data-dir}/.appx-internals/initial_password.

TLS: self-signed ECDSA P-256 certificate auto-generated on first run, auto-renewed 7 days before expiry. For production, use APPX_DOMAIN + CLOUDFLARE_API_TOKEN for Let's Encrypt.

Documentation

• Self-Hosting — prerequisites, the from-scratch install, provider secrets, updating, verification, troubleshooting, and known gotchas (incl. Amazon Bedrock).
• Networking & TLS — subdomain routing via sslip.io and automatic Let's Encrypt certificates.
• Storage & Isolation — where state lives (host data dir + Docker volumes), what survives a container restart, the user/isolation model, and caveats.
• Local Development — the no-systemd, no-container dev flow (run agent-server by hand + appx --http).
• CLAUDE.md — architecture details and development conventions.

Prerequisites (production)

A Linux host (Ubuntu 24.04 LTS recommended), git, rootful Docker, and the sibling agent-server + agent-client repos checked out next to appx. Then:

cd /srv/appx
sudo ./deploy/bootstrap.sh

See Self-Hosting for the complete, ordered steps.