PocketDev/Docs

Get Started

PocketDev is a mobile-first interface for controlling AI coding agents on remote servers. Install it on a Linux machine running Ubuntu 24.04, pair your phone, and control Claude, Codex, or GitHub Copilot from anywhere.

Prerequisites

  • A Linux server (Ubuntu 24.04+ has been tested but other distributions may work) with SSH access
  • At least 1 GB of RAM and 2 GB of disk space
  • A mobile device running iOS 16+ (Android coming soon)

Installation

Run this on your server to install the PocketDev agent:

$curl -fsSL https://pocketdev.run/install.sh | bash

The installer will set up the PocketDev agent as a systemd service on port 4387.

Logging into the PocketDev Agent web app

  1. Open the PocketDev app on port 4387/PocketDev/console of your server in a web browser
  2. Setup your admin account
  3. Login
  4. Navigate to the Pairing section
  5. Copy the setup code

Example code:

pocketdev://123.123.12.123:4387/DCCU-6451

Pairing Your Device

  1. Open the PocketDev app on your phone
  2. Paste the setup code
  3. Click pair workspace

Pairing creates an Ed25519 keypair on your device. All future connections are authenticated with this key.

Setup Wizards

Once paired, the app opens the Workspace Tools screen — a guided setup flow that detects what's installed on your server and walks you through configuring everything PocketDev needs to run AI coding tasks. You must complete setup before you can start tasks.

The setup checklist groups tools into categories:

  • Required Tools — Git (with SSH key + GitHub CLI auth) and a package manager (npm, pnpm, or yarn)
  • AI Assistants — At least one of Claude, Codex, or GitHub Copilot must be authenticated
  • Languages — Python, Rust, Go, TypeScript (detected automatically)
  • Infrastructure — Docker (optional)

Your workspace is ready when the required tools, at least one AI assistant, and Python are all configured. If an install step fails, you can tap AI Inspect to have an AI agent diagnose the failure and suggest a fix command.

Git & SSH Setup

The Git wizard is the most involved setup step. It walks you through the full SSH + GitHub authentication flow from your phone — no need to SSH into the server yourself.

1. Detect

The wizard starts by scanning your server for existing Git config: whether Git is installed, whether an SSH key exists, whether GitHub SSH works, GitHub CLI status, and your current Git identity. Steps that are already configured are automatically skipped.

2. Install Git

If Git isn't installed, PocketDev runs sudo apt-get install -y git on your server via a live terminal session. You'll see the output in real-time and may be prompted for your server's sudo password.

3. Generate SSH Key

PocketDev generates an Ed25519 SSH key pair on the server at ~/.ssh/id_ed25519. The private key never leaves the server — only the public key is displayed for you to copy. If a key already exists, you can keep it or generate a new one.

4. Add Key to GitHub

The app displays your public key with a copy button, then opens GitHub's SSH key settings page in your browser. You paste the key, name it (e.g. "PocketDev"), and click "Add key" on GitHub. Then return to the app and confirm.

5. Test Connection

The server runs ssh -T git@github.com to verify the key is registered. On success, it shows your GitHub username. If it fails, you can go back and re-add the key.

6. Install GitHub CLI

PocketDev installs the gh CLI from GitHub's official APT repository. This enables private repository discovery in the project picker.

7. Authenticate GitHub CLI

Two methods are available:

  • Browser sign-in (recommended) — The app starts a device code flow. You'll see a one-time code, then open GitHub in your browser to enter it. The app polls for completion and advances automatically once you approve.
  • Access token — Paste a GitHub personal access token directly.

8. Configure Identity

Set your git config --global user.name and user.email for commits. These fields are pre-filled if already configured on the server.

Code Screen

Once setup is complete, the Code tab gives you full access to your workspace's files and Git state. It has three views you can switch between:

  • Files — Browse and edit your project's file tree, search files with ripgrep, and view code with syntax highlighting
  • Git — See branches, staged/unstaged changes, commit diffs, and manage commits and pushes
  • Scripts — Run and monitor package.json scripts on your server

The Code screen also shows your active project context — tap the project banner to switch between repositories or clone a new one.

Your First Task

With setup complete, you can start an AI coding task from the Tasks screen:

  1. Tap the + button to create a new task
  2. Type a prompt describing what you want the AI to do
  3. Choose your agent (Claude, Codex, or a custom CLI)
  4. Watch the output stream in real-time as the agent works

You can also open the built-in terminal for direct shell access and preview your dev server — all from your phone.

Next Steps

More documentation is coming soon. In the meantime, check out the architecture overview for a deeper look at how PocketDev works.