TeamOnly文档

快速上手

你需要Node.js 20或更高版本。还没有方案？第一次登录时，你可以开始14天免费试用，无需绑卡，也可以订阅。你也可以在这里订阅。在新文件夹里，或者在已有的项目里：

1. npx teamonly init会添加一个起步应用，以及你的AI工具要遵循的说明。
2. npx teamonly login每台电脑运行一次。输入工作邮箱和我们发到邮箱的6位验证码。如果你的公司还没有方案，它会提供14天免费试用，试用马上开始；也可以选一个方案，在付款页面付款。不输入邮箱直接按回车，就用浏览器登录。
3. npx teamonly deploy会让应用在https://<app>.<company>.teamonly.app上线。

过程是这样的：

$npx teamonly init✔Added the TeamOnly skill, Cursor rules and SDK>做一个报销审批工具（AI正在做应用）$npx teamonly login✔Signed in as dana@acme.com$npx teamonly deploy✔Live at https://expenses.acme.teamonly.appOnly @acme.com accounts can sign in

首次部署会创建应用、它的数据库和文件存储。之后的部署会在同一个网址更新同一个应用。

CLI命令

npx teamonly login

在这台电脑上登录TeamOnly，每台电脑一次。输入工作邮箱和我们发来的6位验证码，或者按回车用浏览器登录。--email和--code不提问就完成同样的事，适合AI工具和脚本。

npx teamonly trial --company "Acme"

为你的公司开始14天免费试用，无需绑卡。在login之后、公司还没有方案时使用。每个公司邮箱域名只能试用一次。

npx teamonly subscribe --plan builder

订阅，或者在试用结束后重新开启应用。选择builder、team或business。它会打开付款页面，付款后在这里自动登录。

npx teamonly init

初始化这个文件夹：创建一个起步应用，或者在已有项目中加入给AI工具的TeamOnly说明（Claude Code技能、Cursor规则、AGENTS.md）和SDK。

npx teamonly deploy

构建应用并让它上线。首次部署时创建数据库和文件存储。会显示应用的网址。

npx teamonly access

查看谁能打开这个应用。加上only、add或remove和邮箱地址来使用名单，或用everyone开放给全公司。

npx teamonly roles

给大家分配应用里的角色，比如approver或finance。roles add approver dana@acme.com分配一个角色，roles remove收回角色，单独运行roles会列出谁有哪些角色。只限公司邮箱。

npx teamonly secrets set NAME

为这个应用保存一个密钥。系统会提示你输入值，所以它不会出现在你的命令行历史里。

npx teamonly logs

实时查看线上应用的请求、console.log输出和错误。按Ctrl+C停止。

npx teamonly whoami

显示你当前登录的身份、你的套餐和你的应用。

npx teamonly delete

删除线上应用及其数据库和文件。会先要求你输入应用名称。

npx teamonly logout

在这台电脑上退出TeamOnly。

SDK

你的API是一个Hono应用。SDK的中间件会为每个请求在c.var.ctx提供一个上下文：

ctx.user

已登录的人：email、name、首次部署应用的人才有的isOwner，以及roles，也就是这个人在这个应用里的角色。在你的代码运行之前由TeamOnly验证。永远不要自己从标头读取身份。

ctx.db

这个应用自己的SQL数据库（SQLite，运行在Cloudflare D1上）。首次部署时创建。

ctx.files

这个应用的文件存储：put、get、list、delete。

ctx.secrets

用npx teamonly secrets set设置的值。用ctx.secrets.get(name)读取。

ctx.email

给同事发邮件：send({ to, subject, text, html?, replyTo? })。见邮件。

ctx.schedule

TeamOnly运行定时任务时，这里是任务的名称，其他时候是undefined。见定时任务。

在浏览器里，teamonly/react中的useUser()会返回{ email, name, roles }。

import { Hono } from 'hono'
import { teamonly, type TeamOnly } from 'teamonly/server'

const app = new Hono<TeamOnly>()
app.use('*', teamonly())

// Who is signed in. Verified before your code runs.
app.get('/api/me', (c) => {
  return c.json(c.var.ctx.user) // { email: 'dana@acme.com', name: 'Dana Okafor', isOwner: false, roles: ['approver'] }
})

// Save to this app's own database.
app.post('/api/expenses', async (c) => {
  const { db, user } = c.var.ctx
  const { amount, reason } = await c.req.json()
  await db
    .prepare('INSERT INTO expenses (amount, reason, submitted_by) VALUES (?, ?, ?)')
    .bind(amount, reason, user.email)
    .run()
  return c.json({ ok: true })
})

// Store an uploaded receipt in this app's file storage.
app.put('/api/receipts/:id', async (c) => {
  await c.var.ctx.files.put(`receipts/${c.req.param('id')}`, c.req.raw.body)
  return c.json({ ok: true })
})

// Read a secret set with: npx teamonly secrets set QUICKBOOKS_KEY
app.get('/api/sync', async (c) => {
  const key = c.var.ctx.secrets.get('QUICKBOOKS_KEY')
  // ...
})

export default app

邮件

应用可以用ctx.email.send()给你公司里的人发邮件，比如告诉审批人有一笔报销在等待审批。

