Background Service

Run the Broski bridge as a persistent background service that starts automatically on boot.

Overview

By default, the bridge runs in your terminal and stops when you close the window. For always-on access, you can run the bridge as a background service (daemon) that:

Starts automatically when your computer boots
Runs in the background without a terminal window
Automatically restarts if it crashes
Logs output to files for debugging

Quick Setup (Recommended)

The easiest way to set up the bridge as a background service:

bash

# Install as background service
broski install

# Check status
broski status

# View QR code to pair your phone
broski qr

# Stop the service
broski stop

# Remove the service
broski uninstall

Recommended Workflow

Use broski install once, then use broski qr to get the QR code whenever you need to pair a new device. The service keeps running in the background.

macOS LaunchAgent

On macOS, the recommended way to run the bridge as a service is using a LaunchAgent. The broski install command creates this for you, but here's the manual setup:

1. Create the LaunchAgent plist

Create a file at ~/Library/LaunchAgents/com.broski.bridge.plist:

xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.broski.bridge</string>
    
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOUR_USERNAME/.broski/bin/broski</string>
    </array>
    
    <key>RunAtLoad</key>
    <true/>
    
    <key>KeepAlive</key>
    <true/>
    
    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/.broski/logs/bridge.log</string>
    
    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/.broski/logs/bridge.error.log</string>
</dict>
</plist>

Important

Replace YOUR_USERNAME with your actual macOS username. Find it with: whoami

2. Load the service

bash

# Load and start the service
launchctl load ~/Library/LaunchAgents/com.broski.bridge.plist

# Verify it's running
launchctl list | grep broski

3. Manage the service

bash

# Stop the service
launchctl stop com.broski.bridge

# Start the service
launchctl start com.broski.bridge

# Unload (disable) the service
launchctl unload ~/Library/LaunchAgents/com.broski.bridge.plist

# View logs
tail -f ~/.broski/logs/bridge.log
tail -f ~/.broski/logs/bridge.error.log

With Tailscale Funnel

To enable Funnel in your background service, modify the ProgramArguments:

xml

<key>ProgramArguments</key>
<array>
    <string>/Users/YOUR_USERNAME/.broski/bin/broski</string>
    <string>--funnel</string>
</array>

Or set the environment variable:

xml

<key>EnvironmentVariables</key>
<dict>
    <key>BROSKI_ENABLE_FUNNEL</key>
    <string>1</string>
</dict>

Linux systemd

On Linux, use systemd to run the bridge as a user service.

1. Create the service file

Create ~/.config/systemd/user/broski.service:

ini

[Unit]
Description=Broski Bridge
After=network.target

[Service]
Type=simple
ExecStart=%h/.broski/bin/broski
Restart=always
RestartSec=10
Environment="PATH=%h/.broski/bin:/usr/local/bin:/usr/bin:/bin"

[Install]
WantedBy=default.target

2. Enable and start

bash

# Create config directory if needed
mkdir -p ~/.config/systemd/user

# Reload systemd
systemctl --user daemon-reload

# Enable on boot
systemctl --user enable broski

# Start now
systemctl --user start broski

# Check status
systemctl --user status broski

# View logs
journalctl --user -u broski -f

3. Manage the service

bash

# Stop the service
systemctl --user stop broski

# Restart the service
systemctl --user restart broski

# Disable auto-start
systemctl --user disable broski

Enable lingering

For the service to run after you log out, enable lingering:

bash

loginctl enable-linger $USER

Windows Task Scheduler

On Windows, use Task Scheduler to run the bridge automatically.

Method 1: Task Scheduler GUI

Open Task Scheduler

Press Win+R, type taskschd.msc, press Enter

Create Basic Task

Click 'Create Basic Task' in the right panel

Name the task

Name: 'Broski Bridge', Description: 'Broski bridge server'

Set trigger

Choose 'When I log on'

Set action

Choose 'Start a program'

Configure program

Program: %USERPROFILE%\.broski\bin\broski.exe

Configure options

Check 'Open the Properties dialog' and click Finish

Set to run hidden

In Properties > General, check 'Run whether user is logged on or not'

Method 2: PowerShell (Command Line)

powershell

