Skip to content

README.md

Latest commit

 

History

History
208 lines (155 loc) · 5.35 KB

README.md

File metadata and controls

208 lines (155 loc) · 5.35 KB

drok

Expose local ports to the internet with one command — powered by dynamoip and Cloudflare Tunnels.

drok http 3000
# => https://drok-a1b2c3.yourdomain.com → localhost:3000

No config files. No sudo. No ngrok accounts.

Prerequisites

  • Bun (v1.0+)
  • A domain managed by Cloudflare (free tier works)
  • A Cloudflare API token with:
    • Zone : DNS : Edit
    • Account : Cloudflare Tunnel : Edit
  • cloudflared (auto-installed on first run via Homebrew on macOS)

Create your Cloudflare API token

  1. Go to https://dash.cloudflare.com/profile/api-tokens
  2. Click Create Token
  3. Use Custom Token with these permissions:
    • Zone → DNS → Edit (scoped to your domain)
    • Account → Cloudflare Tunnel → Edit
  4. Copy the token — you'll need it for drok login

Install

# Clone and install
git clone <your-repo-url>
cd drok
bun install

# Link globally so `drok` is available everywhere
bun link

Quick Start

1. Login (one-time setup)

drok login

This prompts for:

  • Cloudflare API Token — the token you created above
  • Base domain — e.g. yourdomain.com
  • Email — optional, for Let's Encrypt notifications

Credentials are saved to ~/.drok/credentials.json (mode 0600). No files are created in your project.

2. Expose a port

# Start any local server first
# e.g. python3 -m http.server 3000

# Then expose it
drok http 3000

This will:

  1. Create/reuse a Cloudflare Tunnel
  2. Set a CNAME DNS record
  3. Start a local reverse proxy on 127.0.0.1:8080
  4. Print your live public URL

3. Test it

Open the printed URL (e.g. https://drok-a1b2c3.yourdomain.com) from any device — phone, another computer, anywhere.

Press Ctrl+C to stop.

Testing Locally (Step by Step)

Test 1: CLI runs

drok --help
drok http --help

Test 2: Login flow

drok login
# Enter your CF API token, domain, and optional email
# Should print: "Credentials saved to ~/.drok/credentials.json"

Test 3: Verify config

drok config
# Should show your domain and masked token

Test 4: Expose a port

# Terminal 1 — start a test server
python3 -m http.server 8000

# Terminal 2 — expose it
drok http 8000

You should see output like:

╭──────────────────────────────────╮
│  drok — exposing localhost:8000  │
╰──────────────────────────────────╯
  Domain : https://drok-a1b2c3.yourdomain.com
  Proxy  : http://127.0.0.1:8080

✔ cloudflared ready
✔ Tunnel ready
✔ DNS configured

╭─────────────────────────────────────────────────────────╮
│  ✨ Live on the internet!                               │
│                                                         │
│  https://drok-a1b2c3.yourdomain.com → localhost:8000    │
│                                                         │
│  Press Ctrl+C to stop.                                  │
╰─────────────────────────────────────────────────────────╯

Test 5: Custom subdomain

drok http 3000 --subdomain myapp
# => https://myapp.yourdomain.com

Test 6: Override domain

drok http 3000 --subdomain api --domain other.com
# => https://api.other.com

Test 7: Logout

drok logout
# Removes ~/.drok/credentials.json

Commands

Command Description
drok login Store Cloudflare credentials interactively
drok http <port> Expose a local port to the internet
drok config Show stored config (token masked)
drok logout Remove stored credentials

drok http options

Flag Short Description
--subdomain <name> -s Custom subdomain (default: random drok-XXXXXX)
--domain <domain> -d Override base domain from credentials
--proxy-port <port> -p Local proxy port (default: 8080)

How It Works

Browser → https://myapp.yourdomain.com
  → Cloudflare Edge (TLS termination)
  → cloudflared daemon (outbound tunnel on your machine)
  → http://127.0.0.1:8080 (drok proxy)
  → localhost:3000 (your app)
  • Uses Cloudflare Tunnel (Max mode) — no inbound ports, no firewall changes
  • Tunnel credentials cached in ~/.localmap/tunnels/ (reused across runs)
  • DNS CNAME records auto-managed via Cloudflare API

Project Structure

drok/
├── bin/drok.ts                 # Shebang entry point
├── src/
│   ├── index.ts                # CLI root (citty)
│   ├── commands/
│   │   ├── http.ts             # Tunnel orchestration
│   │   ├── login.ts            # Interactive credential setup
│   │   ├── logout.ts           # Remove credentials
│   │   └── config.ts           # Display config
│   └── lib/
│       ├── credentials.ts      # ~/.drok/ read/write
│       └── constants.ts        # Paths, defaults
├── package.json
└── tsconfig.json

License

MIT