bux-claude-agent
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBux (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 — survives reboots
/home/bux
- 在你的服务器上以持久化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 bashbash
curl -fsSL https://raw.githubusercontent.com/browser-use/bux/main/install.sh \
| sudo BROWSER_USE_API_KEY=bu_xxx bashWith 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 bashbash
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 bashVia 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:
| Service | Purpose |
|---|---|
| Keeps Chromium alive via browser-harness |
| Web terminal on localhost |
| 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服务:
| 服务 | 用途 |
|---|---|
| 通过browser-harness保持Chromium持续运行 |
| 本地主机上的网页终端 |
| Telegram机器人桥接器(如果提供了令牌) |
Verifying the Install
验证安装
bash
undefinedbash
undefinedCheck 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.
undefinedsudo -u bux bash
cd ~
ls -la # 应显示.claude、browser-harness状态等内容
undefinedCompleting Claude Login
完成Claude登录
After install, you must log Claude in once:
bash
sudo -u bux claude /login安装后,你需要完成一次Claude登录:
bash
sudo -u bux claude /loginFollow the OAuth flow printed to stdout
按照标准输出中的提示完成OAuth流程
undefinedundefinedKey Configuration Files
关键配置文件
/home/bux/agent/CLAUDE.md
/home/bux/agent/CLAUDE.md/home/bux/agent/CLAUDE.md
/home/bux/agent/CLAUDE.mdContext loaded by Claude on every session. Edit this to give your agent persistent instructions, personas, or domain knowledge.
markdown
undefined每次会话时Claude都会加载该上下文文件。编辑此文件可为代理提供持久化指令、角色设定或领域知识。
markdown
undefinedMy 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/目录下(切勿记录这些内容)
undefinedEnvironment 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 /loginbash
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
undefinedbash
undefinedCreate 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
--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
--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"
| sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY TG_BOT_TOKEN=$TG_BOT_TOKEN bash"
undefinedssh 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"
| sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY TG_BOT_TOKEN=$TG_BOT_TOKEN bash"
undefinedDigitalOcean
DigitalOcean
bash
undefinedbash
undefinedCreate 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)
--size s-1vcpu-2gb
--image ubuntu-22-04-x64
--region nyc1
--ssh-keys $(doctl compute ssh-key list --format ID --no-header)
undefineddoctl 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)
--size s-1vcpu-2gb
--image ubuntu-22-04-x64
--region nyc1
--ssh-keys $(doctl compute ssh-key list --format ID --no-header)
undefinedRaspberry Pi (local)
Raspberry Pi(本地部署)
bash
undefinedbash
undefinedEnsure 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
| sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY bash
undefinedssh 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
| sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY bash
undefinedCustomizing Agent Behavior
自定义代理行为
Give your agent persistent skills
为代理添加持久化技能
Edit as user:
/home/bux/agent/CLAUDE.mdbuxbash
sudo -u bux nano /home/bux/agent/CLAUDE.md以bux用户身份编辑:
/home/bux/agent/CLAUDE.mdbash
sudo -u bux nano /home/bux/agent/CLAUDE.mdSend 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
undefinedbash
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." \
"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
undefined0 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." \
"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
undefinedTelegram Bot Python Bridge (telegram_bot.py)
Telegram机器人Python桥接器(telegram_bot.py)
The bot bridges Telegram messages to . Simplified structure:
claude -ppython
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 -ppython
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
undefinedbash
undefinedCheck 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
undefinedid bux
undefinedClaude not authenticated
Claude未完成认证
bash
sudo -u bux claude /loginbash
sudo -u bux claude /loginor check existing auth
或检查现有认证状态
sudo -u bux claude /status
undefinedsudo -u bux claude /status
undefinedBrowser session lost
浏览器会话丢失
bash
undefinedbash
undefinedRestart 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
undefinedsleep 10
systemctl status bux-browser-keeper
undefinedTelegram bot not responding
Telegram机器人无响应
bash
undefinedbash
undefinedVerify 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
undefinedundefinedOut of memory (2GB VPS)
内存不足(2GB VPS)
bash
undefinedbash
undefinedCheck 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
undefinedfallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab
undefinedReinstalling / updating
重新安装/更新
bash
undefinedbash
undefinedRe-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
| sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY bash
undefinedcurl -fsSL https://raw.githubusercontent.com/browser-use/bux/main/install.sh
| sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY bash
| sudo BROWSER_USE_API_KEY=$BROWSER_USE_API_KEY bash
undefinedManaged 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 Claude Code skill.
bux up如果你不想自行管理VPS:cloud.browser-use.com可在约60秒内为你部署相同的技术栈,只需使用单条命令的Claude Code Skill即可完成。
bux upContributing
贡献
The highest-leverage contribution is a deploy recipe — one file in documenting provider-specific setup steps (Oracle Free Tier, Fly.io, Mac mini, etc.).
.mddocs/recipes/bash
git clone https://github.com/browser-use/bux最有价值的贡献是部署指南——在目录下添加一个文件,记录特定服务商的部署步骤(如Oracle免费层、Fly.io、Mac mini等)。
docs/recipes/.mdbash
git clone https://github.com/browser-use/buxAdd docs/recipes/YOUR_PROVIDER.md
添加docs/recipes/YOUR_PROVIDER.md
Submit a PR
提交PR
undefinedundefined