unlocalhost

---

问题

你的编码 Agent 可以编写整个应用，但无法托管它，因为托管需要服务器、域名、证书和登录系统。于是人们会选择最快的方式，而问题也就由此产生：没有登录功能的公开 URL、不小心提交的 API 密钥，或者由从未编写过身份验证的人在最后才匆忙添加的身份验证。

unlocalhost 填补了这一空缺。你只需对已经打开的 Agent 说一句话，就能获得一个带有访客名单的真实 URL。

you    deploy this and let [email protected] in

agent  pushed your code to a private repo
agent  building
agent  live at sarahs-todo.unlocalhost.tech
agent  [email protected] can sign in and open it

工作原理

1. 将 unlocalhost 添加到编码 Agent，作为 MCP 服务，然后使用 GitHub 登录一次。
2. 告诉 Agent 部署，并指定允许访问的人。
3. 你的 Agent 使用你自己的 git 凭据推送代码。 unlocalhost 从不持有任何内容的写入权限。
4. 我们以只读方式克隆代码，扫描已提交的密钥；如果发现任何密钥，就会拒绝继续，然后构建并运行应用。
5. 访客使用 GitHub 或 Google 登录。我们会在请求到达你的应用之前，先将经过验证的邮箱地址与访客名单进行核对。

有何不同

	隧道（ngrok）	平台（Vercel）	unlocalhost
关闭笔记本电脑后仍可使用	否	是	是
默认私密	否	否	是
需要你编写的身份验证代码	全部	全部	无需
在你自己的服务器上运行	否	否	是

快速开始

claude mcp add unlocalhost -- npx -y @unlocalhost/unlocalhost

或者在任意 MCP 客户端配置中：

{
  "mcpServers": {
    "unlocalhost": {
      "command": "npx",
      "args": ["-y", "@unlocalhost/unlocalhost"]
    }
  }
}

然后让你的 Agent 登录 unlocalhost 并进行部署。

自托管

托管服务运行的就是这份代码。没有任何保留内容，不会向外回传信息，也没有许可证检查。

git clone https://github.com/info-arnav/unlocalhost.git
cd unlocalhost/deploy
cp .env.example .env      # fill it in
docker compose --env-file .env run --rm migrate
docker compose --env-file .env up -d

你需要一个带有通配符 DNS 的域名、用于通配符 TLS 的 DNS 服务商 API 令牌、一个 GitHub App，以及一个 Google OAuth 客户端。完整的操作指南请参阅 docs/server-setup.md。

架构

internet :443 → Caddy → auth-gate /verify → activator → Dokku → your app

Package	Job
web	落地页、登录界面、文档
server/gateway	公共 API 入口、CORS、速率限制、请求 ID
server/services/auth-gate	OAuth、会话，以及每次请求的允许名单检查
server/services/control-plane	应用、共享、GitHub App、部署流水线
server/services/activator	唤醒休眠的应用，并让闲置的应用重新休眠
server/services/mcp-server	Agent 使用的 unlocalhost npm 包
server/shared	数据库、日志记录、加密、错误、会话

我们选择借用而非自行构建的组件：Dokku 和 Nixpacks 可将代码仓库转换为运行中的容器， Caddy 负责处理通配符 TLS。刻意将创新部分保持得很小。

安全

• 在指定人员之前，应用均为私有。移除人员会立即撤销访问权限。
• 每次部署都会扫描已提交的密钥；如果发现任何密钥，部署将被拒绝。
• 请求到达应用之前，会在边缘层强制要求登录。
• 环境变量在静态存储时使用 AES 256 GCM 加密。
• 我们仅拥有只读访问权限，且只能访问你选择的仓库。

发现漏洞？请遵循 SECURITY.md，不要公开提交问题。

贡献

请先阅读 CONTRIBUTING.md。简而言之：每个后端模块都遵循 routes → controller → service → repository，代码不包含注释，也没有测试文件。通过运行程序进行验证。

许可证

MIT。请参阅 LICENSE。