bux-claude-agent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bux (Browser Use Box) ♞

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.
ara.so开发的Skill — 属于Daily 2026 Skills合集。
Bux可将任意Ubuntu VPS转变为搭载持久化Chromium浏览器会话的7×24小时Claude Code代理。你可以通过Telegram向代理发送指令,它会浏览网页、登录站点、交互式处理双因素认证(2FA),并在重启后保留状态——所有操作都在你拥有的硬件上进行。

What Bux Does

Bux的功能

  • 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
  • 在你的服务器上以持久化systemd服务形式运行Claude Code
  • 保持真实Chromium浏览器持续运行(Cookie/登录状态在会话间持久化)
  • 提供Telegram机器人接口,让你可以随时随地向代理发送消息
  • 提供绑定到本地主机的网页终端(ttyd)以实现直接访问
  • 当需要人工交互时(如验证码、双因素认证、登录墙),提供实时浏览器视图URL
  • 所有状态存储在
    /home/bux
    目录下——重启后仍能保留

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
  • 运行Ubuntu 22.04+的VPS,内存≥2GB(每月5美元的Hetzner或DigitalOcean云服务器即可满足需求)
  • Browser Use Cloud API密钥
    BROWSER_USE_API_KEY=bu_xxx
  • Anthropic API密钥 Claude Max订阅(在
    /login
    过程中输入)
  • (可选)来自@BotFather的Telegram机器人令牌

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

启用Telegram机器人

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

通过Claude Code完成自动化部署

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.
将以下提示粘贴到你笔记本电脑上的Claude Code中:
在我的远程服务器上部署https://github.com/browser-use/bux。

通过SSH连接到服务器(主机:YOUR_SERVER_IP),使用我的BROWSER_USE_API_KEY运行install.sh,
并配置使用我的TG_BOT_TOKEN的Telegram机器人。先阅读install.md。
安装完成后,验证服务是否运行
(systemctl is-active bux-browser-keeper bux-ttyd),然后切换到`bux`
用户并运行`claude /login`,以便我完成OAuth流程。
登录后,测试让claude访问https://browser-use.com
并返回页面标题。

Architecture

架构

  telegram ──►  telegram_bot.py ─┐
                                 ├──► claude -p  ──► browser-harness ──► BU Cloud
  browser  ──►  ttyd ────────────┘         │            (cdp over wss)
                                  /home/bux (persistent state)
Three systemd services:
ServicePurpose
bux-browser-keeper
Keeps Chromium alive via browser-harness
bux-ttyd
Web terminal on localhost
bux-telegram
Telegram bot bridge (if token provided)
  telegram ──►  telegram_bot.py ─┐
                                 ├──► claude -p  ──► browser-harness ──► BU Cloud
  browser  ──►  ttyd ────────────┘         │            (cdp over wss)
                                  /home/bux (persistent state)
三个systemd服务:
服务用途
bux-browser-keeper
通过browser-harness保持Chromium持续运行
bux-ttyd
本地主机上的网页终端
bux-telegram
Telegram机器人桥接器(如果提供了令牌)

Verifying the Install

验证安装

bash
undefined
bash
undefined

Check all services are active

检查所有服务是否处于活跃状态

systemctl is-active bux-browser-keeper bux-ttyd bux-telegram
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
journalctl -u bux-browser-keeper -f journalctl -u bux-telegram -f journalctl -u bux-ttyd -f

Check as the bux user

以bux用户身份检查

sudo -u bux bash cd ~ ls -la # should show .claude, browser-harness state, etc.
undefined
sudo -u bux bash cd ~ ls -la # 应显示.claude、browser-harness状态等内容
undefined

Completing Claude Login

完成Claude登录

After install, you must log Claude in once:
bash
sudo -u bux claude /login
安装后,你需要完成一次Claude登录:
bash
sudo -u bux claude /login

Follow the OAuth flow printed to stdout

按照标准输出中的提示完成OAuth流程

undefined
undefined

Key Configuration Files

关键配置文件

/home/bux/agent/CLAUDE.md

/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
undefined
每次会话时Claude都会加载该上下文文件。编辑此文件可为代理提供持久化指令、角色设定或领域知识。
markdown
undefined

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
  • 始终以项目符号形式总结邮件内容
  • 预订任何服务前先与我确认
  • 使用我的日历cal.example.com进行日程安排

Credentials locations

凭证位置

  • Passwords are in ~/secrets/ (never log these)
undefined
  • 密码存储在~/secrets/目录下(切勿记录这些内容)
undefined

Environment variables (set in systemd unit or shell)

