@liveport/cli

Secure localhost tunnels for AI agents

Command-line interface for creating secure, temporary tunnels to expose your localhost to the internet. Built specifically for AI agents and developers who need to test webhooks, share local demos, or enable AI agents to access local development servers.

Features

• 🚀 Instant Tunnels - Expose localhost with a single command
• 🔐 Secure by Default - Bridge key authentication with expiration and rate limits
• 🤖 AI Agent Ready - First-class support for AI agents via the Agent SDK
• ⚡ Zero Configuration - Works out of the box, configure only what you need
• 🌍 Global Edge Network - Low-latency tunnels from anywhere
• 📊 Real-time Logs - See incoming requests as they happen
• 💾 Persistent Config - Save your bridge key for quick access

Installation

npm

npm install -g @liveport/cli

pnpm

pnpm add -g @liveport/cli

npx (no installation)

npx @liveport/cli connect 3000

Requirements

• Node.js 18.0.0 or higher
• A LivePort account (Sign up free)

Quick Start

1. Get Your Bridge Key

Visit liveport.dev/keys to create a bridge key. You'll see something like:

lpk_abc123def456ghi789jkl012mno345

⚠️ Important: Copy this key immediately - it's only shown once!

2. Save Your Key (Recommended)

liveport config set key lpk_abc123def456ghi789jkl012mno345

3. Start a Tunnel

# Expose your local server on port 3000
liveport connect 3000

You'll see:

  ╦  ╦╦  ╦╔═╗╔═╗╔═╗╦═╗╔╦╗
  ║  ║╚╗╔╝║╣ ╠═╝║ ║╠╦╝ ║
  ╩═╝╩ ╚╝ ╚═╝╩  ╚═╝╩╚═ ╩

  Secure localhost tunnels for AI agents

✓ Tunnel established!

Public URL: https://swift-fox-a7x2.liveport.online
Forwarding: → http://localhost:3000

Press Ctrl+C to disconnect

Your local server is now accessible at the public URL! 🎉

Commands

liveport connect <port>

Create a tunnel to expose a local port to the internet.

Arguments:

• <port> - Local port to expose (1-65535)

Options:

