Tinyagent

Connect your local shell to any device - access your dev environment from anywhere.

Installation

npm install -g tinyagent

Quick Start

1. Start tinyagent (auto-generates session ID):

tinyagent

Or specify your own session ID:

tinyagent my-session

2. Scan the QR code with the Tinyagent mobile app OR enter the session ID manually

3. Your local terminal is now accessible from your phone!

Bonus: If you have Claude CLI installed, it will automatically start Claude for you! Claude will be able to see and interact with your terminal session.

Features

• 🔐 Secure WebSocket connection through relay servers
• 📱 Full terminal access from mobile devices
• 🌐 HTTP tunneling - access your local dev servers from anywhere
• ⌨️ Bidirectional typing - type from computer or phone
• 📏 Smart terminal resizing based on device
• 🚀 Zero configuration required

Usage

Basic connection (auto-generates session ID):

tinyagent

Connect with specific session ID:

tinyagent my-session
# or
tinyagent --session-id my-session

Use a custom relay server:

tinyagent --relay ws://localhost:8080

Specify a custom shell:

tinyagent --shell /bin/zsh

Disable Claude auto-start:

tinyagent --no-claude

Advanced: Run a server alongside your shell

tinyagent -c "npm run dev" -p 3000

This runs a dev server in parallel with your shell session (legacy feature - HTTP tunneling now auto-detects running servers).

All Options:

• [sessionId] - Session ID as first argument (optional, auto-generated if not provided)
• --session-id <id> - Session ID (alternative to positional argument)
• -r, --relay <url> - Relay server URL (default: wss://relay.tinyagent.app)
• -s, --shell <shell> - Shell to use (default: $SHELL or /bin/bash)
• -c, --command <cmd> - Run a server command in parallel (legacy - auto-detection preferred)
• -p, --port <port> - Port for the server command (default: 3000)
• --no-tunnel - Disable localtunnel integration
• --no-claude - Do not auto-start Claude CLI
• -v, --verbose - Show detailed debug output
• -V, --version - Show version number
• -h, --help - Show help

HTTP Tunneling

Tinyagent automatically detects and exposes your local development servers! No configuration needed.

When you have servers running on common ports (3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 9000), you'll see:

[HTTP] Exposing ports: 3000, 5173
[HTTP] Access your dev server at:
  https://my-session-3000.tinyagent.app/
  https://my-session-5173.tinyagent.app/

Access your local dev servers from any browser - perfect for testing on mobile devices!

Environment Variables

You can set these environment variables to customize default behavior:

• RELAY_URL - Default relay server URL (instead of using -r flag each time)
• SHELL - Default shell to use (automatically detected from your system)

Example:

export RELAY_URL=ws://localhost:8080
tinyagent

Security

• All connections are routed through relay servers - your machine is never directly exposed
• Session IDs are private - only those with the ID can connect
• Connections are encrypted with WSS (WebSocket Secure)

Troubleshooting

Debug Mode

If you're experiencing issues, run with verbose output:

tinyagent -v
# or
tinyagent --verbose

This will show:

• WebSocket connection details
• Terminal resize events
• Input source tracking (local vs mobile)
• HTTP port detection

Common Issues

Claude not starting automatically?

• Make sure Claude CLI is installed and in your PATH
• Try running which claude to verify installation
• Use --no-claude to disable auto-start

Dev server not accessible?

• Ensure your server is running on a standard port (3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 9000)
• Check that the server is bound to localhost or 0.0.0.0, not just 127.0.0.1
• Look for the [HTTP] Exposing ports: message in the output

Learn More

• Website: https://tinyagent.app
• Documentation: https://docs.tinyagent.app
• Mobile App: Available on App Store and Google Play

License

MIT