host0

host0 是做什么的？

host0 托管你的 AI 代理创建的任何内容 —— HTML、网站、带共享数据库的应用、Markdown、PDF —— 并生成一个你可以分享的链接，就像分享 Google 文档一样简单。适用于任何代理。

核心原语是一个 应用：发布任何文件或文件夹 —— 一个包含静态文件的目录，或一个可以在浏览器中打开的单个文件（PDF、图片、单个 HTML 页面、视频、音频、Markdown、CSV、文本；压缩包或其他仅下载类型的文件会被拒绝 —— 请解压 zip 并发布文件夹）—— 并获得一个位于 https://{slug}.host0.app/ 的实时 URL（本地开发：http://{slug}.localhost:3000/）。默认情况下，每个应用都是 私有的 —— 只有所有者（登录 host0）和通过邮件邀请的人可以打开。选择 --visibility link 可让任何拥有 URL 的人（无需登录；未列出且永远不会被索引）访问。--visibility public 则更进一步 —— 在网络上公开，搜索引擎可能会索引它 —— 仅用于用户希望在搜索结果中找到的内容。新应用的 URL 是随机的（如 k3x9q2m7ta.host0.app）；当用户想要一个更易读的链接时，可以将其重命名为有意义的名称（如 team-todo.host0.app）—— 请参见下面的“重命名 URL”。

一个应用还可以持有 共享数据：在 h0.json 中声明记录集合，其前端即可获得一个数据库，无需服务器代码。请参见下面的“共享数据” —— 这将一个页面转变为一个团队可以共同使用的工具。

当前文档

完整文档位于 https://host0.ai/docs —— 当用户询问某个功能如何工作、有哪些可能性，或在告诉用户某个功能不受支持之前，请阅读这些文档。

API 也描述了自身。机器可读的索引：

curl -sS {base}/api/v1

它会返回当前的端点列表、文件限制以及平台合约（host0 当前提供的内容）。发送 API 密钥（-H "authorization: bearer $HOST0_API_KEY"），那么 limits 和 plan 就是用户自己的 —— 限制取决于账户的套餐；如果没有密钥，你将获得新账户的默认值。GET {base}/api/v1/account 还会显示本月已使用的额度。如果本文档描述的技能与实时 API 的行为不一致，请以实时 API 为准。

要安装或更新此技能：npx skills add host0-ai/skills（任何 skills CLI 支持的代理；源代码：https://github.com/host0-ai/skills），或获取两个文件：`https://host0.ai/skill.md` → 保存为 SKILL.md，以及 https://host0.ai/publish.sh → 保存为同目录下的 scripts/publish.sh，然后执行 chmod +x scripts/publish.sh。脚本的 URL 是 /publish.sh —— 其中没有 /scripts/ 路径。

要求

• 必需的可执行文件：curl、jq（如果两者中任何一个缺失，脚本会以清晰的错误信息退出）
• 一个 API 密钥，来自 $HOST0_API_KEY 或 ~/.host0/credentials。如果都没有，publish.sh 会为你启动一个 设备登录流程 —— 用户在自己的浏览器中批准一个链接和代码（请参见“获取 API 密钥”）
• 捆绑的辅助脚本：./scripts/publish.sh
• 网络：出站 HTTPS 连接到 host0.ai（API）和 host0.app（上传和实时应用）。在具有出站白名单的沙盒中，如果请求总是失败并显示 SSL_ERROR_SYSCALL、代理错误或连接被拒绝/重置，请告知用户需要允许哪个域名 —— 不要在此循环重试。
• 瞬时故障会发生：某些云沙盒可能会偶尔遇到连接重置 / SSL_ERROR_SYSCALL / 连接到 host0.ai 时超时。publish.sh 会自动重试这些情况（你会在 stderr 上看到 host0: network hiccup … retrying 2/4）—— 让它运行即可。如果你直接使用原始 curl 调用 API，请自行重试请求；对于 GET 和设备登录轮询，可以添加 --retry 3 --retry-all-errors，但绝不用于创建资源的 POST。

发布应用

./scripts/publish.sh {dir} [--name "my app"]
./scripts/publish.sh {file}  [--name "my app"]   # 单个文件：pdf、图片、页面

在 stdout 上输出实时 URL（例如 https://k3x9q2m7ta.host0.app/ —— 新应用会获得一个随机 slug；--name 仅用于显示名称）。

如果你使用的不是 Claude Code、Codex、Cursor 或 Gemini CLI，请添加 --client {your-agent}（例如 --client claude-ai）—— 脚本会自动检测这些代理。它仅用于标记部署统计。

底层是一个三步流程：清单 → 上传文件 → 最终确认。应用在最终确认成功之前不会上线。

文件结构： index.html 必须位于你发布的目录的根目录下 —— 该目录的内容将成为站点根目录。发布 my-site/ 目录，其中包含 my-site/index.html，而不是包含 my-site/ 的父文件夹。

