Frequently Asked Questions

What is Broski?

Broski is a mobile companion app that turns your phone into a remote control for AI coding agents. It connects to Claude Code, OpenCode, or Codex running on your system, letting you chat with AI, view code changes, and approve actions from anywhere.

How much does Broski cost?

Broski requires a subscription. The app is free to download, but a subscription is required to use it. You'll also need your own AI provider subscription (Claude Pro, OpenAI API key, etc.) configured in your AI backend — Broski doesn't handle AI authentication.

What platforms does Broski support?

Mobile: iOS 15+ and Android 8+

Bridge Server: macOS 12+, Windows 10+ (WSL2), Linux (Ubuntu 20.04+)

Do I need a computer to use Broski?

Yes. Broski is a companion app - the AI coding agent runs on your computer, and Broski provides a mobile interface to interact with it. Your computer needs to be running the bridge server for Broski to work.

How does Broski work?

Broski uses a three-part architecture:

1. Phone App - Displays UI, captures input
2. Bridge Server - Runs on your system, translates messages
3. AI Backend - Does reasoning, executes tools

What do I need to get started?

• • A Mac, Windows PC, or Linux machine
• • Broski bridge installed on your computer
• • Claude Code, OpenCode, or Codex CLI installed
• • An AI provider account (Claude, OpenAI, etc.)
• • An iPhone/iPad (iOS 15+) or Android device (8.0+)
• • Same WiFi network OR Tailscale for remote access

How do I install the bridge?

Run one of these commands in your terminal:

broski

This starts the bridge server and displays a QR code to pair with your phone.

Can I use Broski on multiple computers?

Yes, but one bridge instance connects to one AI backend at a time. Install the bridge on each computer, and scan the QR code for whichever computer you want to connect to. Sessions are stored per-computer.

Why can't I scan the QR code?

• • Make sure your phone and system are on the same WiFi network
• • Check that the bridge is still running in your terminal
• • Try increasing terminal brightness
• • Move closer to the screen for better camera focus
• • Use "Enter manually" and type the IP address

How do I update Broski?

Bridge: Download and install the latest version for your platform.

App: Update from App Store (iOS) or Play Store (Android).

Do I need to be on the same WiFi?

For local connections, yes. For remote access from anywhere, set up Tailscale (free) on both your computer and phone - then you can use Broski from any location.

Can multiple phones connect to the same bridge?

Yes! Multiple devices can connect simultaneously. Each phone registers with a unique ID, and all phones see the same sessions and projects. Messages from any phone go to the same AI.

Can I use Broski over cellular data?

Yes, but you need Tailscale or Funnel for remote access. Local IPs (192.168.x.x) won't work on cellular - you need Tailscale IPs (100.x.x.x) or a Funnel URL. Data usage is light (1-50 KB per message).

What is Tailscale and why do I need it?

Tailscale is a free VPN that creates a secure connection between your devices. Without it, you can only use Broski when connected to the same WiFi as your system. With Tailscale, you can use Broski from a coffee shop, airport, or anywhere in the world.

What is Funnel?

Tailscale Funnel exposes your bridge to the internet via a public HTTPS URL. This lets you connect without installing Tailscale on your phone - just use the URL. Enable with: broski --funnel

Why does my connection keep dropping?

• • Check your WiFi signal strength
• • The bridge may have crashed - restart it
• • Keep the app in foreground (mobile OSes kill background apps)
• • If using Tailscale, verify both devices are connected
• • On Android, disable battery optimization for Broski

Why does the connection drop when I leave my house?

Your local IP (192.168.x.x) only works on your home WiFi. When you leave, that IP becomes unreachable. Set up Tailscale to get a stable IP that works everywhere, or enable Funnel for a public URL.

What do the connection bars mean?

What's the difference between OpenCode and Claude Code?

Can I switch between backends?

Yes! Go to Settings > AI Backend in the app to switch between Claude Code, OpenCode, and Codex. The bridge will reconnect with the selected backend. Note that sessions are per-backend - they don't transfer.

Are my sessions shared between backends?

No - each backend maintains separate session storage. OpenCode sessions are in~/.opencode/, Claude Code sessions are stored separately. Switching backends shows different sessions.

Can I use local/self-hosted models?

Yes, if you use OpenCode with Ollama or similar local inference. Install Ollama, pull a model (ollama pull llama3), configure OpenCode to use it, and Broski will work with the local model.

How do I configure my API key?

API keys are configured in OpenCode/Claude Code, not in Broski. Set environment variables like ANTHROPIC_API_KEY or useclaude login for Claude Code.

What can I do with Broski?

• • Chat with AI in real-time with streaming responses
• • Review code diffs before they're applied
• • Approve or reject file changes and commands
• • Switch between projects and sessions
• • Browse files and search your codebase
• • View AI thinking and tool execution
• • Attach images to your conversations
• • Fork, share, and manage sessions

Can I use Broski offline?

Partially. You can view cached sessions and messages offline, but you need an active connection to the bridge to send new messages or interact with AI.

How do I attach images to messages?

Tap the attachment button in the chat input bar. You can take a photo or select from your photo library. The AI can analyze images and use them as context for your requests.

What happens to my sessions when I disconnect?

Sessions persist on your computer - they're not stored on your phone. When you reconnect, all sessions reload from your system. Any in-progress AI responses will have completed (or failed). Recent messages are cached for offline viewing.

Why do I need to approve permissions?

Some AI actions are potentially dangerous (running commands, editing files, deleting things). Broski requires your explicit approval for these actions. This is a safety feature - the AI can't do anything destructive without your permission.

