Back to Pocket Dev

Pocket Dev docs

Install on Linux

Contents

Install Pocket Dev on Linux

Prefer your coding assistant? Copy the setup prompt and paste it into an agent running on your computer. AI setup details.

Written from the code and not yet run on a real Linux machine. If something here is wrong, please report the exact error text.

1. Prerequisites

  • Node.js 22 or newer with npm. Distribution packages are often older, so check. With nvm: nvm install 22. Or NodeSource, or the download at nodejs.org.
  • Only if node-pty has to be built: a compiler and Python 3, for example sudo apt install build-essential python3.
  • A phone on the same Wi-Fi as the computer.
node -v
npm -v

You should see v22 or higher, then an npm version. Installing Node with nvm or fnm keeps npm's global folder in your home folder, so you never need sudo for npm.

2. Install

Keep the @anisirji/ and the -g:

npm install -g @anisirji/pocket-dev
pocket-dev doctor

pocket-dev doctor checks Node, npm's global folder on PATH, the command, terminals, tools and port 7777, and prints the exact fix for each cross.

Installing also adds a Pocket Dev Admin entry, with the Pocket Dev logo, to your applications menu, and on GNOME to your favourites (the dock). It does this only when a desktop session is present, so a server installed over SSH is left alone. On other desktops it stops at the menu entry (KDE: right-click it, Pin to Task Manager). This is the one change the install makes without asking. Undo: pocket-dev admin unpin. Skip: POCKET_DEV_NO_PIN=1 npm install -g @anisirji/pocket-dev, or --ignore-scripts; pocket-dev setup still offers it. This part is covered by tests with fixtures; it has not been run on a real Linux desktop.

3. Start

pocket-dev start

You should see a QR code, then:

Pocket Dev running at http://192.168.1.20:7777
Password: Xk3p9QwR2tLm

The password is shown once, so copy it. Scan the QR code with the phone camera, or open the address and type the password. Missed the address? hostname -I prints the computer's addresses; use the Wi-Fi or LAN one. Add --no-open if you do not want the Admin page to open a browser (a server with no desktop).

4. Firewall

If a firewall is on, allow TCP port 7777 from your local network only.

# ufw (Ubuntu, Debian)
sudo ufw allow from 192.168.1.0/24 to any port 7777 proto tcp

# firewalld (Fedora, RHEL)
sudo firewall-cmd --add-port=7777/tcp --permanent && sudo firewall-cmd --reload

Change 192.168.1.0/24 to your own network. The firewalld command opens the port to all sources; use a rich rule if you want to limit it.

5. Optional tools

Chats need at least one of Claude Code or Codex. pocket-dev setup --check lists what is missing. pocket-dev setup shows each command first and prints (never runs) any command that needs sudo.

ToolInstallLog in
Claude Codenpm install -g @anthropic-ai/claude-codeclaude auth login
Codexnpm install -g @openai/codexcodex login
Gitsudo apt install git, sudo dnf install git, sudo pacman -S git or sudo zypper install gitnone
GitHub CLI (gh)sudo apt install gh, sudo dnf install gh, sudo pacman -S github-cli; or install instructionsgh auth login
cloudflared (internet access only)download page; sudo pacman -S cloudflared on Archnone for a Quick link

Experimental: Google Antigravity CLI (agy) in Chat. Pocket Dev starts agy acp and talks to it over the Agent Client Protocol. It was tested by hand on macOS with Antigravity CLI 1.5.9, and not yet on this system, so it may not work here. See the roadmap.

Experimental: GitHub Copilot CLI (copilot) in Chat. Pocket Dev starts copilot --acp --stdio and talks to it over the Agent Client Protocol, with the sign-in that copilot login made. It was tested on macOS with Copilot CLI 1.0.112, and not yet on this system. See the roadmap.

6. Keep it running, start at login

  • Quick way: nohup pocket-dev start --no-open > ~/pocket-dev.log 2>&1 &
  • Start at login with systemd: pocket-dev setup --only autostart writes the user unit ~/.config/systemd/user/dev.pocket.server.service and enables it. The Admin page (pocket-dev admin, Service) does the same. To start before you log in, run loginctl enable-linger $USER once.

Coming soon: pocket-dev service on Linux. Today it is macOS only.

7. Update and uninstall

npm install -g @anisirji/pocket-dev@latest
npm uninstall -g @anisirji/pocket-dev

Restart Pocket Dev after updating. Settings stay in ~/.pocket-dev until you delete that folder.

Errors and fixes

You seeCause and fix
unknown command 'start'. See 'main --help', or EEXIST on installA different npm package named pocket-dev owns the command. npm uninstall -g pocket-dev, then npm install -g @anisirji/pocket-dev.
command not found: pocket-devYou skipped -g, or the terminal predates the install. Open a new terminal. npm config get prefix shows npm's global folder; its bin must be on PATH. Or run npx -y @anisirji/pocket-dev doctor.
404, or it installs from GitHubUse the scoped name with the @: @anisirji/pocket-dev.
EACCES writing npm's global folderInstall Node with nvm or fnm, or run the sudo npm install -g @anisirji/pocket-dev you are shown.
node-pty fails to buildsudo apt install build-essential python3, then pocket-dev doctor --fix.
"Terminals are not available on this computer"pocket-dev doctor --fix, then restart Pocket Dev.
The phone cannot open the addressSame Wi-Fi (not mobile data or an isolated guest network)? Port 7777 allowed in step 4? Use the numeric address from hostname -I, not localhost. Run pocket-dev doctor.
Port 7777 is in usepocket-dev start --port 7780, or pocket-dev config set port 7780.
Start at login says there is no systemctlYour system has no systemd. Use the nohup line or your init system's own service file.
Forgot the passwordpocket-dev setup --only password, or pocket-dev admin (needs a browser on that computer).

More: full guide, reference.

Read from docs/linux.md in the repository and refreshed about once an hour.