PocketDev/Docs

Architecture

PocketDev is split into a hosted website, a self-hosted agent runtime, a browser-based console, and a mobile app. The public website and the self-hosted runtime are separate products. Your live server state, paired devices, terminal sessions, and workspace actions stay with the agent running on your own machine.

System Overview

The core runtime is the PocketDev agent, a Bun and Elysia process running on your Linux server. It handles pairing, task orchestration, terminal sessions, file access, preview proxying, and local SQLite-backed runtime state.

The console is a browser-based control plane served by that agent. It is used for admin setup, diagnostics, pairing, repository inspection, and direct terminal access.

The mobile app is the remote workspace interface. It is designed for tasks, plans, files, git actions, project switching, container operations, and guided setup flows from a phone or tablet.

Shared contracts live in `@pocketdev/shared`, which keeps the wire protocol, schema definitions, theme tokens, and cryptographic primitives aligned across the monorepo.

Workspace Readiness Model

PocketDev treats setup as capability enablement instead of a flat checklist. The app groups tooling by role and blocks workflows until the server has what that workflow actually requires.

The first readiness group is required setup: Git, GitHub CLI, and a Node-compatible package manager path. Without those pieces, repository and script workflows remain incomplete.

The second group is AI assistant support. PocketDev is built to work with at least one assistant path such as Claude, Codex, or GitHub Copilot, depending on how the server is configured.

The third group is language support. Python is especially important because it unlocks more capable setup inspection and automation paths.

Agent API Surface

The self-hosted agent exposes a single-port interface under the `PocketDev` namespace, but that surface includes several distinct product areas.

Console and Setup Endpoints

  • GET /PocketDev/health for health checks and first-boot status
  • /PocketDev/api/console/* for admin auth, passcode flows, pairing status, diagnostics, and repository inspection
  • /PocketDev/api/pair for mobile pairing handshakes
  • /PocketDev/* as the static catch-all that serves the console SPA

Realtime Transport

  • /PocketDev/ws for task commands, plan events, file approvals, and streamed server state
  • /PocketDev/ws/terminal for interactive PTY-backed terminal sessions

Device REST Endpoints

  • /PocketDev/api/files/* for tree browsing, reads, search, and file approval workflows
  • /PocketDev/api/git/* for change inspection, commits, branch actions, and pushes
  • /PocketDev/api/projects/* for repository selection, cloning, and active project switching
  • /PocketDev/api/containers/* for listing containers, lifecycle actions, and logs

Preview Proxy

  • /PocketDev/preview/* for reverse proxying the active development server running on the host

Security Model

PocketDev separates trust boundaries between the public website, the self-hosted agent, and the paired clients that talk to that agent.

  • Each paired device generates its own Ed25519 keypair. The agent stores the public key, and signed requests prove device identity.
  • Mobile pairing uses short-lived passcodes and explicit approval so the server owner controls enrollment.
  • The browser console has its own admin account and cookie session, separate from device key-based authentication.
  • File, git, terminal, and preview actions are mediated by the agent instead of exposing direct host access from clients.
  • Operational runtime data stays local to the machine you control, primarily in SQLite on the agent and secure local client storage on devices.

Port Security

When enabled, the agent can block its own port at the iptables level, making the server invisible to scanners when not in use. This is opt-in and disabled by default.

The design uses two ports. The main agent port (4387) can be blocked by iptables when no mobile clients are active. A secondary wake server on port 4388 stays permanently open but accepts only one request type: a signed POST /wake from a registered device. This solves the catch-22 of "port is closed, how do I reopen it" — the mobile app sends a wake request to port 4388, which verifies the Ed25519 signature and unblocks port 4387.

  • Auto-lock fires after configurable inactivity with no active WebSocket clients. Skipped if a task is running.
  • Manual lock and unlock are available from the mobile app Settings screen and the server console's Network diagnostics tab.
  • The wake server rate-limits attempts per IP (3 per 60 seconds) to prevent brute force.
  • The agent always boots unlocked, so restarts and updates never leave the server inaccessible.

Wire Protocol

The typed protocol shared by PocketDev covers more than task output. It also supports plans, setup diagnostics, terminal sessions, container logs, and connection-health events through a common message envelope.

Example Commands

  • task.start
  • task.kill
  • task.input
  • container.logs.follow
  • terminal.input
  • setup.check_prerequisites
  • plan.answer
  • plan.accept

Example Events

  • task.output
  • task.status_changed
  • task.completed
  • terminal.output
  • setup.prerequisites_result
  • plan.proposed
  • plan.step_updated
  • plan.resolved
  • server.locked
  • server.unlocked
{
  type: "plan.step_updated",
  id: "msg_01",
  payload: { step_id: "step_repo", status: "completed" },
  timestamp: 1712000000
}

Tech Stack

PocketDev uses different runtimes for the hosted web layer, the self-hosted agent, and the user-facing clients, but keeps them aligned with shared TypeScript contracts.

  • Hosted web: TanStack Start, Vite, Postgres, and @pocketdev/db
  • Agent: Bun, Elysia, SQLite with Drizzle, and PTY/process orchestration
  • Console: React 19, Vite, react-router-dom, xterm.js, shadcn/ui, and Tailwind 4
  • Mobile: React Native 0.83, Rock CLI with Re.Pack, Zustand, MMKV, and Keychain-backed storage
  • Shared: typed WebSocket protocol, Zod schemas, theme tokens, and @noble/ed25519
  • Tooling: Claude, Codex, and Copilot CLIs plus git, ripgrep, and local dev servers

Future Development

I am... going back and forth on open-sourcing PocketDev itself. There are parts of the system that could be valuable to the community if released, but I also am weighing the security implications of exposing the agent and protocol. Monetization and sustainability of the project are also factors in deciding whether to open-source the codebase or keep it internal. App Store guidelines, publishing fees, and review requirements for the mobile client also influence how much of the system can be exposed publicly versus kept behind the agent boundary. One idea I was thinking about was open sourcing the repo, adding a stipulation that the code cannot be used to create a competing mobile app, and charging a one-time fee to download the mobile app to cover App Store publishing costs and help support ongoing development of the project.