★ FEATURED ARTICLE 【免费下载链接】headlongAn open source agent microharness featuring persistent agency and recursive LLMs. Of bash, by bash, for bash; its shells all the way down.项目地址https://gitcode.com/gh_mirrors/headl/headlong点击查看免费下载把Headlong一个开源的 AI Agent 微框架核心约 1.1 万行 Bash部署到专用服务器只需要两步systemd负责让headlong-web仪表板和每个 Agent 的调度器在重启后自动复活Terraform负责一键拉起 AWS 服务器 Cloudflare 零入站隧道。这篇完整指南面向新手带你看懂架构、跑通部署并掌握日常运维与故障排查 ⚠️先记住一条黄金原则Headlong 的 Agent 会在服务器上执行真实的 shell 命令所以官方建议把这台服务器当作**可烧毁的机器burnable box——上面只跑 Agent不跑任何其他服务再配一把带消费上限的专用 API 密钥**作为真正的安全网。部署架构一图看懂零入站端口设计Headlong 官方推荐的部署形态是服务器永远不开放任何入站端口。浏览器访问的路径是这样的你的浏览器 ── Cloudflare AccessSSO / 邮件 OTP 登录 │ Cloudflare Tunnel从 VM 只向外拨号 │ 127.0.0.1:8080 headlong-websystemd 服务 │ 派生 各身份的 dispatcher thinkers独立 systemd 单元三个关键组件各管一摊组件职责说明AWS 可烧毁VM运行整个 Headlong默认t4g.large、Ubuntu 24.04 arm64、40 GB gp3 磁盘安全组零入站规则登录走 SSM 而非 SSHCloudflare Zero Trust唯一的入口出站隧道 CNAME 解析 邮件白名单 OTP 登录认证全部在这一层应用本身零认证AWS SSM 参数存放 API 密钥整个.env存进一个 SecureString 参数绝不进入 Terraform 状态文件完整部署物料都集中在 deploy/ 目录可复用的部分是 deploy/setup.sh、deploy/update.sh、systemd 单元文件和 deploy/terraform/ 基础设施代码官方操作手册是 deploy/DEPLOY.md 和 deploy/terraform/README.md。手动部署路径setup.sh 一键装好 systemd 全家桶如果你已经有一台空的 Ubuntu 22.04/24.04 服务器比如 Lightsail 或任意云主机可以先不走 Terraform直接手动体验1️⃣ 克隆仓库并运行部署脚本git clone https://gitcode.com/gh_mirrors/headl/headlong.git cd headlong sudo bash deploy/setup.shdeploy/setup.sh 会自动完成创建专用系统用户shellm把仓库克隆到/opt/shellm/app为该用户安装uv、bun并预构建 web/viewer/ 前端仪表板安装并启动headlong-websystemd 服务只监听127.0.0.1:8080安装按身份启用的调度器单元headlong-thinkersidentity.service及 sudo 控制封装headlong-thinkersctl把身份目录独立挂载到/var/lib/headlong/identities代码更新永远碰不到 Agent 的记忆见 design/runtime_isolation.md2️⃣ 写入带消费上限的 API 密钥并验证sudo -u shellm nano /opt/shellm/app/.env # 填入 ANTHROPIC_API_KEY 等 sudo systemctl restart headlong-web curl -s localhost:8080/api/health # 应返回 {status:ok}3️⃣ systemd 单元文件都装了什么单元文件作用deploy/headlong-web.service仪表板 控制平面Restartalways崩溃自愈KillModeprocess保证重启 Web 服务不会误杀正在思考的 AgentMemoryMax5G防止缓存膨胀拖垮整机deploy/headlong-thinkers.service每个 Agent 身份一个独立 cgroupWeb 重启、OOM 都不会让心智孤立或死亡deploy/headlong-thinkers-silence.timer静默告警定时器Agent 长时间不说话会提醒你deploy/thinkers-sandbox.sh生成 systemd 沙箱 drop-inAgent 每次醒来时文件系统除自身目录外只读 单元文件每次部署都会从仓库重新同步所以本地修改请写在/etc/systemd/system/headlong-web.service.d/override.confdrop-in 里它们可以存活多次部署。Terraform 一键部署terraform apply 拉起整个栈准备好工具后deploy/terraform/ 用一个terraform apply就能搭建上文架构图里的全部内容。0️⃣ 前置检查以 macOS brew 为例详见 deploy/terraform/README.mdbrew install awscli brew tap hashicorp/tap brew install hashicorp/tap/terraform brew install --cask session-manager-plugin # 无 SSH 登录的钥匙另外你需要一个 Cloudflare API Token权限Tunnel Edit、Access Apps Edit、Zone DNS Edit以及账号 ID 和 Zone ID在 Cloudflare 控制台可见。1️⃣ 填写基础设施事实不存密钥cd deploy/terraform cp terraform.tfvars.example terraform.tfvars # 填 region、ID、域名、邮箱白名单 cp envrc.example .envrc direnv allow # 自动加载 CLOUDFLARE_API_TOKEN关键变量定义在 deploy/terraform/variables.tfallowed_emails就是能登录仪表板的全部名单subdomain决定访问地址默认agents.example.com。AWS 侧权限可以直接挂AdministratorAccess或按 deploy/terraform/aws-policy.json 创建最小化策略。2️⃣ 密钥走 SSM 参数绝不进 Terraform 状态aws ssm put-parameter --name /shellm/env --type SecureString \ --value $(cat /path/to/headlong/.env) --overwrite \ --region us-east-1首次启动时引导脚本会把参数内容写入/opt/shellm/app/.env权限 600实例重建也能自愈且实例角色只能读这一个参数。3️⃣ 应用并观察首次启动terraform init terraform plan terraform apply首次启动约5 分钟装依赖、构建前端全程由 deploy/terraform/user_data.sh.tpl 渲染的引导脚本完成装cloudflared并连接隧道 → 克隆仓库并执行setup.sh→ 从 SSM 拉取.env→ 用 systemd drop-in把 CORS 锁死到你的域名。登录 SSM 会话跟踪进度$(terraform output -raw ssm_session_command) tail -f /var/log/shellm-bootstrap.log # 看到 bootstrap done 即可然后打开terraform output打印的url——你会先看到 Cloudflare 的邮件 OTP 登录页输入白名单邮箱、收验证码即可进入仪表板 日常运维更新、暂停计费与故障排查日常操作都被封装成了 deploy/scripts/ 里的小脚本需要本机 AWS 凭证任务命令交互式登录服务器deploy/scripts/shellSSM 会话无 SSH查看实例状态 服务健康 已部署提交deploy/scripts/status部署最新已推送代码deploy/scripts/update内部流式执行 deploy/update.sh拉代码、重建前端、重启 Web 服务运行中的 Agent 不受影响暂停计费磁盘和身份保留deploy/scripts/stop约省 $60/月只留 ~$3/月磁盘费两条排错经验官方踩坑总结黄金法则服务器跑的是推送到shellm_branch的代码不是你笔记本上的工作区。任何本地修改必须先 commit push机器才看得见。Thinker 日志循环报PROVIDER_API_KEY is not set基本是 SSM 参数缺失、过期或SHELLM_MODEL与密钥类型不匹配例如openai/...模型却没配OPENROUTER_API_KEY重走一遍密钥上传步骤即可。安全底线与紧急停机开关部署完成后的安全姿态详见 deploy/SECURITY.md✅ VM 本身就是沙箱零入站端口唯一入口是 Cloudflare Access不要临时把 Web 服务绑到0.0.0.0✅ 密钥消费上限是真正的保险丝OpenRouter 用预付费额度、Anthropic 设置 spend cap✅ 身份可整体导出为可移植的.shellm.tgz密钥和运行时状态不会离开机器适合演示前备份恢复流程见 deploy/DEPLOY.md 的快照章节紧急开关按升级顺序仪表板 Kill All 按钮 → 服务器上headlong-killall见 tools/headlong-killall→systemctl stop headlong-web→ 直接停掉 VM 顺带一提仓库里能找到的图片资源如 web/viewer/public/icons/icon-512.png均为 PWA 小图标分辨率不满足正文配图标准因此本文未插入行内图片架构细节建议直接阅读上文图示与 deploy/DEPLOY.md 的架构图。总结部署方式适合场景核心命令手动 systemd已有服务器想快速体验sudo bash deploy/setup.shTerraform 全托管零入站 SSO 登录 一键重建terraform apply掌握这三件事你就完成了 Headlong 专用服务器部署架构上零入站端口Cloudflare 隧道是唯一入口、运维上 systemd 自愈Web 与调度器分离重启不丢心智、成本上随时可停stop实例省 95% 费用身份和磁盘数据原样保留。祝你早日拥有一个 7×24 小时在线、随时可以杀进程兜底的 AI Agent赞分享【免费下载链接】headlongAn open source agent microharness featuring persistent agency and recursive LLMs. Of bash, by bash, for bash; its shells all the way down.项目地址https://gitcode.com/gh_mirrors/headl/headlong点击查看免费下载相关推荐Komodo Periphery 一键安装脚本实战指南用 systemd 管理多服务器 Agent 部署Komodo Periphery 一键安装脚本实战指南用 systemd 管理多服务器 Agent 部署 本指南以仓库 scripts/readme.md hDevOps容器编排CI/CD运维Gradio 应用自托管部署实战用 Disco 一键把应用部署到自己的 Ubuntu 服务器Gradio 应用自托管部署实战用 Disco 一键把应用部署到自己的 Ubuntu 服务器 导读 Gradio 是一个开源的 Python 库只需几行代前端后端AI 应用nanobot 部署实战Render 一键上线、Docker 容器化与 systemd/LaunchAgent 常驻服务nanobot 部署实战Render 一键上线、Docker 容器化与 systemd/LaunchAgent 常驻服务 本文基于 nanobot 仓库的 部人工智能AI AgentAgent 框架多智能体工具调用MCP Clients交互助手后端任务调度创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