// Tell the approver an expense is waiting.
await c.var.ctx.email.send({
  to: 'priya@acme.com',   // one address or a list, up to 50
  subject: 'An expense is waiting for you',
  text: 'Dana sent a $42 expense. Review it: https://expenses.acme.teamonly.app',
})

• 只能发到你公司自己的邮箱域名下的地址，也就是能登录的那些人。其他地址会被拒绝，什么都不会发出。
• 邮件从notify@teamonly.app发出，发件人是你公司里的这个应用，比如“Expenses at Acme”。回复会发给应用的负责人，除非你设置了replyTo（同样必须是公司邮箱）。
• 每封邮件里都有一行说明是哪个应用发的。
• 每个应用的限制：每小时100个收件人，每天500个，每封邮件最多50个收件人。
• 控制台里的应用页面会显示它过去30天发了多少封邮件。
• 在本地用npm run dev时，邮件会打印在终端里，不会真的发出。
• 不支持给公司以外的人发邮件。

定时任务

每日汇总、提醒和月末报告这类工作，把任务列在teamonly.json里。TeamOnly会在设定的时间调用对应的路由。

{
  "name": "expenses",
  "timezone": "America/New_York",
  "schedules": [
    { "name": "daily-digest", "cron": "0 9 * * 1-5", "path": "/api/cron/daily-digest" }
  ]
}

import { scheduled } from 'teamonly/server'

// Runs at 9am New York time, Monday to Friday.
app.post('/api/cron/daily-digest', scheduled(async (c) => {
  const { db, email } = c.var.ctx
  // ...find what is waiting, then email each approver
  return c.json({ ok: true })
}))

• cron有五个字段：分钟、小时、日期、月份、星期几。任务按5分钟刻度运行，所以分钟必须是5的倍数。
• timezone可选，默认是UTC。
• 用teamonly/server里的scheduled(...)包住这个路由。有人直接打开这个网址会得到404。
• 控制台里的应用页面会显示每个任务最近一次运行的时间，以及是否成功。
• 免费试用结束后，任务会暂停。

角色

approver、finance或admin这类角色保存在TeamOnly里，不在你的代码里。应用的负责人或管理员可以在控制台的应用页面分配角色，也可以用npx teamonly roles。只限公司邮箱。

$npx teamonly roles add approver dana@acme.com✔Gave dana@acme.com the role approverapprover: dana@acme.com

// Only approvers can approve.
app.post('/api/expenses/:id/approve', async (c) => {
  const { user } = c.var.ctx
  if (!user.roles.includes('approver')) return c.json({ error: 'Approvers only' }, 403)
  // ...
})

应用通过ctx.user.roles读取角色，并自己决定每个角色能做什么。依然不用写任何登录代码。

技能文件

init会为Claude Code添加一个技能文件，并为Cursor添加内容相同的规则文件。你的AI工具在写代码前会先读它。它会教AI：

• 唯一支持的应用结构（见下文），并且不要超出这个范围。
• 用ctx.user获取身份，绝不自己写登录、注册或密码页面。
• 用ctx.db和ctx.files，而不是另外加数据库服务、Express、Supabase或Firebase。
• 把API密钥放在ctx.secrets里，绝不写进代码。
• 用ctx.email发邮件，把定时的工作做成定时任务，并在服务器上检查ctx.user.roles。
• 如何运行deploy，并修复它报告的问题。

目的就是让首次部署成功。如果你的AI总想用我们不支持的东西，请告诉我们，那是技能文件的问题。

MCP服务器

teamonly包还可以作为MCP服务器运行，面向更习惯用工具、而不是终端命令的AI工具，比如Claude Desktop或没有终端的Cursor智能体。它在你的电脑上运行，因为部署时要读取你项目里的文件。用下面的命令把它添加到Claude Code：

$claude mcp add teamonly -- npx -y teamonly mcp

• Cursor、Claude Desktop和Windsurf：把{ "mcpServers": { "teamonly": { "command": "npx", "args": ["-y", "teamonly", "mcp"] } } }加到它们的MCP配置里。
• VS Code：在.vscode/mcp.json中键名是servers，并加上"type": "stdio"。
• 它的12个工具：get_app_rules、init、deploy、status、logs、access、roles、set_secret、sign_in、start_trial、subscribe、delete_app。
• 以dev.teamonly/teamonly的名字收录在官方MCP Registry中。

技能文件和规则仍然是你的AI学习这套技术栈的主要方式，CLI也和以前完全一样能用。每个工具的配置方法，以及Cursor的一键安装按钮：TeamOnly MCP服务器。

支持的应用结构

• 前端：React，用Vite构建，以静态文件提供。
• API：一个用TypeScript或JavaScript写的Hono应用，放在/api下，和前端同一个网址。
• 运行环境：Cloudflare Workers。标准Web API；大部分Node内置模块可通过兼容层使用，但不支持原生模块或长时间运行的进程。
• 不支持：Python、Ruby、PHP、Docker容器、WebSockets和实时更新、后台进程、给公司以外的人发邮件、连接公司内网里的服务器、自定义域名、公开应用。

限制

目前的限制：

• Builder套餐：1位搭建者，3个应用。Team套餐：搭建者和应用数量不限。
• 每个应用的数据库和文件存储遵循Cloudflare D1和R2的限制。
• 请求的CPU时间和内存遵循Cloudflare Workers的限制。

想了解整体是怎么运作的：使用流程和安全。