npm package: @locol.dev/agent
Description: Create instant HTTPS tunnels to your localhost for mobile testing via Cloudflare
Latest version: 1.5.2

# 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 <session_id> <secret> <port>
```

Or install globally if you prefer:

```bash
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:**
```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](https://github.com/cloudflare/cloudflared/releases)

**Other platforms:**
See [official installation guide](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/)

## Quick Start

### 1. Get Your Tunnel Command

Go to [your Locol dashboard](https://your-app-url.com) 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:

```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. 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`:
```js
export default defineConfig({
  server: { host: true }
})
```
Or run: `npm run dev -- --host`

### webpack Dev Server
Add to `webpack.config.js`:
```js
module.exports = {
  devServer: { allowedHosts: 'all' }
}
```

### Create React App
```json
"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:

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

### Option 2: Export globally

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

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

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

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

### "Blocked request" errors

**Cause:** Your dev server is blocking tunnel requests.

**Solution:** Configure your dev server - see [Dev Server Configuration](#dev-server-configuration) above.

### "Cloudflared is not installed"

**Cause:** The `cloudflared` command is not available.

**Solution:** Install cloudflared using the instructions in the [Prerequisites](#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](./ERROR_HANDLING_GUIDE.md) for common error scenarios
- Check [TEST_ERROR_HANDLING.md](./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](https://your-app-url.com)
- [Documentation](https://github.com/yourusername/locol-v2)
- [Report Issues](https://github.com/yourusername/locol-v2/issues)

---

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