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:

``bash npx @locol.dev/agent@latest`

Or install globally if you prefer:

`bash npm install -g @locol.dev/agent locol`

`Prerequisites`

`$3`


Version 18 or higher required.
$3

Install the Cloudflare tunnel client:

macOS:`bash brew install cloudflared`

Linux (Debian/Ubuntu):`bash 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`

`$3`

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

`$3`

The dashboard will give you a command like:

`bash 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`

- 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.

`$3`


Add to

vite.config.js

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


Or run:

npm run dev -- --host


$3

Add to

webpack.config.js

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

$3

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


$3

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:

`$3`

The dashboard can generate a command with environment variables included:

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

`$3`

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

`$3`

Create a .env file in your current directory:

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

Then run:

`bash npx @locol/agent session_id secret 3000`

`Usage`

`bash npx @locol.dev/agent@latest`

`$3`

- 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)

`$3`

`bash

`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 forcloudflaredinstallation 4. ✓ Start a secure Cloudflare tunnel 5. ✓ Update the dashboard with your public URL 6. ✓ Keep the tunnel running until you pressCtrl+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:

`$3`

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

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

`bash

`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 ...


$3
Cause: Your dev server is blocking tunnel requests.
Solution: Configure your dev server - see Dev Server Configuration above.
$3

Cause: The cloudflared` command is not available.

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

$3

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

$3

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

$3

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

Locol Agent

> Create instant HTTPS tunnels to your localhost for mobile testing

Features

Installation

No installation needed! Just use npx:

``bash npx @locol.dev/agent@latest`

Or install globally if you prefer:

`bash npm install -g @locol.dev/agent locol`

`Prerequisites`

`$3`


Version 18 or higher required.
$3

Install the Cloudflare tunnel client:

macOS:`bash brew install cloudflared`

Linux (Debian/Ubuntu):`bash 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`

`$3`

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

`$3`

The dashboard will give you a command like:

`bash 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`

- 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.

`$3`


Add to

vite.config.js

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


Or run:

npm run dev -- --host


$3

Add to

webpack.config.js

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

$3

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


$3

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:

`$3`

The dashboard can generate a command with environment variables included:

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

`$3`

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

`$3`

Create a .env file in your current directory:

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

Then run:

`bash npx @locol/agent session_id secret 3000`

`Usage`

`bash npx @locol.dev/agent@latest`

`$3`

- 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)

`$3`

`bash

`Tunnel localhost:3000`


npx @locol.dev/agent@latest abc123-def456 mysecret789 3000

`How It Works`

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:

`$3`

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

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

`bash

`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 ...


$3
Cause: Your dev server is blocking tunnel requests.
Solution: Configure your dev server - see Dev Server Configuration above.
$3

Cause: The cloudflared` command is not available.

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

$3

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

$3

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

$3

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

Security

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