• -k, --key <key> - Bridge key for authentication
• -s, --server <url> - Tunnel server URL (default: https://tunnel.liveport.dev)
• -r, --region <region> - Server region (coming soon)
• --name <name> - Custom tunnel name (coming soon)

Examples:

# Basic usage (requires saved config)
liveport connect 3000

# With explicit key
liveport connect 8080 --key lpk_abc123...

# Custom server
liveport connect 3000 --server https://custom.tunnel.server

# Using environment variable
LIVEPORT_KEY=lpk_abc123... liveport connect 3000

What it does:

1. Establishes a secure WebSocket connection to the tunnel server
2. Receives a unique public URL (e.g., https://swift-fox-a7x2.liveport.online)
3. Proxies all incoming HTTP requests to your local port
4. Displays real-time request logs
5. Maintains connection with automatic reconnection

liveport status

Show current tunnel status and connection details.

Output:

liveport status

Tunnel Status
──────────────────────────────
  Status: Connected
  Public URL: https://swift-fox-a7x2.liveport.online
  Local Port: 3000
  Requests: 42
  Connected: 5 minutes ago

liveport disconnect

Disconnect the active tunnel.

Options:

• -a, --all - Disconnect all tunnels (when multiple tunnels supported)

Example:

liveport disconnect

liveport config

Manage CLI configuration stored at ~/.liveport/config.json.

config set <key> <value>

Set a configuration value.

Valid keys:

• key - Your bridge key
• server - Default tunnel server URL

Examples:

# Set bridge key
liveport config set key lpk_abc123def456ghi789jkl012mno345

# Set custom server
liveport config set server https://tunnel.liveport.dev

config get <key>

Get a specific configuration value.

Example:

liveport config get key
# Output: key: lpk_abc12...mno345 (masked for security)

config list

List all configuration values.

Example:

liveport config list

Configuration
────────────────────────────────────────
  Config file: /Users/you/.liveport/config.json

  key: lpk_abc12...mno345
  server: https://tunnel.liveport.dev

config delete <key>

Delete a configuration value.

Example:

liveport config delete key

liveport --version

Display the CLI version.

liveport --help

Show help information for all commands.

Authentication

LivePort uses bridge keys for authentication. Bridge keys are cryptographically secure tokens that:

• Authenticate your tunnels
• Control access and permissions
• Support expiration dates
• Can limit usage (max requests)
• Can restrict to specific ports

Authentication Priority (highest to lowest):

1. --key flag - Passed directly to the command
2. LIVEPORT_KEY environment variable - Set in your shell
3. Config file - Saved via liveport config set key

Get a Bridge Key

1. Visit liveport.dev/keys
2. Click "Create Bridge Key"
3. Configure:
   • Name: Describe where you'll use it (e.g., "Development", "CI/CD")
   • Expires: Optional expiration (e.g., 30 days)
   • Max Uses: Optional usage limit
4. Copy the key immediately (shown only once!)

Managing Keys

You can have multiple bridge keys for different purposes:

• Development - Long-lived key for daily work
• CI/CD - Short-lived key with usage limits
• Demos - Single-use keys that expire quickly
• AI Agents - Dedicated keys per agent/project

Configuration

Config File Location

Configuration is stored in JSON format at:

• macOS/Linux: ~/.liveport/config.json
• Windows: %USERPROFILE%\.liveport\config.json

Config File Format

{
  "key": "lpk_abc123def456ghi789jkl012mno345",
  "server": "https://tunnel.liveport.dev"
}

Environment Variables

All configuration can be overridden with environment variables:

• LIVEPORT_KEY - Bridge key
• LIVEPORT_SERVER_URL - Tunnel server URL

Example:

export LIVEPORT_KEY=lpk_abc123def456ghi789jkl012mno345
liveport connect 3000

Use Cases

1. Test Webhooks Locally

# Start your local webhook server
node webhook-server.js

# Expose it via LivePort
liveport connect 3000

# Use the public URL in your webhook provider
# https://swift-fox-a7x2.liveport.online/webhooks

2. Share Local Development

# Start your dev server
npm run dev

# Create a tunnel
liveport connect 5173

# Share the URL with your team
# https://swift-fox-a7x2.liveport.online

3. Enable AI Agents

# Start your local API
python manage.py runserver 8000

# Expose it for AI agents
liveport connect 8000

# AI agents can now discover and access your API
# using the LivePort Agent SDK

4. Test Mobile Apps

# Start your API server
rails server -p 3000

# Create tunnel
liveport connect 3000

# Configure mobile app to use public URL
# https://swift-fox-a7x2.liveport.online/api

5. CI/CD Integration

# .github/workflows/e2e-tests.yml
- name: Install LivePort CLI
  run: npm install -g @liveport/cli

- name: Start local server
  run: npm run dev &

- name: Create tunnel
  run: liveport connect 3000 --key ${{ secrets.LIVEPORT_KEY }}

- name: Run E2E tests
  run: npm run test:e2e

Troubleshooting

"Bridge key required"

Problem: No bridge key provided.

Solutions:

1. Set via config: liveport config set key lpk_...
2. Use environment variable: export LIVEPORT_KEY=lpk_...
3. Pass via flag: liveport connect 3000 --key lpk_...

"Connection failed"

Problem: Cannot connect to tunnel server.

Check:

1. Internet connection is working
2. Firewall allows WebSocket connections
3. Server URL is correct: liveport config get server

"Port already in use"

Problem: Local port is not running or accessible.

Solutions:

1. Verify your local server is running on the specified port
2. Check localhost:<port> in your browser
3. Try a different port

"Invalid bridge key"

Problem: Bridge key is incorrect, expired, or revoked.

Solutions:

1. Check the key format starts with lpk_
2. Verify key hasn't expired at liveport.dev/keys
3. Create a new bridge key if needed

Tunnel disconnects frequently

Problem: Connection is unstable.

Try:

1. Check your network connection
2. Look for firewall/VPN interference
3. Contact support if issue persists

Security Best Practices

✅ Do's

• Rotate keys regularly - Create new keys periodically
• Use expiration dates - Set keys to expire after a specific time
• Limit key scope - Create separate keys for different projects
• Revoke unused keys - Delete keys you no longer need
• Use environment variables in CI/CD - Never commit keys to git

❌ Don'ts

• Don't commit keys to git - Add .env to .gitignore
• Don't share keys publicly - Keep keys private
• Don't use production keys in development - Separate environments
• Don't expose sensitive endpoints - Only tunnel what's needed
• Don't ignore expiration - Set reasonable expiration dates

Advanced Usage

Multiple Tunnels (Coming Soon)

# Start multiple tunnels simultaneously
liveport connect 3000 --name api
liveport connect 3001 --name web
liveport connect 5432 --name database

Custom Subdomains (Coming Soon)

# Request specific subdomain
liveport connect 3000 --subdomain my-app
# https://my-app.liveport.online

Regional Servers (Coming Soon)

# Connect to regional server for lower latency
liveport connect 3000 --region us-west

Programmatic Usage

While this is a CLI tool, you can also use it programmatically:

import { TunnelClient } from '@liveport/cli';

const client = new TunnelClient({
  serverUrl: 'https://tunnel.liveport.dev',
  bridgeKey: 'lpk_abc123...',
  localPort: 3000,
});

client.on('connected', (info) => {
  console.log('Tunnel URL:', info.url);
});

client.on('request', (method, path) => {
  console.log(`${method} ${path}`);
});

await client.connect();

Related Packages

• @liveport/agent-sdk - SDK for AI agents to discover and use tunnels
• Dashboard - Web interface for managing keys and tunnels

Resources

• Documentation: liveport.dev/docs
• API Reference: liveport.dev/docs
• Dashboard: liveport.dev/dashboard
• Support: GitHub Issues
• Website: liveport.dev

Contributing

Contributions are welcome! Please read our Contributing Guide first.

License

MIT © LivePort

Made with ❤️ for developers and AI agents