单个文件： 直接传递文件本身（./scripts/publish.sh report.pdf）—— 不需要 index.html。应用的根 URL 将提供该文件（在浏览器标签页中，它会在 host0 的文件查看器中打开 —— 请参阅下面的徽章说明；?download 可以获取原始文件，PDF 支持大文件的范围请求），并且也可以通过在 /{filename} 路径访问。当用户只想分享一个文档或图片时，请使用此方式。

部署构建输出，而非源代码： 如果项目使用构建步骤（React/Vite/Next export、.ts/.tsx/.vue/.svelte），请先构建，然后发布输出目录（dist/、build/、out/）。切勿发布 node_modules/、package.json 或机密文件（.env、密钥文件）—— API 会拒绝服务器代码和机密文件，并附带可操作的错误信息。

测试期间免费，带有一个徽章： host0 在测试期间免费，并且每个应用都使用免费套餐，该套餐会在每个 HTML 页面的右下角添加一个小的“Hosted on host0”徽章（高约 28px，距边缘 12px），因此请在该位置留出一点空间（不要在该角落放置固定的按钮或聊天气泡）并且不要试图隐藏它。直接在浏览器标签页中打开的 PDF、图片、视频、音频或文本文件（.txt、.csv、.md、.json）会在 host0 文件查看器中打开：文件填满窗口，下方有一个细条（文件名、下载、“Hosted on host0”），永远不会遮挡文件。原始文件仍然会通过 <img>/<video> 标签、嵌入式内容、fetch()、curl、链接预览和搜索引擎提供；在任何文件 URL 后添加 ?download 可以下载原始文件。其他文件（zip、字体、JS、CSS）按原样提供。用户的套餐是否显示徽章由 GET {base}/api/v1（使用他们的密钥）返回的 plan.badge 决定。如果用户询问定价或移除徽章：当该索引包含 plans 列表时，它会列出每个套餐的名称、价格以及它改变的内容（badge: false 的套餐会移除徽章）—— 请将他们指向 {base}/pricing；如果没有 plans 列表，则 host0 在测试期间免费，付费套餐可能会在以后推出，并且可能允许他们移除徽章。

内置分析： host0 会统计每个应用的访问量，不使用 cookie —— 一个微小的同源脚本（/.h0/a.js）会被添加到每个 HTML 页面中，打开的 PDF 会在服务器端进行计数。所有者可以在仪表板的 Analytics 标签页中查看访问者、页面、来源、国家/地区和设备，也可以通过 GET {base}/api/v1/apps/{app_id_or_slug}/analytics?period=7d（period 可选值：24h、7d、30d、90d、365d；否则返回 400 invalid_period；可选过滤器 page=/path、referrer=host 或 (direct)、country=DE 或 (unknown)、device、browser 可以缩小每个数字的范围 —— 格式错误则返回 400 invalid_filter）或 MCP get_analytics 工具获取。不要移除该脚本。如果应用设置了 Content-Security-Policy，请在 script-src 和 connect-src 中允许 'self'。当用户询问“有多少人打开了它？”时，请从该端点获取答案。

更新应用

./scripts/publish.sh {dir} --slug {slug}     # 或 --app-id {uuid}

如果没有提供标志，脚本会从已发布目录中的 .host0/state.json 解析应用（对于单个文件：使用文件旁边的 .host0/state.json，以文件名为键，因此一个文件夹中的两个文件仍然是两个应用），并且仅在没有匹配项时创建新应用。服务器端会对未更改的文件进行哈希跳过 —— 重新发布一个包含一个已编辑文件的大型站点只会上传一个文件。

添加 --message "what changed"（最多 200 个字符）为新版本添加说明 —— 例如 --message "Added a due date column"。每当你发布用户要求的更改时，都建议这样做；这将显示在版本列表中供用户查看。

版本和回滚

每个上线发布的版本都是应用的编号版本（v1、v2、…）—— publish_result.version 是当前版本，publish_result.previous_version 是它替换的版本。早期版本会根据套餐保留一定天数 —— GET {base}/api/v1（使用密钥）→ limits.account.version_retention_days（0 = 仅保留当前版本）；较旧的版本会被自动删除。

当用户想要撤消更改（“回滚”、“恢复旧版本”、“那个版本坏了”）时，恢复早期版本 —— 它会在一分钟内作为新版本重新上线给所有人，无需重新上传：

# 列出版本，最新的在前（version, live, message, client, restored_from_version, created_at）
curl -sS {base}/api/v1/apps/{app_id_or_slug}/versions \
  -H "authorization: bearer $HOST0_API_KEY"

# 恢复版本 3（也接受 v3）；请求体是可选的
curl -sS -X POST {base}/api/v1/apps/{app_id_or_slug}/versions/3/restore \
  -H "authorization: bearer $HOST0_API_KEY" \
  -H "content-type: application/json" \
  -d '{"message": "回到重新设计之前"}'

