Mirror terminal sessions and AI coding agents to mobile over WebSocket
npm install agentumControl AI coding agents from your phone. Mirror Claude Code, GitHub Copilot, and OpenAI Codex to mobile - code from your couch, bed, or anywhere.
``
┌──────────────┐ WebSocket ┌──────────────┐
│ Your Phone │ ◄────────────────► │ Desktop │
│ (Agentum │ │(agentum start)│
│ Mobile) │ │ │
└──────────────┘ └──────────────┘
│
┌──────┴──────┐
│ AI Agents │
│ Claude Code │
│ Copilot │
│ Codex │
└─────────────┘
You need Node.js (v18+) installed. Then, install and authenticate the AI agents you want to control:
| Agent | Install | Login |
|-------|---------|-------|
| Claude Code | npm install -g @anthropic-ai/claude-code | claude (follow prompts) |gh extension install github/gh-copilot
| GitHub Copilot | | gh auth login |npm install -g @openai/codex
| OpenAI Codex | | codex (follow prompts) |
Only install and authenticate the agents you plan to use.
---
`bash`
npm install -g agentum
`bash`
npx agentum start
This shows your connection info:
`
Terminal server started on port 11042
Connect from mobile using IP:
`bashmacOS/Linux
ifconfig | grep "inet " | grep -v 127.0.0.1
$3
| Platform | Status |
|----------|--------|
| iOS | iOS link |
| Android | Coming soon |
$3
Open the mobile app and enter:
- IP/Host: Your desktop's IP address
- Port:
(default)That's it! Your AI agents now stream to your phone.
---
Commands
$3
Start the server. Run this first.
`bash
agentum start # Default: port 11042
agentum start --port 8080 # Custom port
agentum start --no-vnc # Disable screen sharing
`$3
Run any command and mirror output to mobile.
bash
agentum run "npm test"
agentum run "python train.py" -d # Detached (background)
agentum run "make build" -n build # Named session
`$3
Show active sessions.
$3
Attach to a session locally. Press
to detach.$3
Stop a session.
$3
Capture screen to disk.
`bash
agentum screenshot # Saves to /tmp
agentum screenshot -o ./shots # Custom directory
`$3
Push notification to phone.
bash
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.
$3
1. Install Tailscale on desktop and phone
2. Sign in with same account on both
3. Start Tailscale:
bash
tailscale up
`
4. Connect from mobile:
- IP/Host: Your Tailscale IP () or MagicDNS hostname (e.g., your-desktop-name)
- Port: 11042---
Ports
| Port | Service | Description |
|-------|-----------|--------------------------|
| 11042 | WebSocket | Mobile ↔ Desktop |
| 11043 | VNC | Screen sharing (optional)|
---
---
Troubleshooting
Port in use?
bash
agentum start --port 8080
`Can't connect from phone?
- Same WiFi network?
- Firewall blocking port 11042?
- Try:
from phoneFind your IP:
`bash
ifconfig | grep "inet "
``---