aradotso 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 pi@raspberrypi.local
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