bux-claude-agent

Bux (Browser Use Box) ♞

Skill by 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 — BROWSER_USE_API_KEY=bu_xxx
• Anthropic API key or Claude Max subscription (entered during /login)
• (Optional) Telegram bot token from @BotFather

Installation

One-liner install

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

With Telegram bot enabled

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

# 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:

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.

# 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)

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

# 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

# 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)

# 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:

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

Send one-off tasks programmatically

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

# /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:

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

# Check status
systemctl status bux-browser-keeper
journalctl -u bux-browser-keeper --since "5 min ago"

# Restart all bux services
systemctl restart bux-browser-keeper bux-ttyd bux-telegram

# Verify bux user exists
id bux

Claude not authenticated

sudo -u bux claude /login
# or check existing auth
sudo -u bux claude /status

Browser session lost

# Restart the browser keeper
systemctl restart bux-browser-keeper
# Wait ~10s for Chromium to initialize
sleep 10
systemctl status bux-browser-keeper

Telegram bot not responding

# Verify token is set
systemctl show bux-telegram | grep Environment

# Test the token directly
curl "https://api.telegram.org/bot${TG_BOT_TOKEN}/getMe"

# Check if your Telegram user ID is in the allowlist
# Get your ID by messaging @userinfobot on Telegram

Out of memory (2GB VPS)

# Check memory usage
free -h
# Chromium + Claude can be memory-hungry; consider 4GB RAM droplets
# Or add swap:
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

Reinstalling / updating

# Re-run the install script — it's idempotent
curl -fsSL https://raw.githubusercontent.com/browser-use/bux/main/install.sh \
    | sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY bash

Managed Alternative

If you don't want to manage a VPS: cloud.browser-use.com provisions the same stack for you in ~60 seconds with a one-command bux up Claude Code skill.

Contributing

The highest-leverage contribution is a deploy recipe — one .md file in docs/recipes/ documenting provider-specific setup steps (Oracle Free Tier, Fly.io, Mac mini, etc.).

git clone https://github.com/browser-use/bux
# Add docs/recipes/YOUR_PROVIDER.md
# Submit a PR