Pocket Server in a Nutshell: Turn Your Laptop into a Remote-Controllable Coding Agent for Your Phone

Core question answered in one line: “How can I run a Claude-style coding agent on my own machine and safely drive it from a subway seat using nothing but my phone?”

1. What Exactly Is Pocket Server?

Core question: “Is Pocket Server just another terminal app, or something else?”
Answer: It is the open-source backend half of Pocket Agent; it stays on your laptop, keeps all the state, and exposes HTTP + WebSocket endpoints so the mobile app can stream terminal sessions, edit files, search the web, and launch cloud jobs while you sip coffee.

2. Installation: One Curl to Rule Them All

Core question: “Do I need Node, Docker, or root privileges?”
Answer: No. A single curl script drops a self-contained binary with Node v22.18.0 baked in, adds the CLI to your PATH, and finishes in under 30 seconds.

# paste-and-run
curl -fsSL https://www.pocket-agent.xyz/install | bash

The script simply:

• Detects architecture (macOS arm64/x64, Linux x64)
• Downloads the matching release
• Symlinks pocket-server into ~/.pocket-server/bin (already in PATH)

Author’s reflection: I used to compile from source and fight native modules after every macOS upgrade. The bundled Node removes that pain; the runtime is immutable and travels with the app—exactly what “works on my machine” should mean.

3. First-Run Walk-through: Pair → Start → Connect

Core question: “What are the absolute minimum moves to see a terminal prompt on my phone?”

Once pairing succeeds, the server writes an encrypted device secret under ~/.pocket-server/data. Short-lived access tokens are derived from it; the PIN is never reused.

4. Local Attachment: Resume Phone Sessions on Your Desktop

Core question: “Can I jump from mobile to laptop without creating a new terminal?”
Answer: Yes. If you are on the same machine, no pairing is needed—the CLI exchanges a local socket key and re-attaches to the exact PTY you left on the phone.

# list active sessions
pocket-server terminal sessions

# jump back in
pocket-server terminal attach 3
pocket-server terminal attach --name "Backend-Compile"

Scenario: I started a Rust build on the subway, arrived at the office, typed attach, and the compile progress bar resumed on my external monitor—no re-run, no context lost.

5. Event-Driven Architecture: Why the Server Owns All State

Core question: “Who keeps the chat history, terminal buffer, and file revisions?”
Answer: Only the server. The mobile app is a stateless renderer that subscribes to events; everything lives in ~/.pocket-server/data.

Key endpoints (all prefixed by http(s)://host:port):

• /ws – bidirectional event stream (terminal output, file changes, job status)
• /auth/* – PIN pairing, token issuance
• /agent/* – create, pause, resume sessions
• /fs/* – read, write, diff, fuzzy search
• /cloud/* – spin up VMs, stream cloud logs back
• /notifications/* – optional push gateway

Reflection: This design saved me when my iPhone overheated and rebooted. I reopened the app, re-connected, and the terminal replayed the last 1000 lines automatically—because the session never left my laptop.

6. Cloud Jobs: Let a VM Finish While You Sleep

Core question: “How do I run long tasks if I close my laptop lid?”
Answer: Push the repo to a disposable VM. Pocket Server can clone any public (or accessible private) GitHub repo, boot a Linux box, inject your start script, and stream stdout exactly like a local tab.

Flow (all from the phone UI):

1. Pick repo → branch → entry command, e.g. pytest tests/
2. Server calls /cloud/launch → cloud provider boots image
3. VM stdout mirrors to mobile in real time
4. On completion, server diffs changed files, posts a comment to the PR, and pushes a “Job done” notification

Lesson learned: I underestimated cold-start time; the first VM took 45s to boot. Now I add sleep 5 && to the command line so the package cache warmer runs before my actual tests—total wall time dropped 20%.

7. Security Checklist: Local PIN, Rotating Tokens, No State in the Cloud

Core question: “Is any part of my code or keys stored on external infrastructure?”
Answer: No. Pairing is LAN-only; tokens expire quickly; the mobile app caches nothing; cloud VMs are ephemeral and under your GitHub credentials.

If you want a hard reset:

pocket-server stop
rm -rf ~/.pocket-server

All sessions, keys, and logs vanish.

8. Platform Support & Updating

Core question: “Will it work on my M2 Mac or on Ubuntu 22.04?”
Answer: Yes. Releases are published for macOS (arm64 & x64) and Linux x64. Updating re-runs the same installer and swaps the binary atomically.

pocket-server update   # fetches latest.json and patches itself

Reflection: I keep an old Intel Mac mini as a home server. The x64 binary boots in 400ms and uses ~65MB RAM idle—smaller than a single Chrome tab.

9. Troubleshooting Cheat-Sheet

10. Action Checklist / Implementation Steps

1. Install: curl -fsSL https://www.pocket-agent.xyz/install | bash
2. Pair: pocket-server pair → enter PIN in App (same Wi-Fi)
3. Start: pocket-server start (local) or pocket-server start --remote (public HTTPS)
4. Use: create terminal tabs, browse files, launch cloud jobs
5. Resume on desktop: pocket-server terminal attach <id>
6. Update: pocket-server update
7. Uninstall: rm -rf ~/.pocket-server (removes sessions & keys)

11. One-Page Overview

Pocket Server is a zero-dependency, single-binary server that turns any Mac or Linux laptop into a private backend for the Pocket mobile app. After a one-time LAN pairing, your phone becomes a multi-tab terminal, file editor, and cloud-job control panel. All state stays on the laptop; tokens are short-lived; optional Cloudflare tunnels give transient public URLs. You can attach desktop terminals to phone sessions without re-authentication, and you can offload long GitHub tasks to disposable VMs that report back when done. Installation, upgrade, and removal are each a single command.

12. FAQ

Q1: Does my laptop need a public IP?
No. Local Wi-Fi works out of the box; --remote gives a temporary Cloudflare URL.

Q2: Can I pair multiple phones?
The server accepts multiple devices; each gets its own secret.

Q3: Is Windows supported?
Official releases are macOS and Linux only; WSL2 is an unofficial workaround.

Q4: Where are my files actually edited?
All changes happen on the laptop where Pocket Server runs; the phone is just a remote keyboard/monitor.

Q5: How big is the install footprint?
~120MB including the bundled Node binary; runtime disk use grows with session logs.

Q6: Are cloud VMs free?
The document does not specify pricing; you supply your own GitHub token and presumably pay the cloud provider.

Q7: What happens if I reboot the server?
Active terminal sessions survive; cloud jobs keep running and reconnect on restart; access tokens are regenerated.

Q8: How do I back up my session history?
Copy ~/.pocket-server/data; conversations and PTY logs are plain JSON and typescript files.