Agent

The PocketDev agent is the self-hosted runtime at the center of the system — a single Bun + Elysia process you install on your own Linux server. It pairs with your phone, spawns and streams AI coding tasks, exposes an interactive terminal, brokers file and git operations, proxies your dev server for preview, and serves a browser-based admin console — all over one port.

Try the console

Every agent serves a browser-based control plane called the console. The demo below is the exact console UI running entirely in your browser against sample data — no install, no server, nothing to pair. Click around: inspect tool readiness, browse the sample repository, review tasks and diagnostics, and open the terminal.

Try the live console demo →

Install

Run this on your server to install the agent as a systemd service on port 4387:

On first boot the agent generates an Ed25519 keypair and a short-lived setup code, then opens the console for admin account creation. See Get Started for the full pairing walkthrough.

Single-port architecture

Everything the agent does is reachable through one Elysia process under the /PocketDev/ namespace. There are no extra daemons or ports to manage (aside from the optional wake server — see Architecture).

• GET /PocketDev/health — health check and first-boot pairing status
• /PocketDev/api/console/* — console admin auth, pairing, diagnostics, repo inspection
• /PocketDev/api/pair — one-time mobile device pairing
• /PocketDev/api/files/*, /api/git/*, /api/projects/* — authenticated device REST API
• /PocketDev/ws — task command and event WebSocket
• /PocketDev/ws/terminal — interactive PTY shell session
• /PocketDev/preview/* — reverse proxy to your local dev server
• /PocketDev/* — static catch-all that serves the console SPA

Key services

• Task manager — spawns Claude, Codex, Copilot, or shell processes, streams stdout/stderr line-by-line to paired devices, and auto-detects the dev server port from task output.
• Terminal — allocates a real PTY via the script command and streams it over a WebSocket. One session per connection, torn down on disconnect.
• File API — tree listing, read/write, search (ripgrep with a grep fallback), all path-validated against the project directory to prevent traversal.
• Dev preview proxy — forwards /preview/* to your running dev server so you can view it from the mobile app.
• Setup & pairing — a one-time 15-minute setup code and Ed25519 device enrollment, disabled the moment a device is paired.

Local state

The agent is stateless apart from a self-contained SQLite database (via bun:sqlite + Drizzle) living under $POCKETDEV_DATA_DIR. It tracks paired devices, task history and streaming logs, agent plans, detected CLI tool paths, and the console admin account. Migrations apply automatically on startup, so updates never require a manual database step.

The web console

The console is a React 19 + Vite SPA (with xterm.js and shadcn/ui) that the agent serves directly. It is where the server owner creates the admin account, pairs and manages devices via a QR code and passcode, monitors toolchain readiness, inspects the active repository, reviews task history, and opens a full server terminal — all from a browser.

Try the live console demo →

Security

• Setup mode is temporary — a 15-minute, one-time setup code that disables after pairing.
• Each device authenticates with its own Ed25519 keypair; there are no long-term shared secrets.
• The browser console has a separate admin account with a cookie session.
• File, git, terminal, and preview actions are mediated by the agent rather than exposing direct host access.
• Operational data stays local to the machine you control.

For the full trust model, port-locking, and wire protocol, see the Architecture page.