workpod

A remote development environment manager — one CLI for everything you need on remote machines.

workpod — manage and connect to remote development pods over SSH

Install

git clone https://github.com/xmonader/workpod
cd workpod
go install .

Prerequisites

✓ SSH key — Either existing keys at ~/.ssh/ (id_ed25519, id_rsa) or run:

ssh-keygen -t ed25519 -C "your-email@example.com"

✗ NOT required — SSH agent. You can use workpod without eval $(ssh-agent -s).

See SSH_AUTH.md for auth options and setup.

Quick Start

Two ways to add your first pod:

Easy way (interactive menu — no YAML needed)

workpod config
# Menu-driven: choose "Add new pod", answer prompts
# Great if you're not comfortable with YAML editing

Fast way (command prompt)

workpod add myserver
# > Host: 192.168.1.10
# > User: ubuntu
# > Port: 22
# > Identity file: ~/.ssh/id_rsa
# > Workspace: ~/projects

Advanced way (YAML editor)

workpod edit
# Opens config in your preferred editor (nano, gedit, VS Code, vim, etc.)
# Set your editor with: export EDITOR=nano

Once you have a pod:

workpod init myserver          # Bootstrap the remote
workpod ssh myserver           # Open a shell
workpod forward myserver       # Start port tunnels
workpod code myserver          # Open in VS Code
workpod browser myserver       # Open code-server in browser
workpod sync myserver          # Sync local cwd → remote
workpod watch myserver         # Auto-sync on file change
workpod serve                  # Launch web UI dashboard

Commands

Command	Description
workpod config	Interactive menu — add/edit/remove pods without YAML
workpod add <name>	Add a pod with guided prompts
workpod list	List pods with live connectivity status
workpod remove <name>	Remove a pod
workpod edit	Edit config in your preferred editor (nano/gedit/code/vim)
workpod status [name]	Show connectivity + uptime/disk/CPU/mem
workpod ssh <name>	Interactive SSH shell
workpod exec <name> <cmd>	Run remote command, stream output
workpod forward <name>	Start all port tunnels (foreground)
workpod sync <name>	rsync local CWD → remote workspace
workpod watch <name>	Auto-sync on file change (fsnotify)
workpod code <name>	Launch VS Code Remote SSH
workpod browser <name>	Start code-server + open browser
workpod init <name>	Run setup_script on remote to bootstrap env
workpod serve [--addr]	Local web UI dashboard (default :7070)

Configuration

Pod configurations live in ~/.config/workpod/config.yaml.

See CONFIG_STORAGE.md for details on:

• Where data is stored (~/.config/workpod/, ~/.ssh/config, ~/.ssh/known_hosts)
• Security model (file permissions, key handling)
• TOFU host key verification
• Environment variables

Quick example:

pods:
  myserver:
    host: 192.168.1.10
    user: ubuntu
    port: 22
    identity_file: ~/.ssh/id_rsa
    workspace: ~/projects/myapp
    tags: [dev, python]

File Sync

workpod sync uses rsync under the hood. It respects:

• .workpodignore — workpod-specific ignore rules (.gitignore syntax)
• .gitignore — automatically excluded too

# Dry run — see what would be synced
workpod sync myserver --dry-run

# Delete remote files not present locally
workpod sync myserver --delete

Web UI

workpod serve launches a local dashboard at http://127.0.0.1:7070:

• Live pod status via Server-Sent Events
• In-browser terminal (xterm.js + WebSocket → SSH PTY)
• Port forward management (start/stop tunnels)
• VS Code / code-server launch buttons
• Resource stats (uptime, disk, memory)

Choosing Your Editor

When you run workpod edit, workpod automatically finds a user-friendly editor:

1. Uses $EDITOR env var if set:

   export EDITOR=nano      # Easiest to learn, beginner-friendly
   export EDITOR=gedit     # GNOME graphical editor
   export EDITOR=code      # Visual Studio Code
   export EDITOR=emacs     # Powerful but steep learning curve

2. Auto-detects available editors in this order:

   • nano — Simple, beginner-friendly (recommended)
   • gedit — GNOME GUI editor
   • code — VS Code
   • emacs — Powerful text editor
   • vim/vi — Falls back to vi (with a helpful warning)

If you don't know vi/vim, just set your shell to use nano:

# Add to ~/.bashrc or ~/.zshrc:
export EDITOR=nano

# Then reload:
source ~/.bashrc
workpod edit

SSH Authentication

Good news: SSH agent is optional! workpod supports three auth methods:

1. Identity files (recommended) — ~/.ssh/id_ed25519, id_rsa, etc. Works without setup.
2. SSH agent (optional) — Faster for repeated connections, requires ssh-add.
3. Password (config) — Can be set in pod config, but less secure.

workpod tries them in order. If you have SSH keys, it just works.

Check your setup:

workpod auth-help

Full guide: See SSH_AUTH.md for scenarios, troubleshooting, and setup options.

Environment Variables

Variable	Description
WORKPOD_CONFIG_DIR	Override config directory (default: ~/.config/workpod)
EDITOR	Editor for workpod edit (default: auto-detect nano, gedit, code, vim)
SSH_AUTH_SOCK	SSH agent socket