@locol.dev/agent/README.md

Create instant HTTPS tunnels to your localhost for mobile testing via Cloudflare

# 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
- 🎯 **Zero config** - no account needed for the CLI

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

## 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. ✓ Validate your tunnel session
2. ✓ Check for `cloudflared` installation
3. ✓ Start a secure Cloudflare tunnel
4. ✓ Update the dashboard with your public URL
5. ✓ 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

### "cloudflared not found"

Install cloudflared using the instructions in the [Prerequisites](#prerequisites) section.

### "Missing Supabase environment variables"

Make sure you've set `SUPABASE_URL` and `SUPABASE_ANON_KEY`. See [Environment Variables](#environment-variables).

### "Invalid session ID or secret"

Double-check that you copied the complete command from the dashboard. The session ID and secret must match exactly.

### Port already in use

Make sure your local dev server is actually running on the port you specified.

### Tunnel not updating in dashboard

- Check that the Supabase credentials are correct
- Ensure the dashboard is open and connected
- Try refreshing the dashboard page

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