Deploy bằng AI agent

Hai lối vào, một nền tảng

• TOSE CLI

  Có sẵn

  Kết nối

  Cài @tosesh/tose từ npm; agent chạy lệnh trong terminal với --json.

  npm install -g @tosesh/tose

  Xác thực

  API key của workspace trong TOSE_API_KEY (có thể giới hạn scope), tạo tại Settings → API Keys.

  Agent làm được gì

  Mọi thứ CLI hỗ trợ: tạo và deploy project, status, log, doctor, env, domain, database, ổ đĩa, template, skills.

  Các bước CLI bên dưới

• TOSE MCP server

  Có sẵn

  Kết nối

  Thêm remote MCP server với URL này vào client (Claude Code: claude mcp add --transport http tose https://app.tose.sh/mcp).

  https://app.tose.sh/mcp

  Xác thực

  OAuth 2.1 với PKCE: đăng nhập TOSE và duyệt các scope được yêu cầu. Không cần API key.

  Agent làm được gì

  8 tool: liệt kê project, trạng thái và chi tiết deployment, log, incident (chỉ đọc), cùng deploy_project và rollback_deployment khi có scope ghi.

  Hướng dẫn kết nối MCP

• TOSE Agent Skills

  Coming soon

  Kết nối

  Gói skill của TOSE để agent cài vào, giúp deploy, debug và rollback trên TOSE. Chưa phát hành.

  Xác thực

  Chưa có.

  Agent làm được gì

  Chưa có. Skills catalogue công khai (JSON) bên dưới là tập tài liệu, không phải gói này.

  Xem roadmap

Những gì dùng được hôm nay

Kết nối agent

Qua MCP: thêm remote MCP server với URL https://app.tose.sh/mcp vào client (Claude Code: claude mcp add --transport http tose https://app.tose.sh/mcp), đăng nhập TOSE và duyệt scope. Hoặc dùng CLI với API key: Hướng dẫn kết nối MCP

1. 1. Tạo API key

   Đăng nhập app.tose.sh, mở workspace, vào Settings → API Keys → Create API Key. Chỉ owner và admin của workspace tạo được key. Đặt thời hạn nếu agent chỉ cần quyền truy cập trong một thời gian. Key đầy đủ, bắt đầu bằng tose_sk_, chỉ hiện một lần.

2. 2. Đưa key cho agent dưới dạng secret

   Đặt TOSE_API_KEY trong biến môi trường hoặc kho secret mà agent chạy cùng. Đừng dán key vào chat, prompt, issue hay commit: mọi thứ trong hội thoại đều có thể nằm lại trong log và transcript.

   export TOSE_API_KEY=…   # lấy từ kho secret, không gõ vào chat

3. 3. Cài CLI và kiểm tra quyền truy cập

   Cần Node.js 18 trở lên. Lệnh whoami cho biết key thuộc workspace nào mà không thay đổi gì.

   npm install -g @tosesh/tose
   tose whoami --json
   tose capabilities --json

4. 4. Tạo project một lần, sau đó để agent deploy

   Lần đầu tose up sẽ hỏi workspace, project và có đẩy file .env hay không, nên hãy tự chạy nó trong terminal hoặc tạo project trên dashboard. Sau đó agent tự xem kế hoạch bằng --dry-run, deploy, chờ mọi pod sẵn sàng và đọc log được.

   tose deploy my-workspace/my-app --dry-run --json
   tose deploy my-workspace/my-app --wait --json
   tose status my-workspace/my-app --json
   tose logs my-workspace/my-app -n 100
   tose doctor my-workspace/my-app --json

app.tose.sh

Key được phép làm gì

• Mỗi key thuộc một workspace. Key tạo không kèm scope làm được mọi thứ CLI làm được trong đó: deploy, redeploy, dừng project, đổi biến môi trường, domain, database và template.
• API nhận danh sách scope khi tạo key (ví dụ logs:read hoặc deployments:execute), và key có scope không thể tạo key có scope mà nó không có. Form trên dashboard chưa có tuỳ chọn scope và CLI không tạo được key. Yêu cầu vượt scope sẽ lỗi insufficient_scope.
• Hãy cấp cho mỗi agent một key riêng, ít scope nhất có thể và có thời hạn, để thu hồi mà không ảnh hưởng chỗ khác. Key này dành cho CLI và API; MCP server dùng OAuth và không cần API key.
• Thu hồi key tại Settings → API Keys. Yêu cầu dùng key đã thu hồi hoặc hết hạn sẽ bị từ chối.
• API vẫn kiểm tra quyền thành viên workspace; CLI không thể làm nhiều hơn những gì key cho phép.

Chi phí

Agent tiêu tiền từ cùng ví trả trước của workspace, theo giá vCPU, RAM và ổ đĩa tính theo giờ như bình thường. Dùng CLI không mất phí riêng. Deploy, redeploy hoặc rollback mới sẽ bị từ chối khi ví hết tiền, nên hãy nạp tiền trước. Khi hết số dư, project đang chạy bị tạm dừng và ổ đĩa vẫn được giữ; ổ đĩa vẫn tính phí kể cả khi project đã dừng. Xem bảng giá

Sao chép context an toàn cho project

Dán đoạn này vào chỉ dẫn cho agent (ví dụ AGENTS.md hoặc CLAUDE.md) rồi điền slug. Nó hướng dẫn agent dùng TOSE mà không chứa bất kỳ secret nào.

TOSE deployment context
- CLI: @tosesh/tose from npm. Add --json to every command and read the JSON result.
- Auth: the API key is in the TOSE_API_KEY environment variable. Never print, log, echo or commit it.
- Workspace: <workspace-slug>
- Project: <project-slug>
- Check first: tose deploy <workspace-slug>/<project-slug> --dry-run --json
- Deploy: tose deploy <workspace-slug>/<project-slug> --wait --json
- Status: tose status <workspace-slug>/<project-slug> --json
- Logs: tose logs <workspace-slug>/<project-slug> -n 100
- Diagnose: tose doctor <workspace-slug>/<project-slug> --json
- Ask me before running: tose down, tose env rm, tose domain rm, tose disk delete.
- Every deployment is paid from the workspace wallet by the hour. If the wallet is empty a new deploy is refused: tell me to top up, do not retry.
- Docs: https://docs.tose.sh/vi/commands/overview

Khi có lỗi

"No API key found. Set TOSE_API_KEY, pipe it with --api-key-stdin, or run `tose login`."

Tiến trình agent không thấy biến này. Đặt nó trong môi trường hoặc phần cài đặt secret của agent, rồi mở shell mới.

"API key must start with tose_sk_"

Giá trị này không phải API key của TOSE. Sao chép lại key từ Settings → API Keys.

"Only owner or admin can create API keys"

Nhờ owner của workspace tạo key giúp bạn hoặc cấp quyền admin cho bạn.

Key từng dùng được nay bị từ chối

Key đã hết hạn hoặc bị thu hồi. Tạo key mới và thay secret TOSE_API_KEY.

Project bị tạm dừng

Ví đã hết số dư. Nạp tiền trên dashboard; ổ đĩa vẫn được giữ và project có thể chạy lại.

Deploy bị từ chối vì không đủ số dư (HTTP 402)

Ví đang trống. Nạp tiền trên dashboard rồi deploy lại. Agent nên dừng và báo lại thay vì thử lại.

insufficient_scope

Key không có scope mà lệnh cần. Tạo key mới có scope đó.

Tài liệu

• Cài đặt CLI
• Tất cả lệnh CLI
• Bắt đầu
• Bảng giá
• Lịch sử phát hành CLI (npm)