Remote Servers

Run cli4ai tools on remote machines. Perfect for accessing tools on other computers, servers, or headless instances.

Overview

cli4ai can run as a remote service, allowing you to:

  • Execute tools on a different machine from where you're working
  • Access browser automation tools running on a headed machine
  • Share tool installations across multiple computers
  • Run tools on cloud servers or VMs

Quick Start

1. Start the server

On the machine with the tools installed:

cli4ai serve

This starts an HTTP server on port 4100 by default.

2. Add the remote

On your local machine:

cli4ai remotes add my-server http://192.168.1.100:4100

3. Run commands remotely

# Run a tool on the remote server
cli4ai run --remote my-server github notifs

# List packages on the remote
cli4ai list --remote my-server

# Get package info from remote
cli4ai info --remote my-server twitter

Server Commands

Command Description
cli4ai serve Start server on port 4100
cli4ai serve --port 8080 Start on custom port
cli4ai serve --api-key SECRET Require API key authentication
cli4ai serve --scope read,write Restrict to specific scopes

Remote Management Commands

Command Description
cli4ai remotes add <name> <url> Add a remote server
cli4ai remotes list List configured remotes
cli4ai remotes remove <name> Remove a remote
cli4ai remotes test <name> Test connection to remote
cli4ai remotes show <name> Show remote details

Remote Operations

Most commands support the --remote flag:

Command Description
cli4ai run --remote <name> <pkg> <cmd> Run tool on remote
cli4ai list --remote <name> List packages on remote
cli4ai info --remote <name> <pkg> Get package info from remote
cli4ai search --remote <name> <query> Search packages on remote

Authentication

For production use, always enable API key authentication:

# On the server
cli4ai serve --api-key mysecretkey

# When adding the remote
cli4ai remotes add my-server http://192.168.1.100:4100 --api-key mysecretkey

API Endpoints

The serve command exposes a REST API:

Endpoint Description
GET /health Service health check
GET /packages List available packages
GET /packages/:name Get package info
POST /run Execute a tool
POST /routines/:name/run Run a routine

Example: Browser Automation

Remote servers are especially useful for browser automation. Run Chrome on a headed machine and control it from anywhere:

# On the machine with a display (e.g., Mac mini)
cli4ai add -g chrome twitter
cli4ai serve

# From your laptop
cli4ai remotes add mac-mini http://192.168.1.50:4100

# Launch Chrome and use Twitter automation
cli4ai run --remote mac-mini chrome launch
cli4ai run --remote mac-mini twitter trends
cli4ai run --remote mac-mini twitter timeline

Using with Tailscale

Tailscale makes remote servers incredibly easy to set up. It creates a private network between your devices with zero configuration:

# On your Mac mini (server)
cli4ai serve

# From your laptop (anywhere in the world)
cli4ai remotes add mac-mini http://100.x.x.x:4100

Benefits of using Tailscale:

  • No port forwarding - Works through NAT and firewalls
  • Encrypted by default - All traffic is end-to-end encrypted
  • Access from anywhere - Use the same IP from home, office, or mobile
  • MagicDNS - Use names like mac-mini.tailnet instead of IPs
# With MagicDNS enabled
cli4ai remotes add mac-mini http://mac-mini:4100

Security Considerations

  • Use Tailscale or VPN for secure access over the internet
  • Use API keys in production environments
  • Restrict scopes to limit what operations can be performed
  • Firewall the port if only accessing from specific IPs

Next Steps