Agentum

Control AI coding agents from your phone. Mirror Claude Code, GitHub Copilot, and OpenAI Codex to mobile - code from your couch, bed, or anywhere.

How It Works

┌──────────────┐     WebSocket      ┌──────────────┐
│  Your Phone  │ ◄────────────────► │   Desktop    │
│  (Agentum    │                    │(agentum start)│
│   Mobile)    │                    │              │
└──────────────┘                    └──────────────┘
                                           │
                                    ┌──────┴──────┐
                                    │ AI Agents   │
                                    │ Claude Code │
                                    │ Copilot     │
                                    │ Codex       │
                                    └─────────────┘

Prerequisites

You need Node.js (v18+) installed. Then, install and authenticate the AI agents you want to control:

Only install and authenticate the agents you plan to use.

Quick Setup

1. Install CLI on your desktop

npm install -g agentum

2. Start the server

npx agentum start

This shows your connection info:

Terminal server started on port 11042
Connect from mobile using IP: <your-ip>, Port: 11042

3. Find your IP (if needed)

# macOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1

# Or just use
hostname -I   # Linux
ipconfig      # Windows

4. Get the mobile app

5. Connect

Open the mobile app and enter:

• IP/Host: Your desktop's IP address
• Port: 11042 (default)

That's it! Your AI agents now stream to your phone.

Commands

agentum start

Start the server. Run this first.

agentum start                    # Default: port 11042
agentum start --port 8080        # Custom port
agentum start --no-vnc           # Disable screen sharing

agentum run <command>

Run any command and mirror output to mobile.

agentum run "npm test"
agentum run "python train.py" -d     # Detached (background)
agentum run "make build" -n build    # Named session

agentum list

Show active sessions.

agentum attach <id>

Attach to a session locally. Press Ctrl+] to detach.

agentum kill <id>

Stop a session.

agentum screenshot

Capture screen to disk.

agentum screenshot                # Saves to /tmp
agentum screenshot -o ./shots     # Custom directory

agentum notify

Push notification to phone.

agentum notify -t "Done" -b "Build complete"
agentum notify -t "Error" -b "Tests failed" -P high

Remote Access (Tailscale) - Highly Recommended

Access from anywhere, not just your local network. Works through firewalls and NATs.

Setup

1. Install Tailscale on desktop and phone
2. Sign in with same account on both
3. Start Tailscale:

   tailscale up
   

4. Connect from mobile:
   • IP/Host: Your Tailscale IP (tailscale ip -4) or MagicDNS hostname (e.g., your-desktop-name)
   • Port: 11042

Ports

Troubleshooting

Port in use?

agentum start --port 8080

Can't connect from phone?

• Same WiFi network?
• Firewall blocking port 11042?
• Try: ping <desktop-ip> from phone

Find your IP:

ifconfig | grep "inet "

Links

• Repository
• AirCodum

Windows and WSL desktop setup

Install normally with npm install -g agentum; Windows no longer needs --ignore-scripts. The platform-aware install step repairs node-pty’s helper only on macOS.

Run ag start from Windows PowerShell on the Windows computer or VM whose desktop you want to see. WSL/WSLg exposes Linux app windows rather than the host Windows desktop, so Agentum detects WSL, prints setup guidance and leaves desktop sharing off instead of showing a misleading black screen. Terminal sessions continue to work. To keep working inside WSL while viewing Windows, start Agentum on Windows and create a terminal session running wsl.exe.

This 1.0.3 maintenance release preserves the existing app connection protocol. It does not require the newer paired app/server release.