bux-claude-agent

What this skill does

# Bux (Browser Use Box) ♞

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Bux turns any Ubuntu VPS into a 24/7 Claude Code agent with a persistent Chromium browser session. Text your agent via Telegram, it browses the web, logs into sites, handles 2FA interactively, and maintains state across reboots — all on hardware you own.

## What Bux Does

- Runs **Claude Code** as a persistent systemd service on your server
- Keeps a real **Chromium** browser alive (cookies/logins persist across sessions)
- Exposes a **Telegram bot** interface so you can message your agent from anywhere
- Provides a **web terminal** (ttyd) bound to localhost for direct access
- Hands you a **live browser view URL** when human interaction is needed (CAPTCHA, 2FA, login walls)
- All state lives in `/home/bux` — survives reboots

## Requirements

- Ubuntu 22.04+ VPS with ≥ 2GB RAM (a $5/mo Hetzner or DigitalOcean droplet works)
- [Browser Use Cloud API key](https://cloud.browser-use.com/new-api-key) — `BROWSER_USE_API_KEY=bu_xxx`
- Anthropic API key **or** Claude Max subscription (entered during `/login`)
- *(Optional)* Telegram bot token from [@BotFather](https://t.me/BotFather)

## Installation

### One-liner install

```bash
curl -fsSL https://raw.githubusercontent.com/browser-use/bux/main/install.sh \
    | sudo BROWSER_USE_API_KEY=bu_xxx bash
```

### With Telegram bot enabled

```bash
curl -fsSL https://raw.githubusercontent.com/browser-use/bux/main/install.sh \
    | sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY \
           TG_BOT_TOKEN=$TG_BOT_TOKEN bash
```

### Via Claude Code (automated setup)

Paste this prompt into Claude Code on your laptop:

```
Set up https://github.com/browser-use/bux on my remote box.

SSH into it (host: YOUR_SERVER_IP), run install.sh with my BROWSER_USE_API_KEY,
and wire up a Telegram bot with my TG_BOT_TOKEN. Read install.md first.
After the install completes, verify the services are running
(systemctl is-active bux-browser-keeper bux-ttyd), then become the `bux`
user and run `claude /login` so I can complete the OAuth flow.
Once logged in, test by asking claude to visit https://browser-use.com
and report the page title.
```

## Architecture

```
  telegram ──►  telegram_bot.py ─┐
                                 ├──► claude -p  ──► browser-harness ──► BU Cloud
  browser  ──►  ttyd ────────────┘         │            (cdp over wss)
                                           ▼
                                  /home/bux (persistent state)
```

Three systemd services:
| Service | Purpose |
|---|---|
| `bux-browser-keeper` | Keeps Chromium alive via browser-harness |
| `bux-ttyd` | Web terminal on localhost |
| `bux-telegram` | Telegram bot bridge (if token provided) |

## Verifying the Install

```bash
# Check all services are active
systemctl is-active bux-browser-keeper bux-ttyd bux-telegram

# View logs for each service
journalctl -u bux-browser-keeper -f
journalctl -u bux-telegram -f
journalctl -u bux-ttyd -f

# Check as the bux user
sudo -u bux bash
cd ~
ls -la  # should show .claude, browser-harness state, etc.
```

## Completing Claude Login

After install, you must log Claude in once:

```bash
sudo -u bux claude /login
# Follow the OAuth flow printed to stdout
```

## Key Configuration Files

### `/home/bux/agent/CLAUDE.md`
Context loaded by Claude on every session. Edit this to give your agent persistent instructions, personas, or domain knowledge.

```markdown
# My Agent Instructions

## Preferred behavior
- Always summarize email in bullet points
- When booking anything, confirm with me first
- Use my calendar at cal.example.com for scheduling

## Credentials locations
- Passwords are in ~/secrets/ (never log these)
```

### Environment variables (set in systemd unit or shell)

```bash
BROWSER_USE_API_KEY=bu_xxx        # Required: Browser Use Cloud key
TG_BOT_TOKEN=xxx                  # Optional: Telegram bot token
TG_ALLOWED_USERS=123456,789012    # Optional: comma-separated Telegram user IDs
ANTHROPIC_API_KEY=sk-ant-xxx      # Optional if using Claude Max via /login
```

## Using Your Agent via Telegram

Once set up, message your bot directly:

```
You: check my gmail and summarize unread emails
Agent: [browses Gmail, returns summary]

You: book a flight from SFO to NYC next Tuesday under $300
Agent: [opens Kayak/Google Flights, searches, returns options]
       I found 3 options. Should I proceed with booking? [live view URL]

You: yes, book the Delta flight at 8am
Agent: [navigates to checkout] I need your payment info — 
       here's a live view: https://view.browser-use.com/session/xxx
       Please complete the payment form directly.
```

## Working with the Browser Directly

When Claude hits an interactive wall, it surfaces a live view URL:

```
Claude: I've hit a 2FA prompt on your bank login.
        Live view: https://view.browser-use.com/session/abc123
        Please enter your 2FA code there, then tell me when done.
```

You open the URL in your browser, complete the action, then reply "done" — Claude continues automatically.

## Deploying to Specific Providers

### Hetzner Cloud

```bash
# Create CX21 (2 vCPU, 4GB RAM) — plenty for bux
hcloud server create \
  --name my-agent \
  --type cx21 \
  --image ubuntu-22.04 \
  --ssh-key ~/.ssh/id_rsa.pub

# Get the IP
hcloud server ip my-agent

# Install bux
ssh root@<IP> "curl -fsSL https://raw.githubusercontent.com/browser-use/bux/main/install.sh \
  | sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY TG_BOT_TOKEN=$TG_BOT_TOKEN bash"
```

### DigitalOcean

```bash
# Create a $6/mo Basic Droplet via doctl
doctl compute droplet create my-agent \
  --size s-1vcpu-2gb \
  --image ubuntu-22-04-x64 \
  --region nyc1 \
  --ssh-keys $(doctl compute ssh-key list --format ID --no-header)
```

### Raspberry Pi (local)

```bash
# Ensure Ubuntu 22.04+ on Pi, then same install script
ssh [email protected]
curl -fsSL https://raw.githubusercontent.com/browser-use/bux/main/install.sh \
    | sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY bash
```

## Customizing Agent Behavior

### Give your agent persistent skills

Edit `/home/bux/agent/CLAUDE.md` as `bux` user:

```bash
sudo -u bux nano /home/bux/agent/CLAUDE.md
```

### Send one-off tasks programmatically

```python
import subprocess

result = subprocess.run(
    ["sudo", "-u", "bux", "claude", "-p",
     "Visit https://news.ycombinator.com and return the top 5 headlines as JSON"],
    capture_output=True, text=True
)
print(result.stdout)
```

### Invoke claude non-interactively from a cron job

```bash
# /etc/cron.d/bux-morning-brief
0 8 * * * bux /usr/local/bin/claude -p \
  "Check my email, weather for San Francisco, and top HN stories. \
   Send a morning brief to my Telegram." \
  >> /var/log/bux-morning.log 2>&1
```

## Telegram Bot Python Bridge (telegram_bot.py)

The bot bridges Telegram messages to `claude -p`. Simplified structure:

```python
import asyncio
import subprocess
from telegram import Update
from telegram.ext import ApplicationBuilder, MessageHandler, filters, ContextTypes

ALLOWED_USERS = {int(uid) for uid in os.environ.get("TG_ALLOWED_USERS", "").split(",") if uid}

async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id
    if ALLOWED_USERS and user_id not in ALLOWED_USERS:
        await update.message.reply_text("Unauthorized.")
        return

    task = update.message.text
    await update.message.reply_text("On it...")

    result = await asyncio.to_thread(
        subprocess.run,
        ["claude", "-p", task],
        capture_output=True, text=True,
        cwd="/home/bux"
    )
    await update.message.reply_text(result.stdout or result.stderr)

app = ApplicationBuilder().token(os.environ["TG_BOT_TOKEN"]).build()
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))
app.run_polling()
```

## Troubleshooting

### Services not starting

```bash
# Check status
systemctl status bux-browser-keeper
jour