Locol Agent

Create instant HTTPS tunnels to your localhost for mobile testing

Locol makes it dead simple to preview your local development server on any device. No configuration, no account setup on the CLI - just run one command and get a secure HTTPS URL powered by Cloudflare.

Features

• 🚀 Instant HTTPS tunnels to your localhost
• 📱 Test on real devices - scan QR code and go
• 🔒 Secure by default - all tunnels use HTTPS
• 🌍 Share with anyone - teammates, clients, or just your phone
• 🆓 Free - powered by Cloudflare Quick Tunnels
• 🎯 Simple setup - one-time dev server configuration
• ⚡ HMR support - Hot Module Replacement works through tunnels
• 💡 Helpful error messages - clear guidance when things go wrong (v1.5+)

Installation

No installation needed! Just use npx:

npx @locol.dev/agent@latest <session_id> <secret> <port>

Or install globally if you prefer:

npm install -g @locol.dev/agent
locol <session_id> <secret> <port>

Prerequisites

1. Node.js

Version 18 or higher required.

2. Cloudflared

Install the Cloudflare tunnel client:

macOS:

brew install cloudflared

Linux (Debian/Ubuntu):

wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

Windows: Download from Cloudflare's releases page

Other platforms: See official installation guide

Quick Start

1. Get Your Tunnel Command

Go to your Locol dashboard and:

• Sign up or log in
• Click "New Tunnel"
• Enter your local port (e.g., 3000)
• Copy the generated command

2. Run the Command

The dashboard will give you a command like:

npx @locol.dev/agent@latest abc123-def456 your-secret-token 3000

Just paste and run it! Your localhost will be accessible via a public HTTPS URL.

3. Access Your App

• The tunnel URL appears in your terminal and dashboard
• Scan the QR code with your phone
• Share the URL with anyone

Dev Server Configuration

One-time setup: Modern dev servers need configuration to accept tunnel traffic.

Vite

Add to vite.config.js:

export default defineConfig({
  server: { host: true }
})

Or run: npm run dev -- --host

webpack Dev Server

Add to webpack.config.js:

module.exports = {
  devServer: { allowedHosts: 'all' }
}

Create React App

"start": "DANGEROUSLY_DISABLE_HOST_CHECK=true react-scripts start"

Next.js

Usually works without config! If needed: next dev -H 0.0.0.0

Why? Dev servers validate the Host header for security. This simple config allows tunnel access while keeping your dev server secure.

Environment Variables

The agent needs to connect to the Locol backend. You can provide credentials in three ways:

Option 1: Dashboard embeds them (Recommended)

The dashboard can generate a command with environment variables included:

SUPABASE_URL=https://xxx.supabase.co SUPABASE_ANON_KEY=yyy npx @locol.dev/agent session_id secret 3000

Option 2: Export globally

export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_ANON_KEY=your-anon-key
npx @locol/agent session_id secret 3000

Option 3: .env file

Create a .env file in your current directory:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

Then run:

npx @locol/agent session_id secret 3000

Usage

npx @locol.dev/agent@latest <session_id> <secret> <local_port>

Arguments

• session_id - Unique tunnel session ID from the dashboard
• secret - Secret token for authentication
• local_port - Your local dev server port (e.g., 3000, 8080)

Example

# Tunnel localhost:3000
npx @locol.dev/agent@latest abc123-def456 mysecret789 3000

The agent will:

1. ✓ Check that your local port is accessible
2. ✓ Validate your tunnel session
3. ✓ Check for cloudflared installation
4. ✓ Start a secure Cloudflare tunnel
5. ✓ Update the dashboard with your public URL
6. ✓ Keep the tunnel running until you press Ctrl+C

How It Works

1. Create tunnel session in the web dashboard
2. Run the agent with the provided command
3. Agent starts Cloudflare tunnel to your localhost
4. Dashboard updates in real-time with the public URL
5. Access from anywhere - phone, tablet, or share with teammates

All tunnels are:

• Secured with HTTPS
• Randomly generated subdomains
• Ephemeral (closed when agent stops)
• Free (powered by Cloudflare Quick Tunnels)

Troubleshooting

The agent now provides helpful error messages with actionable suggestions when things go wrong. Here are some common scenarios:

"Nothing is listening on localhost:PORT"

Cause: Your application isn't running on the specified port.

Solution: Start your app first, then run the tunnel command.

# Example: Start your app
npm run dev  # or npm start, yarn dev, etc.

# Then in another terminal, run the tunnel
npx @locol.dev/agent@latest ...

"Blocked request" errors

Cause: Your dev server is blocking tunnel requests.

Solution: Configure your dev server - see Dev Server Configuration above.

"Cloudflared is not installed"

Cause: The cloudflared command is not available.

Solution: Install cloudflared using the instructions in the Prerequisites section.

"Invalid tunnel credentials"

Cause: The session ID or secret is incorrect, or the tunnel has expired.

Solution:

1. Go to https://locol.dev
2. Create a new tunnel
3. Copy and use the fresh command

"Cannot connect to Locol servers"

Cause: Network connectivity issue.

Solution:

• Check your internet connection
• Verify you can access https://locol.dev in your browser
• Check if a firewall or VPN is blocking the connection
• Try again in a few moments

Getting More Help

v1.5+ Every error now includes specific suggestions for fixing the issue. Read the error message carefully - it will guide you to the solution.

For additional help:

• See ERROR_HANDLING_GUIDE.md for common error scenarios
• Check TEST_ERROR_HANDLING.md for testing guides
• Visit https://locol.dev/support for support options

Use Cases

• 📱 Mobile testing - Test responsive design on real devices
• 🤝 Client demos - Show work in progress without deploying
• 👥 Team collaboration - Share localhost with remote teammates
• 🔍 Device debugging - Test on specific browsers/devices
• 🎨 Design reviews - Get feedback on local builds
• 🌐 Webhook testing - Receive webhooks on your localhost

Security

• Tunnels are protected by unique session IDs and secrets
• Row-level security ensures you can only access your own tunnels
• Secrets are 64-character random tokens
• HTTPS encryption for all traffic
• Tunnels automatically close when the agent stops

Limits

Cloudflare Quick Tunnels are free but have some limitations:

• Tunnels are ephemeral (not persistent)
• Each tunnel gets a random subdomain
• Subject to Cloudflare's fair use policy

For production or persistent tunnels, consider Cloudflare Tunnel with a custom domain.

License

MIT

Links

• Dashboard
• Documentation
• Report Issues

Built with ❤️ for developers who need to test on real devices