Deploy with your AI agent

Two ways in, one platform

• TOSE CLI

  Available

  Connect

  Install @tosesh/tose from npm; the agent runs commands in its terminal with --json.

  npm install -g @tosesh/tose

  Sign-in

  A workspace API key in TOSE_API_KEY (optionally scoped), created in Settings → API Keys.

  What the agent can do

  Everything the CLI covers: create and deploy projects, status, logs, doctor, env, domains, databases, disks, templates, skills.

  CLI steps below

• TOSE MCP server

  Available

  Connect

  Add a remote MCP server with this URL in your client (Claude Code: claude mcp add --transport http tose https://app.tose.sh/mcp).

  https://app.tose.sh/mcp

  Sign-in

  OAuth 2.1 with PKCE: sign in to TOSE and approve the requested scopes. No API key.

  What the agent can do

  8 tools: list projects, deployment status and details, logs, incidents (read-only), plus deploy_project and rollback_deployment with write scopes.

  MCP connection guide

• TOSE Agent Skills

  Coming soon

  Connect

  A package of TOSE skills an agent installs to deploy, debug and roll back on TOSE. Not released yet.

  Sign-in

  Not available yet.

  What the agent can do

  Not available yet. The public Skills catalogue (JSON) below is a set of documents, not this package.

  View roadmap

What works today

Connect an agent

Over MCP: add a remote MCP server with the URL https://app.tose.sh/mcp in your client (Claude Code: claude mcp add --transport http tose https://app.tose.sh/mcp), sign in to TOSE and approve the scopes. Or use the CLI with an API key: MCP connection guide

1. 1. Create an API key

   Sign in to app.tose.sh, open your workspace, then Settings → API Keys → Create API Key. Only workspace owners and admins can create keys. Set an expiry if the agent only needs access for a while. The full key, starting with tose_sk_, is shown once.

2. 2. Give the key to the agent as a secret

   Set TOSE_API_KEY in the environment or secret store the agent runs with. Do not paste the key into a chat, a prompt, an issue or a commit: anything in the conversation can end up in logs and transcripts.

   export TOSE_API_KEY=…   # from your secret store, not typed into the chat

3. 3. Install the CLI and check access

   Node.js 18 or later is required. whoami shows which workspace the key belongs to without changing anything.

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

4. 4. Create the project once, then let the agent deploy

   tose up asks questions the first time (workspace, project, whether to push .env files), so run it yourself in a terminal or create the project in the dashboard. After that the agent can check the plan with --dry-run, deploy, wait until every pod is ready and read the logs on its own.

   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

What the key allows

• A key belongs to one workspace. A key created without scopes can do everything the CLI can do there: deploy, redeploy, stop projects, change environment variables, domains, databases and templates.
• The API accepts a list of scopes when it creates a key (for example logs:read or deployments:execute), and a scoped key cannot create a key with scopes it does not have. The dashboard form does not offer scopes yet, and the CLI cannot create keys. A request outside the key scopes fails with insufficient_scope.
• Give each agent its own key, with the fewest scopes it needs and an expiry, so you can revoke it without affecting anything else. These keys are for the CLI and the API; the MCP server uses OAuth and needs no API key.
• Revoke a key in Settings → API Keys. Requests made with a revoked or expired key are rejected.
• The API still checks workspace membership; the CLI cannot do more than the key allows.

What it costs

Agents spend from the same prepaid workspace wallet as you, at the normal hourly price for vCPU, RAM and disk. There is no separate charge for using the CLI. A new deploy, redeploy or rollback is refused while the wallet is empty, so top up first. When the wallet runs out, running projects are suspended and disks are kept; disks are billed even while a project is stopped. See prices

Copy safe project context

Paste this into your agent instructions (for example AGENTS.md or CLAUDE.md) and fill in the slugs. It tells the agent how to use TOSE without containing any secret.

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/commands/overview

When something fails

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

The variable is not visible to the process the agent runs. Set it in the agent environment or its secret settings, then start a new shell.

"API key must start with tose_sk_"

The value is not a TOSE API key. Copy the key again from Settings → API Keys.

"Only owner or admin can create API keys"

Ask a workspace owner to create a key for you or to make you an admin.

A key that worked is now rejected

It expired or was revoked. Create a new key and replace the TOSE_API_KEY secret.

Projects are suspended

The wallet balance ran out. Top up in the dashboard; disks are kept, and projects can be started again.

A deploy is refused with an insufficient-balance error (HTTP 402)

The wallet is empty. Top up in the dashboard, then deploy again. The agent should stop and report this instead of retrying.

insufficient_scope

The key does not carry the scope the command needs. Create a new key that includes it.

Documentation

• Install the CLI
• All CLI commands
• Getting started
• Pricing
• CLI release history (npm)