Configuration

Complete reference for all CLI options, environment variables, and configuration files.

Configuration Precedence

When the same setting is available in multiple places, the following order applies (highest to lowest):

CLI arguments - Always take precedence
Environment variables - Override config files
Configuration files - Override defaults
Default values - Built-in fallbacks

bash

# CLI overrides env var
BROSKI_PORT=8080 broski --port 9090
# Result: Port 9090 is used

Quick Reference

Setting	CLI Flag	Env Variable	Default
Bridge Port	--port	BROSKI_PORT	18274
Tailscale Funnel	--funnel	BROSKI_ENABLE_FUNNEL=1	false
New Token	--new-token	-	false
Detect Hotspot	--hotspot	-	false
OpenCode URL	--opencode-url	OPENCODE_BASE_URL	-
OpenCode Hostname	--opencode-hostname	BROSKI_OPENCODE_HOSTNAME	127.0.0.1
OpenCode Port	--opencode-port	BROSKI_OPENCODE_PORT	0 (random)

CLI Options

Subcommands

broski (default)

Start the bridge server.

bash

broski [options]

broski install

Install as a background service that runs on login.

bash

broski install

Creates a LaunchAgent (macOS) or systemd service (Linux).

broski qr

Show the QR code to pair your phone (works with background service).

bash

broski qr
broski qr --hotspot  # Prioritize hotspot IP

broski doctor

Run diagnostics, apply safe fixes, and export support bundles.

bash

broski doctor
broski doctor --fix
broski doctor --profile pairing
broski doctor --export

Profiles: all, network, pairing, agents, daemon, security.

broski setup-tailscale

Interactive wizard to install and configure Tailscale for remote access.

bash

broski setup-tailscale

broski status / stop / uninstall

Manage the background service.

bash

broski status     # Check if running
broski stop       # Stop the service
broski uninstall  # Remove the service

Connection Options

--port <number>

Bridge WebSocket port number.

Default: 18274
Env: BROSKI_PORT
Special: 0 = random free port

bash

# Use custom port
broski --port 8080

# Use random available port
broski --port 0

--funnel

Enable Tailscale Funnel for public HTTPS access.

Requires: Tailscale connected, Funnel enabled in admin console
Env: BROSKI_ENABLE_FUNNEL=1

bash

broski --funnel

Creates a public HTTPS URL (e.g., https://machine.tailnet-name.ts.net). No VPN required on phone.

--new-token

Generate a new authentication token.

bash

# Generate new token (invalidates old QR codes)
broski --new-token

Use if you suspect your token has been compromised. New token is persisted to ~/.broski/token.json.

--hotspot

Detect and prioritize hotspot IP for mobile tethering.

bash

broski --hotspot
broski qr --hotspot

Useful when your phone is providing internet to your system via hotspot and you want to connect Broski over that same connection.

OpenCode Mode Options

Broski can connect to OpenCode in three modes:

--managed (default)

Let Broski start and manage an OpenCode server.

Broski starts OpenCode on a random port
Automatically restarts if OpenCode crashes
OpenCode stops when Broski stops

--manual

Connect to an existing OpenCode server (requires URL).

bash

# Manual mode with explicit URL
broski --manual --opencode-url http://localhost:4096

# Via environment variable
OPENCODE_BASE_URL=http://localhost:4096 broski

--attach

Scan for running OpenCode servers and interactively choose one.

bash

broski --attach

Scans common ports (4096, 64864-65119, 49152-49407). If multiple found, presents interactive selection menu.

Configuration Files

~/.broski/token.json

Persistent authentication state used for QR pairing and manual connection.

Property	Value
Format	JSON (version, token, createdAt, expiresAt, lastUsedAt)
Permissions	0600 (owner read/write only)
Token	Base64url random token
Created	Automatically on first run

Security

This file contains your auth token. Never share it or commit it to version control. To invalidate: run broski --new-token (or broski qr --new-token).

~/.broski/custom-tools.json

Custom tool definitions for Claude Code.

json

{
  "version": 1,
  "tools": [
    {
      "id": "tool_1234567890_abc123",
      "name": "my_custom_tool",
      "description": "Description of what the tool does",
      "parameters": [
        {
          "name": "input",
          "type": "string",
          "description": "Input parameter",
          "required": true
        }
      ],
      "handler": "http",
      "handlerConfig": {
        "url": "https://api.example.com/endpoint",
        "method": "POST"
      },
      "enabled": true
    }
  ]
}

~/.claude/settings.json

Claude CLI authentication (managed by claude login).

Broski checks this file if ANTHROPIC_API_KEY is not set.

Environment Variables

Bridge Variables

Variable	Type	Default	Description
BROSKI_PORT	number	18274	Bridge WebSocket port
BROSKI_ENABLE_FUNNEL	1 or unset	unset	Enable Tailscale Funnel

OpenCode Variables

Variable	Type	Default	Description
OPENCODE_BASE_URL	string	-	URL of existing OpenCode server
BROSKI_OPENCODE_HOSTNAME	string	127.0.0.1	Hostname for managed OpenCode
BROSKI_OPENCODE_PORT	number	0	Port for managed OpenCode (0 = random)

AI Provider Variables

Variable	Type	Description
ANTHROPIC_API_KEY	string	Anthropic API key for Claude Code
OPENAI_API_KEY	string	OpenAI API key for Codex/GPT models

Configuration Examples

Minimal Setup

bash

broski

Uses all defaults: port 18274, managed OpenCode, no funnel.

Custom Port

bash

broski --port 8080

Tailscale with Funnel

bash

broski --funnel

Public HTTPS access via Tailscale Funnel.

Manual OpenCode Connection

bash

# Start OpenCode separately
opencode serve --port 4096

# Connect Broski to it
broski --opencode-url http://localhost:4096

Claude Code Backend

bash

# With API key
export ANTHROPIC_API_KEY=sk-ant-api03-...
broski

# Or with Claude login
claude login
broski

Mobile Hotspot

bash

# When your phone provides internet to your system
broski --hotspot

Production Setup with Environment

bash

export BROSKI_PORT=18274
export BROSKI_ENABLE_FUNNEL=1
broski

Common Configuration Mistakes

Issue	Cause	Fix
Port in use	Another broski or process running	Kill process or use --port 0
Connection refused	Wrong OpenCode URL	Check URL with curl <url>/path
Auth failed	Invalid or old token	Use --new-token to regenerate
Funnel failed	Not enabled in admin console	Enable at login.tailscale.com/admin
Claude Code unavailable	Missing API key	Set ANTHROPIC_API_KEY or run claude login
QR code not scanning	Old QR after restart	Rescan the current QR code

Configuration

Configuration Precedence

Quick Reference

CLI Options

Subcommands

broski (default)

broski install

broski qr

broski doctor

broski setup-tailscale

broski status / stop / uninstall

Connection Options

--port <number>

--funnel

--new-token

--hotspot

OpenCode Mode Options

--managed (default)

--manual

--attach

Configuration Files

~/.broski/token.json

~/.broski/custom-tools.json

~/.claude/settings.json

Environment Variables

Bridge Variables

OpenCode Variables

AI Provider Variables

Configuration Examples

Minimal Setup

Custom Port

Tailscale with Funnel

Manual OpenCode Connection

Claude Code Backend

Mobile Hotspot

Production Setup with Environment

Common Configuration Mistakes

Next Steps

Remote Access

Background Service