# Create scheduled task
$action = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.broski\bin\broski.exe"
$trigger = New-ScheduledTaskTrigger -AtLogon
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable
$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -RunLevel Limited

Register-ScheduledTask -TaskName "Broski Bridge" -Action $action -Trigger $trigger -Settings $settings -Principal $principal

# Check status
Get-ScheduledTask -TaskName "Broski Bridge"

# Start manually
Start-ScheduledTask -TaskName "Broski Bridge"

# Stop
Stop-ScheduledTask -TaskName "Broski Bridge"

# Remove
Unregister-ScheduledTask -TaskName "Broski Bridge" -Confirm:$false

Windows Log Location

To capture logs on Windows, modify the task to redirect output:

powershell

# Create a batch script at %USERPROFILE%\broski-start.bat
@echo off
%USERPROFILE%\.broski\bin\broski.exe >> %USERPROFILE%\.broski\logs\bridge.log 2>&1

Then point the scheduled task to this batch script instead.

Log File Locations

Platform	Standard Output	Error Output
macOS (LaunchAgent)	~/.broski/logs/bridge.log	~/.broski/logs/bridge.error.log
Linux (systemd)	journalctl --user -u broski	journalctl --user -u broski
Windows	%USERPROFILE%\.broski\logs\bridge.log	(combined with stdout)

View Logs

bash

# macOS
tail -f ~/.broski/logs/bridge.log

# Linux
journalctl --user -u broski -f

# Windows (PowerShell)
Get-Content -Path "$env:USERPROFILE\.broski\logs\bridge.log" -Wait

Auto-Restart on Failure

Configure automatic restart when the bridge crashes:

macOS (LaunchAgent)

Add these keys to your plist for automatic restart:

xml

<!-- Restart immediately on crash -->
<key>KeepAlive</key>
<true/>

<!-- Or restart only on crash (not clean exit) -->
<key>KeepAlive</key>
<dict>
    <key>SuccessfulExit</key>
    <false/>
</dict>

<!-- Throttle restarts (wait 10 seconds between restart attempts) -->
<key>ThrottleInterval</key>
<integer>10</integer>

Linux (systemd)

ini

[Service]
# Restart on failure
Restart=on-failure
# Wait 10 seconds before restarting
RestartSec=10
# Give up after 5 failures in 5 minutes
StartLimitIntervalSec=300
StartLimitBurst=5

Windows (Task Scheduler)

In Task Properties > Settings:

Check "If the task fails, restart every:" and set to 1 minute
Set "Attempt to restart up to:" to 3 times
Check "Run task as soon as possible after a scheduled start is missed"

Checking Service Status

Platform	Check Status Command
All platforms (recommended)	broski status
macOS (LaunchAgent)	launchctl list \| grep broski
Linux (systemd)	systemctl --user status broski
Windows	Get-ScheduledTask -TaskName 'Broski Bridge'

Viewing the QR Code

When running as a background service, you can't see the QR code in a terminal. Options:

Option 1: Use the qr command (Recommended)

bash

broski qr

Shows the QR code while the background service is running.

Option 2: Run temporarily in foreground

bash

# Stop the service temporarily
broski stop

# Run in foreground to see QR
broski

# Scan QR, then Ctrl+C and restart service
broski install

Option 3: Use saved connection

Once you've scanned the QR code, your phone remembers the connection. As long as the token in ~/.broski/token.json doesn't change, the app will reconnect automatically.

Troubleshooting

Service not starting

Check logs: tail ~/.broski/logs/bridge.error.log
Verify the path to broski is correct
Ensure broski is installed: broski --help
Run broski doctor to check requirements

Can't connect from phone

Run broski status to check if running
Verify the service is running in logs
Check firewall isn't blocking port 18274
Try broski qr to get current QR code

Service keeps restarting

Check error logs for crash reason
Verify OpenCode is installed: opencode --version
Check if port 18274 is in use by another process
Try running manually first: broski in a terminal

Permission denied errors

Ensure the service runs as your user, not root
Check file permissions on ~/.broski/
Verify broski is executable: ls -la ~/.broski/bin/broski

Next Steps

Remote Access

Set up Tailscale for access from anywhere

Troubleshooting

Solve common issues