环境变量(在systemd单元或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
bash
BROWSER_USE_API_KEY=bu_xxx        # 必填:Browser Use Cloud密钥
TG_BOT_TOKEN=xxx                  # 可选:Telegram机器人令牌
TG_ALLOWED_USERS=123456,789012    # 可选:以逗号分隔的Telegram用户ID列表
ANTHROPIC_API_KEY=sk-ant-xxx      # 如果通过/login使用Claude Max则可选

Using Your Agent via Telegram

通过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.
设置完成后,直接向你的机器人发送消息:
你:检查我的Gmail并总结未读邮件
代理:[浏览Gmail,返回总结内容]

你:预订下周二从旧金山(SFO)到纽约(NYC)、价格低于300美元的航班
代理:[打开Kayak/Google Flights进行搜索,返回选项]
       我找到了3个选项。是否要继续预订?[实时视图URL]

你:是的,预订达美航空早上8点的航班
代理:[导航至结账页面] 需要你的支付信息 — 
       实时视图链接:https://view.browser-use.com/session/xxx
       请直接在该页面完成支付表单填写。

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.
当Claude遇到需要交互的环节时,会提供实时视图URL:
Claude:我在你的银行登录页面遇到了双因素认证提示。
        实时视图:https://view.browser-use.com/session/abc123
        请在该页面输入你的双因素认证码,完成后告知我。
你在浏览器中打开该URL,完成操作后回复“已完成”——Claude会自动继续执行任务。

Deploying to Specific Providers

部署到特定服务商

Hetzner Cloud

Hetzner Cloud

bash
undefined
bash
undefined

Create CX21 (2 vCPU, 4GB RAM) — plenty for bux

创建CX21服务器(2核CPU,4GB内存)——完全满足bux的需求

hcloud server create
--name my-agent
--type cx21
--image ubuntu-22.04
--ssh-key ~/.ssh/id_rsa.pub
hcloud server create
--name my-agent
--type cx21
--image ubuntu-22.04
--ssh-key ~/.ssh/id_rsa.pub

Get the IP

获取服务器IP

hcloud server ip my-agent
hcloud server ip my-agent

Install bux

安装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"
undefined
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"
undefined

DigitalOcean

DigitalOcean

bash
undefined
bash
undefined

Create a $6/mo Basic Droplet via doctl

通过doctl创建每月6美元的基础云服务器

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

Raspberry Pi (local)

Raspberry Pi(本地部署)

bash
undefined
bash
undefined

Ensure Ubuntu 22.04+ on Pi, then same install script

确保树莓派上运行Ubuntu 22.04+,然后运行相同的安装脚本

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
undefined
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
undefined

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
以bux用户身份编辑
/home/bux/agent/CLAUDE.md
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)
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

通过定时任务非交互式调用claude

bash
undefined
bash
undefined

/etc/cron.d/bux-morning-brief

/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
undefined
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
undefined

Telegram Bot Python Bridge (telegram_bot.py)

Telegram机器人Python桥接器(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()
该机器人将Telegram消息桥接到
claude -p
。简化结构如下:
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
undefined
bash
undefined

Check status

检查状态

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

Restart all bux services

重启所有bux服务

systemctl restart bux-browser-keeper bux-ttyd bux-telegram
systemctl restart bux-browser-keeper bux-ttyd bux-telegram

Verify bux user exists

验证bux用户是否存在

id bux
undefined
id bux
undefined

Claude not authenticated

Claude未完成认证

bash
sudo -u bux claude /login
bash
sudo -u bux claude /login

or check existing auth

或检查现有认证状态

sudo -u bux claude /status
undefined
sudo -u bux claude /status
undefined

Browser session lost

浏览器会话丢失

bash
undefined
bash
undefined

Restart the browser keeper

重启浏览器守护进程

systemctl restart bux-browser-keeper
systemctl restart bux-browser-keeper

Wait ~10s for Chromium to initialize

等待约10秒让Chromium完成初始化

sleep 10 systemctl status bux-browser-keeper
undefined
sleep 10 systemctl status bux-browser-keeper
undefined

Telegram bot not responding

Telegram机器人无响应

bash
undefined
bash
undefined

Verify token is set

验证令牌是否已设置

systemctl show bux-telegram | grep Environment
systemctl show bux-telegram | grep Environment

Test the token directly

直接测试令牌

Check if your Telegram user ID is in the allowlist

检查你的Telegram用户ID是否在允许列表中

Get your ID by messaging @userinfobot on Telegram

通过向Telegram上的@userinfobot发送消息获取你的ID

undefined
undefined

Out of memory (2GB VPS)

内存不足(2GB VPS)

bash
undefined
bash
undefined

Check memory usage

检查内存使用情况

free -h
free -h

Chromium + Claude can be memory-hungry; consider 4GB RAM droplets

Chromium + Claude可能占用较多内存;建议使用4GB内存的云服务器

Or add swap:

或添加交换分区:

fallocate -l 2G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile echo '/swapfile none swap sw 0 0' >> /etc/fstab
undefined
fallocate -l 2G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile echo '/swapfile none swap sw 0 0' >> /etc/fstab
undefined

Reinstalling / updating

重新安装/更新

bash
undefined
bash
undefined

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
undefined
curl -fsSL https://raw.githubusercontent.com/browser-use/bux/main/install.sh
| sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY bash
undefined

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.
如果你不想自行管理VPS:cloud.browser-use.com可在约60秒内为你部署相同的技术栈,只需使用单条命令
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.).
bash
git clone https://github.com/browser-use/bux
最有价值的贡献是部署指南——在
docs/recipes/
目录下添加一个
.md
文件,记录特定服务商的部署步骤(如Oracle免费层、Fly.io、Mac mini等)。
bash
git clone https://github.com/browser-use/bux

Add docs/recipes/YOUR_PROVIDER.md

添加docs/recipes/YOUR_PROVIDER.md

Submit a PR

提交PR

undefined
undefined