Can I always allow certain tools?

Yes! Go to Settings > Tools and toggle "Always Allow" for specific tools. Read is usually safe to always allow. Edit and Bash are better to approve each time.

Can I run the bridge as a background service?

Yes! Use launchd (macOS), systemd (Linux), or Task Scheduler (Windows).

See the Background Service Guide for instructions.

How do I use a custom port?

# Use --port flag
broski --port 8080

# Or set environment variable
BROSKI_PORT=8080 broski

Note: Changing the port invalidates existing QR codes - scan the new one.

Can I configure the bridge with environment variables?

Yes! All CLI options have environment variable equivalents:

• • BROSKI_PORT - Port number
• • BROSKI_ENABLE_FUNNEL - Enable Tailscale Funnel
• • OPENCODE_BASE_URL - OpenCode server URL

How do I reset everything and start fresh?

# Clear bridge data
rm -rf ~/.broski

# Clear OpenCode data (deletes all sessions!)
rm -rf ~/.opencode

On your phone: Settings > Clear Cache, or uninstall and reinstall the app.

Does Broski send my code to the cloud?

No. Your code stays on your system at all times. When you chat with AI, your prompts are sent to your configured AI provider (Anthropic, OpenAI, etc.) by the agent running on your system — exactly the same as if you used Claude Code or OpenCode directly in your terminal. Broski doesn't add, intercept, or route anything through our servers. We don't operate servers that touch your code.

Is my connection encrypted?

Yes, always. The encryption depends on your connection type:

• • Local WiFi: TLS with certificate pinning. The bridge generates a self-signed cert, and your phone pins the SHA-256 fingerprint from the QR code. Even on untrusted WiFi, a man-in-the-middle attack is blocked.
• • Tailscale: WireGuard end-to-end encryption. Modern, audited cryptographic protocol — traffic is encrypted directly between your devices.
• • Funnel: HTTPS/TLS managed by Tailscale. Public endpoint with TLS termination at their edge.

Does Broski collect analytics or telemetry?

Zero. Not “minimal” or “anonymous” — zero. There is no Firebase, no Mixpanel, no Amplitude, no Sentry, no Crashlytics, no Segment in the app or bridge. We don't track screen views, tap events, session duration, or any behavioral data. If the app crashes, we don't know unless you email us. Our revenue comes from subscriptions, not data.

Where is my data stored?

• • Connection credentials: Encrypted in iOS Keychain (hardware-backed) / Android EncryptedSharedPreferences (AES-256)
• • Cached sessions & messages: On your phone only, in encrypted storage. For offline viewing.
• • AI conversations & session history: On your computer only, managed by the AI backend.
• • API keys: On your system only, in the OS keychain (macOS Keychain / Windows Credential Manager / Linux keyring) or local config files. Never sent through Broski.
• • Bridge auth token & TLS cert: In ~/.broski/ on your system with restricted file permissions.

Can someone else access my bridge?

Not without your authentication token. The bridge generates a cryptographically secure token with 192 bits of entropy, embedded in the QR code. Connections are validated using constant-time comparison to prevent timing attacks. Without the token, the bridge rejects the connection at the HTTP level — before a WebSocket is even established. To revoke access: broski --new-token

What third-party services does Broski use?

Exactly two:

• • Authentication (Google/Apple Sign-In): Standard OAuth 2.0 for identity. Receives your name and email only — never code, conversations, or usage data.
• • Subscription (RevenueCat): Purchase verification via Apple/Google APIs. Receives transaction data and subscription status only — never code, conversations, or usage data.

If you enable voice input, audio goes to Groq or OpenAI using your own API key. This is opt-in and off by default.

What happens if I cancel my subscription?

Your pairing data is preserved. If you resubscribe later, the app reconnects to your system automatically — no QR rescan needed. We don't delete your data or hold it hostage when you leave.

How do I delete all my data?

Phone: Settings > Clear Cache removes all cached data. Uninstalling the app removes everything from your device.

System: Delete ~/.broski to remove all bridge data (token, certs, config).

That's it. There's nothing on our end to delete because we never had your data in the first place.

Can I verify all of this myself?

Yes. Run broski doctor to run 30+ diagnostics on your setup (TLS certs, token status, port bindings, daemon health). Use Wireshark to inspect network traffic — you'll see encrypted WebSocket frames between your phone and Mac, and nothing going to any Broski endpoint. The bridge runs on your machine; you can inspect every line of traffic.

For the full deep-dive, see our Security & Privacy documentation.

The bridge says "Port already in use"

# Find what's using the port
lsof -nP -iTCP:18274 -sTCP:LISTEN

# Kill it
kill <PID>

# Or use a different port
broski --port 8080

The app says "Unauthorized"

The authentication token doesn't match. This happens if you restarted the bridge with --new-token or the bridge crashed. Rescan the QR code from the terminal.

The chat is stuck on "busy"

The session is stuck. Try:

1. Tap the stop button in the chat
2. Pull down to refresh the session list
3. Restart the bridge (Ctrl+C, then broski)

OpenCode won't start

# Check if installed
which opencode

# If not found, install it
curl -fsSL https://opencode.ai/install | bash
# or: bun add -g opencode-ai

# Try manual mode
opencode serve
# Then in another terminal:
broski --opencode-url http://localhost:4096

How do I see debug logs?

# Follow logs live
broski logs --follow

# Export diagnostics bundle
broski logs --export

# Run interactive troubleshooter
broski troubleshoot