Self-hosted Android terminal and agent companion. SSH from your phone into your own host, manage tmux sessions, browse files over SFTP, and answer agent approvals from your pocket — no third-party cloud. Terminal and file traffic flows over your direct SSH connection.
The backend only ever sees agent event summaries and approval metadata; terminal output, file contents, diffs, and chat never reach it.
- Real SSH terminal — TOFU host-key pinning, ed25519/RSA key auth, full ANSI/VT parser (alternate screen, scroll regions, synchronized output, DSR/DA/DECRQM queries); works with Codex, vim, htop, tmux, and other TUIs
- Persistent tmux sessions — named sessions, multi-session tabs, reconnect-attach; sessions survive connection drops on the host
- SFTP file manager — list, read, write, download, and share
- Gateway + workspace — workspace files, git diffs, and HTTP preview tunneled over SSH loopback (jailed, token-authenticated)
- Agent hooks — Claude/Codex event stream: notifications, approval requests, chat-style output, 24h-TTL summary inbox
- Android UX — one sessions-first screen with live previews, a terminal that slides up as a layer, an agent-prompt key panel (Enter, arrows, Shift+Tab, snippets), explicit close-or-detach, per-host avatars, 19 contrast-checked themes, terminal fonts, pinch-zoom, OSC52 clipboard, OSC8 hyperlinks, two-pane layout on tablets (docs/design.md)
- Mosh bootstrap —
mosh-serveris packaged for the host; the roaming client side is experimental (see Status and limits)
Android app ──SSH/PTY+SFTP──► Host (sshd + tmux + gateway :loopback)
│ │
└──HTTPS──► Backend ◄──flusher──┘ pocket-agent daemon
(event summaries, (journal → summary POST)
approvals, inbox)
| Sent to the backend | Never sent to the backend |
|---|---|
| Agent event summary (source, category, message) | Terminal output / keystrokes |
| Approval request + decision metadata | File contents, diffs, chat |
| Pairing claim, tenant boundary | SSH keys, gateway token |
The backend stores summaries with a 24-hour TTL in PostgreSQL (DATABASE_URL;
in-memory only when unset); tokens are stored hash-only. Every API call carries
a bearer token: hosts get one at registration, each phone gets its own when it
claims a pairing code. Pairing is keyless: the phone generates its SSH key pair
locally and sends only the public key; the host shows the device and key
fingerprint, and authorizes it in authorized_keys after you confirm.
Requirements: Node 18+ on the host (for npm install) plus sshd; Docker + Compose for the backend; Android 10+ (minSdk 29).
# 1) Backend (optional but recommended — powers agent events/approvals)
cd deploy/docker-compose && cp .env.example .env # fill in your domain
docker compose up -d # or ./bootstrap.sh
# 2) Host CLI — no Go toolchain needed, binaries ship in the package
npm install -g pocket-agent-cli
pocket-agent onboard --backend https://<your-domain>
# 3) Android APK
# https://github.com/azygoss/pocket-agent/releases/latest → pocket-agent-<ver>.apk
# In the app, scan the QR code or enter the XXXX-XXXX pairing codeThe npm package ships Linux/macOS x64 + arm64 and Windows x64 (experimental)
binaries; it installs the pocket-agent and pocket-agent-hook commands.
| Command | What it does |
|---|---|
pocket-agent onboard |
Daemon + gateway + hooks + pair QR in one step |
pocket-agent pair / unpair |
Generate QR + XXXX-XXXX code / remove pairing |
pocket-agent doctor --json |
sshd, port, disk, backend checks |
pocket-agent status --json |
Version + health summary |
pocket-agent hooks install |
Register Claude/Codex hooks in their config |
pocket-agent service install |
systemd user units (daemon + gateway) |
pocket-agent servers |
List active tmux sessions |
pocket-agent gateway serve |
File/diff server (loopback only) |
pocket-agent completion bash |
Shell completion (bash/zsh/fish) |
pocket-agent version |
Version |
Full list: pocket-agent help.
- Terminal: full-screen VT100/xterm emulation, alternate screen, atomic TUI frames via synchronized output (DECSET 2026), 50k-line scrollback, pinch-zoom, selection + OSC52 copy, key panel with hold-to- repeat arrows, keep-screen-on while watching an agent
- Connection: SSH keepalive, automatic reconnect, hard-stop warning on TOFU pin change, experimental Mosh roaming
- Sessions: named tmux sessions, live session cards, attach to tmux sessions started on another device, close or detach (keep running on the host)
- Files: SFTP browser, upload/download/share, image viewer, line-numbered reader (grep jumps to the matching line), hidden files and sorting, workspace + git diff view, HTTP preview
- App: IBM Plex Sans/Mono interface, theme and terminal font settings, key panel snippets, agent activity feed, notifications and approval dialogs
Requirements: Go (version in go.mod), JDK 17, Android SDK 34 + NDK/CMake, Buf (for proto lint).
sudo ./scripts/setup-dev-environment.sh # toolchain (one time)
source ./scripts/dev-env.sh
./scripts/verify-dev-environment.sh
make gates # secret-scan + license + packaging + buf lint + canary
make go # go test + vet + build
make android # lintDebug + testDebugUnitTest + assembleDebug
make live-up && make live-test # env-gated live suites (SSH/SFTP/gateway)
make npm-package # dist/pocket-agent-cli-*.tgzArtifacts: apps/android/app/build/outputs/apk/debug/app-debug.apk,
dist/ (CLI tarballs + checksums).
| Path | Contents |
|---|---|
apps/android/ |
Kotlin + Compose app (ui/ transport/ data/ net/ service/ security/) |
cmd/pocket-agent-hook/ + host/ |
Go CLI + daemon (pairing, gateway, hooks, journal, ssh, tmux) |
backend/ |
Go API (api/ approvals/ auth/ inbox/ store) + PostgreSQL |
protocol/ |
Buf v2 proto contracts (v1 frozen) |
deploy/docker-compose/ |
Backend + Caddy deployment, backup/restore |
packages/npm/ |
npm package (pocket-agent-cli) |
native/mosh/ |
Mosh source/build metadata + libmoshclient.so hashes |
scripts/ tests/ |
Gates, packaging, e2e/fuzz/perf/protocol tests |
docs/ |
Install, security, backup, rollback, design language docs |
- SSH TOFU — the host key is pinned on first connect; a pin change hard-stops and requires explicit user approval
- Keys — Android Keystore-backed; private keys are never written to
disk in plaintext and no secrets live in this repo (
make gatesscans) - Gateway — loopback-only bind, 0600 token file, workspace jail, path-traversal and SSRF protection
- Backend — hash-only tokens, single-use short-TTL pairing codes, tenant isolation enforced on every query, 24h summary TTL
- Signing — CLI
updateaccepts only signed manifests; release APKs are verified withapksigner verify. Debug APKs are not release-signed.
Details: docs/security/privacy.md,
threat-model.md,
incident-response.md.
- Working and live-tested: SSH/PTY, SFTP, tmux, gateway, pairing, backend event/approval flow, npm CLI install
- Mosh: host bootstrap + native client packaged; real-device roaming field testing is still in progress
- ET (Eternal Terminal): deferred
- Emulator/device-dependent tests (frame pacing, biometrics, some a11y flows) are partially covered in CI via Robolectric
- A production backend requires TLS + a domain;
network_security_configonly permits cleartext to localhost/emulator addresses - Current versions: Android
v0.41.0, npm CLI0.1.0(0.1.2packaged, not yet on npm)
make gates && make go && make android # full gate set
make live-up && make live-test # against a real sshd/backend/gatewayLive suites are env-gated (PA_LIVE_SSH, PA_LIVE_BACKEND, PA_LIVE_GW);
scripts/live-env.sh sets up the local fixture (test user, loopback
gateway, preview server).
Rules and test layers: CONTRIBUTING.md.
Reproducible builds and hash verification: REPRODUCING.md.
Third-party component list: NOTICE.
Clean-room rule: no brand, code, or assets are copied from reference
products; docs/reference/ only contains links to publicly available
behavioral sources and never ships in any release artifact.
GPL-3.0-or-later — see LICENSE and NOTICE.
Upstream Mosh/ET sources under native/ keep their own licenses.