• 响应包含 version（新版本）、restored_from_version 和 previous_version —— 告知用户“版本 3 已作为版本 9 重新上线”，并且恢复版本 8 会撤销此操作。
• 在恢复之前请与用户确认：这会改变每个打开应用的人看到的内容。
• 共享数据永远不会因恢复而改变。恢复后的版本的 h0.json 决定提供哪些集合 —— 一个它未声明的集合会被隐藏（但仍然存在于导出中），并在恢复较新版本时重新出现。
• 恢复已经上线的版本会返回 already_live: true 并且不会增加版本号 —— 不要在一个循环中重试。
• 404 version_not_found：该版本已不再保留 —— 列出版本并提供一个可恢复的版本；切勿将一个较旧的、已删除的版本表示为可恢复。409 version_not_restorable：其文件已不存在 —— 改为从用户文件中重新发布。403 versions_not_in_plan：用户的套餐仅保留当前版本 —— 重新发布用户希望上线的文件，并查看“当错误包含 upgrade_url 时”。
• 稍后可以使用 PATCH {base}/api/v1/apps/{app_id_or_slug}/versions/{n} 和 {"message": "…"}（或 null）设置或清除说明。MCP 服务器的 list_versions 和 restore_version 工具与上述调用功能相同，仪表板中应用的 Versions 标签页也包含一个 Restore 按钮。

访问控制

host0 应用一次只使用一种可见性：

• private（默认）：仅限所有者及被邀请的邮件；访客需登录才能查看。每个新应用都从此状态开始。
• link —— “任何拥有链接的人”：任何拥有 URL 的人都可以查看，无需登录。该应用是未列出的，永远不会被索引（每个响应都带有 X-Robots-Tag: noindex），并且其 URL 最初是随机的 —— 但链接会被传播，并且一个重命名后的、可读的 URL 可能会被猜到 —— 请将敏感内容保持私有。
• public —— “在网络上公开”：任何人都可以查看 并且搜索引擎可能会对其进行索引（应用自身页面以 X-Robots-Tag: all 提供）。选择加入，并且每个账户有上限（403 public_app_limit_reached，响应体中包含 max_public_apps）。仅当用户希望该应用在搜索中被找到时才使用 —— 如作品集、着陆页、文档、公开工具。切勿用于任何敏感内容。

当用户想要一个任何人都可以打开的链接（用于发送的页面、演示、共享 PDF）时，请使用 --visibility link 发布 —— 这就是“使其公开”或“分享链接”几乎总是指的含义。仅当用户明确表示想要在 Google/搜索结果中显示时才选择 public；如果不确定，请询问。共享数据在 link 和 public 下工作方式相同。可以在发布时通过 --visibility private|link|public 设置可见性，也可以随时通过 API 设置：

curl -sS {base}/api/v1/apps/{app_id_or_slug} -X PATCH \
  -H "authorization: bearer $HOST0_API_KEY" \
  -H "content-type: application/json" \
  -d '{"visibility": "link"}'

如果转为 public 返回 public_app_limit_reached，请告知用户其账户已达到网络上公开应用的数量限制，并提供 link 作为替代方案（任何拥有 URL 的人都可以访问，不会被索引）或将另一个公开应用移回 link。

重命名 URL

新应用的 URL 是一个类似 k3x9q2m7ta.host0.app 的随机 slug。要赋予它一个可读的名称，请先检查名称是否可用，然后重命名：

curl -sS {base}/api/v1/slugs/team-todo -H "authorization: bearer $HOST0_API_KEY"
# → {"slug":"team-todo","available":true}   （或 available:false + 原因）

curl -sS {base}/api/v1/apps/{app_id} -X PATCH \
  -H "authorization: bearer $HOST0_API_KEY" \
  -H "content-type: application/json" \
  -d '{"slug": "team-todo"}'
# → {"app_id":"…","slug":"team-todo","url":"https://team-todo.host0.app/","old_slug":"k3x9q2m7ta",…}

Slug 由 1–63 个小写字母、数字或连字符组成，开头或结尾不能有连字符。如果 slug 已被占用，会返回 409 slug_taken；格式错误或保留的 slug 会返回 422 invalid_slug。实时部署、记录和分享会随应用一起转移，并且 publish.sh 会持续更新它（它跟踪应用 id）。旧 URL 会在 30 天内重定向（301）到新 URL，并保留给用户，之后会被释放 —— 在重命名用户已经分享的链接之前，请告知这一点。已删除应用的 URL 也被保留 30 天（访问会返回 404）。如果某个 slug 在过去 30 天内被另一个账户使用过，会返回 409 slug_taken（“最近被其他应用使用过”）。用户也可以在应用仪表板页面的 Settings 标签页中重命名它。

应用的显示名称（在仪表板和 GET /api/v1/apps 中显示）与其 URL 是分开的 —— 使用 PATCH {base}/api/v1/apps/{app_id} {"name": "Team todo"}（1–100 个字符）更改它；URL 不会改变。

分享

使用 POST /api/v1/apps/{app_id_or_slug}/shares（请求体 {"emails": ["[email protected]"]}）通过邮件邀请他人；使用 DELETE /api/v1/apps/{app_id_or_slug}/shares/{email} 移除某人。

新的分享对象会收到包含登录和注册链接的个人邀请邮件。检查响应中的 invite_delivery：accepted 表示邮件服务器已接受