{"_id":"@bonya-ai/tyto-mcp","_rev":"7-9e9a34ac2a2471240d21b7f74f32ecb7","name":"@bonya-ai/tyto-mcp","dist-tags":{"latest":"1.1.3"},"versions":{"0.11.0":{"name":"@bonya-ai/tyto-mcp","version":"0.11.0","keywords":["tyto","mcp","model-context-protocol","ai","claude"],"author":{"name":"Bonya"},"license":"MIT","_id":"@bonya-ai/tyto-mcp@0.11.0","maintainers":[{"name":"bonyaai","email":"muhamedadly@gmail.com"}],"bin":{"tyto-mcp":"dist/index.js"},"dist":{"shasum":"43773c7efbf2baacb148e1525fe056b3a1780257","tarball":"https://registry.npmjs.org/@bonya-ai/tyto-mcp/-/tyto-mcp-0.11.0.tgz","fileCount":5,"integrity":"sha512-VJ2y99ZSbEXGFOjDGcd2J9XTAueWrAEqB4YkvCxcJGmnQmBnEOmVaprlaitiutg4mxx5yeXtNKG79vfve2k1fQ==","signatures":[{"sig":"MEUCIQC0kUmHFC2C2u/YbZfTg4D/oFUSvZl66hyx7NdGh80U6AIgQBU+hd2RDhC1baRzs/NxbIcBlAz0nzGF5eIJmIBsiHM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":88158},"type":"module","engines":{"node":">=18"},"gitHead":"7789b9ec5ce2eb3b558858c13d695d50f5529341","scripts":{"dev":"tsx src/index.ts","build":"tsup","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"bonyaai","email":"muhamedadly@gmail.com"},"_npmVersion":"11.9.0","description":"Model Context Protocol server for the Tyto API — manage nests, sessions, files, previews, snapshots, and keepalive holds from any MCP client.","directories":{},"_nodeVersion":"25.6.1","dependencies":{"tar":"^7.4.3","zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.5.0","typescript":"^5.8.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tyto-mcp_0.11.0_1781965304347_0.600688387848219","host":"s3://npm-registry-packages-npm-production"}},"0.12.0":{"name":"@bonya-ai/tyto-mcp","version":"0.12.0","keywords":["tyto","mcp","model-context-protocol","ai","claude"],"author":{"name":"Bonya"},"license":"MIT","_id":"@bonya-ai/tyto-mcp@0.12.0","maintainers":[{"name":"bonyaai","email":"muhamedadly@gmail.com"}],"bin":{"tyto-mcp":"dist/index.js"},"dist":{"shasum":"026f2ebc2a811facec35305e393583552b4547a7","tarball":"https://registry.npmjs.org/@bonya-ai/tyto-mcp/-/tyto-mcp-0.12.0.tgz","fileCount":5,"integrity":"sha512-RA+8ocL1NcHY7kCwsqE3ubx5lmItIv19feUnd00QsAzm7Y4D3GoHiuRNJHc4YjR7zdNMuvGwWtJ/eHfva8Y4WA==","signatures":[{"sig":"MEUCICuS4j6CBIUB4al+W29Ndmz4+BuDZqLmLdhhURDolN3AAiEA0M93feoY1GpUKdiYEK3ogYJL0XL6XRFBX360ibjEsxQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":88158},"type":"module","engines":{"node":">=18"},"gitHead":"36b3669f3f39b51bc55fbef94c923e2920eabdda","scripts":{"dev":"tsx src/index.ts","build":"tsup","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"bonyaai","email":"muhamedadly@gmail.com"},"_npmVersion":"11.9.0","description":"Model Context Protocol server for the Tyto API — manage nests, sessions, files, previews, snapshots, and keepalive holds from any MCP client.","directories":{},"_nodeVersion":"25.6.1","dependencies":{"tar":"^7.4.3","zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.5.0","typescript":"^5.8.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tyto-mcp_0.12.0_1782019248291_0.19083369007711015","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@bonya-ai/tyto-mcp","version":"1.0.0","keywords":["tyto","mcp","model-context-protocol","ai","claude"],"author":{"name":"Bonya"},"license":"MIT","_id":"@bonya-ai/tyto-mcp@1.0.0","maintainers":[{"name":"bonyaai","email":"muhamedadly@gmail.com"}],"bin":{"tyto-mcp":"dist/index.js"},"dist":{"shasum":"37dd2db2848c5fc55f358dc7445e08e91083c9ce","tarball":"https://registry.npmjs.org/@bonya-ai/tyto-mcp/-/tyto-mcp-1.0.0.tgz","fileCount":5,"integrity":"sha512-PSfNGIuNWu0X280OpL/w4tue6AWBU/bZjESsqu1JHYhyDlifw5gO32IEq8jGDgIQ/8RQMA8i7qXCmYUl6Fn7HQ==","signatures":[{"sig":"MEQCIDbKJdtEVjICXqziDAsrHlyUgMHriHlUh+c/WhxJYm/8AiBQnNa0YBga7C+1BM49izf1MXEZ5FuJ4GNnuG/7llvULg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":63654},"type":"module","engines":{"node":">=18"},"gitHead":"d69253e0eaa10dcbd126c0ebcfbc347a4051eeb3","scripts":{"dev":"tsx src/index.ts","build":"tsup","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"bonyaai","email":"muhamedadly@gmail.com"},"_npmVersion":"10.8.2","description":"Model Context Protocol server for the Bonya Compute REST API — manage sandboxes, sessions, files, and previews from any MCP client.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.5.0","typescript":"^5.8.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tyto-mcp_1.0.0_1787062567985_0.8258715120586724","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@bonya-ai/tyto-mcp","version":"1.1.0","keywords":["tyto","mcp","model-context-protocol","ai","claude"],"author":{"name":"Bonya"},"license":"MIT","_id":"@bonya-ai/tyto-mcp@1.1.0","maintainers":[{"name":"bonyaai","email":"muhamedadly@gmail.com"}],"bin":{"tyto-mcp":"dist/index.js"},"dist":{"shasum":"f66734bd372d6e0b69c0fced31190956efdc1fc4","tarball":"https://registry.npmjs.org/@bonya-ai/tyto-mcp/-/tyto-mcp-1.1.0.tgz","fileCount":5,"integrity":"sha512-TSI/beRHvXXpEfPcbH4LB+UEk+7K5mNV4i6pFNOZLW+A0X2+UWX2O+IKmcLq4XtJ1/yEQBiKS+iZVPNxM+j0Qw==","signatures":[{"sig":"MEUCIQCTekqT42HU3lNqJARMrjAYigPNR++1n1X+gGWhEHuPbAIgBa97vQwgoCa0dHfJ+9oj6IjNM/ccODXSiBf8N4MDqlQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCx7owQxR7iL9WXe6HbGbhuVRHAKrqI/y1qdrbvCEf0NQIhANR3zZ1G1vyVcIUJpY7N6v9waKRTcagxFbUYMLg1hC8f","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95623},"type":"module","engines":{"node":">=18"},"gitHead":"9f0e552d54dbf3d1c391cbc8e7e99a99c4a0c210","scripts":{"dev":"tsx src/index.ts","build":"tsup","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"bonyaai","email":"muhamedadly@gmail.com"},"_npmVersion":"10.8.2","description":"Model Context Protocol server for the Bonya Compute REST API — manage sandboxes, sessions, files, previews, and jobs from any MCP client.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.5.0","typescript":"^5.8.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tyto-mcp_1.1.0_1789587157324_0.49536264871058666","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@bonya-ai/tyto-mcp","version":"1.1.1","keywords":["tyto","mcp","model-context-protocol","ai","claude"],"author":{"name":"Bonya"},"license":"MIT","_id":"@bonya-ai/tyto-mcp@1.1.1","maintainers":[{"name":"bonyaai","email":"muhamedadly@gmail.com"}],"bin":{"tyto-mcp":"dist/index.js"},"dist":{"shasum":"f3d269c2da07165198969f390397821905a91402","tarball":"https://registry.npmjs.org/@bonya-ai/tyto-mcp/-/tyto-mcp-1.1.1.tgz","fileCount":5,"integrity":"sha512-BRR/z3G46RFQ1LWE+vwF0nF1VsnNLWB9Ab/ksbz1CQnolJIvmDEz4x9XxpIYsguo7py1n6dsCUdptHf4gG0dOw==","signatures":[{"sig":"MEUCIQDg3YI6dLIOaQr2cGf47f4SkZdMeqC3BpC4Llk+srIEmQIgA1ugushabRRF8Nbvuoe/iap+++cVNlsg2mpxWcfygYM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDDK/NbefgJT5xY38r1YdyxbdDDivxMO5tBDbyowQ4lJAIgZJpaoNsDFYYQ6kdK+2ZapBL3ScjuH6i8m7/HBq5v1X8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":101277},"type":"module","engines":{"node":">=18"},"gitHead":"a0f57b927175407d94acb0f40eead97e8d69c855","scripts":{"dev":"tsx src/index.ts","build":"tsup","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"bonyaai","email":"muhamedadly@gmail.com"},"_npmVersion":"10.8.2","description":"Model Context Protocol server for the Bonya Compute REST API — manage sandboxes, sessions, files, previews, and jobs from any MCP client.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.5.0","typescript":"^5.8.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tyto-mcp_1.1.1_1789630485340_0.1526210598529274","host":"s3://npm-registry-packages-npm-production"}},"1.1.2":{"name":"@bonya-ai/tyto-mcp","version":"1.1.2","keywords":["tyto","mcp","model-context-protocol","ai","claude"],"author":{"name":"Bonya"},"license":"MIT","_id":"@bonya-ai/tyto-mcp@1.1.2","maintainers":[{"name":"bonyaai","email":"muhamedadly@gmail.com"}],"bin":{"tyto-mcp":"dist/index.js"},"dist":{"shasum":"8a72c338326cecb48932cc1217793984fa0a262c","tarball":"https://registry.npmjs.org/@bonya-ai/tyto-mcp/-/tyto-mcp-1.1.2.tgz","fileCount":5,"integrity":"sha512-F2dj6VGw/SyQa90JcIeqa57bNBPWfctq/p5atot0oAio52I9W/sjXsx63o6dN+QlsvwswURw7likL6wJnz5cgA==","signatures":[{"sig":"MEYCIQD3hxs6qwm6LAywB+DopR9MOEMhnV3La08bkwMWkxgrRwIhANdkMrWuBAVdwULw19CCS1BkkwjuzDTHGWrlJBTXPMwx","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDeaepb2873kEHLBXnsIygR5OeH9g7gE0xskGj7y/4H+AIgBZfOUBwo4E0VRpRjK0rew9fkUwsSWn6R2KX7HnKImDE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":101693},"type":"module","engines":{"node":">=18"},"gitHead":"b0409db8b1efc83271b6b3bcd496962311e70977","scripts":{"dev":"tsx src/index.ts","build":"tsup","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"bonyaai","email":"muhamedadly@gmail.com"},"_npmVersion":"10.8.2","description":"Model Context Protocol server for the Bonya Compute REST API — manage sandboxes, sessions, files, previews, and jobs from any MCP client.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.5.0","typescript":"^5.8.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/tyto-mcp_1.1.2_1789902674026_0.24024054726051425","host":"s3://npm-registry-packages-npm-production"}},"1.1.3":{"_id":"@bonya-ai/tyto-mcp@1.1.3","bin":{"tyto-mcp":"dist/index.js"},"dist":{"shasum":"3ef609b4a0364001496d45f1163a5e7c8c0b3197","tarball":"https://registry.npmjs.org/@bonya-ai/tyto-mcp/-/tyto-mcp-1.1.3.tgz","fileCount":5,"integrity":"sha512-E3ZMAO3vdR8oFCT0x7eM5JZAAbVUtsf/TGBHPwzrhsWWBbVwj9Z2BWXOjj9qXjP/shMHjhHUky0+gtuTHWBw9w==","signatures":[{"sig":"MEYCIQDvZVXjEobKyW7CUoG9Or8j4PWj0fj7hWXkAn20vjpM2QIhAMHmYvGbXxo88AyowGpWum7REFMOk7D1pKXmzEoX1EPM","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDGySYSNW7WMqemd5UBkoh1SGwWRBzm2LnOrvR6WB6qcwIhAIS3b4HA4Kd3rPwhSYpMwf/m/Bvowmstutx1RN/k/eaS"}],"unpackedSize":101833},"name":"@bonya-ai/tyto-mcp","type":"module","author":{"name":"Bonya"},"engines":{"node":">=18"},"gitHead":"ca11bd6e4ea3cb4209c57d0ee393282964743bef","license":"MIT","scripts":{"dev":"tsx src/index.ts","build":"tsup","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","typecheck":"tsc --noEmit"},"version":"1.1.3","_npmUser":{"name":"bonyaai","email":"muhamedadly@gmail.com"},"keywords":["tyto","mcp","model-context-protocol","ai","claude"],"_npmVersion":"10.8.2","description":"Model Context Protocol server for the Bonya Compute REST API — manage sandboxes, sessions, files, previews, and jobs from any MCP client.","directories":{},"maintainers":[{"name":"bonyaai","email":"muhamedadly@gmail.com"}],"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.5.0","typescript":"^5.8.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tyto-mcp_1.1.3_1790227053664_0.7629789643445626"}}},"time":{"created":"2026-06-20T14:21:44.154Z","modified":"2026-09-24T05:17:33.994Z","0.11.0":"2026-06-20T14:21:44.504Z","0.12.0":"2026-06-21T05:20:48.431Z","1.0.0":"2026-08-18T14:16:08.194Z","1.1.0":"2026-09-16T19:32:37.418Z","1.1.1":"2026-09-17T07:34:45.459Z","1.1.2":"2026-09-20T11:11:14.131Z","1.1.3":"2026-09-24T05:17:33.757Z"},"author":{"name":"Bonya"},"license":"MIT","keywords":["tyto","mcp","model-context-protocol","ai","claude"],"description":"Model Context Protocol server for the Bonya Compute REST API — manage sandboxes, sessions, files, previews, and jobs from any MCP client.","maintainers":[{"name":"bonyaai","email":"muhamedadly@gmail.com"}],"readme":"# @bonya-ai/tyto-mcp\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the\n[Bonya Compute REST API](https://api.tyto.run) — gives any MCP client (Claude Desktop, Claude\nCode, Cursor, …) direct tool access to spin up sandboxes, run commands and scripts in them, work\nwith files, manage background sessions, expose preview URLs, and run one-off or scheduled jobs.\n\nSelf-contained: it talks to the Bonya Compute REST API directly over `fetch`, with no dependency\non the `@bonya-ai/tyto` or `tyto` SDKs.\n\n## Quick start\n\n1. Get an API key from the [dashboard](https://tyto.run) or via `tyto login` (see the\n   [`tyto` CLI](https://github.com/bonyai/tyto-cli)). It looks like `byk_...`.\n2. Add the server to your MCP client — see [Connect a client](#connect-a-client) below for\n   Claude, Codex, Cursor, and others. Always pass the key as an env var, never as a\n   command-line argument (it would end up in shell history and process listings).\n3. Restart your client. Try asking it to \"list my Tyto sandboxes\" or \"create a sandbox and run\n   `uname -a` in it\" — that exercises `sandbox_list`/`sandbox_create` + `sandbox_exec` end to end.\n\nNo local install is required (`npx` fetches it on demand); `npm install -g @bonya-ai/tyto-mcp`\nworks too if you'd rather have `tyto-mcp` on `PATH` directly.\n\n## Configuration\n\nEverything is read from the environment — there are no CLI flags:\n\n| Env var | Required | Default | Notes |\n|---|---|---|---|\n| `BONYA_API_KEY` | yes | — | Personal API key, `byk_...`. The server doesn't validate it at startup; the first tool call fails with a clear error if it's missing or wrong. |\n| `BONYA_ENDPOINT` | no | `https://api.tyto.run` | Override for self-hosted or staging deployments. |\n| `BONYA_ORGANIZATION_ID` | no | your personal organization | Sent as `X-Bonya-Organization-ID` on every request. Set this to act on behalf of a team organization instead of your own. |\n\n## Connect a client\n\nMost MCP clients read the same `mcpServers` JSON shape (see\n[`examples/mcp-config.json`](examples/mcp-config.json)):\n\n```json\n{\n  \"mcpServers\": {\n    \"tyto\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bonya-ai/tyto-mcp\"],\n      \"env\": { \"BONYA_API_KEY\": \"byk_your_key_here\" }\n    }\n  }\n}\n```\n\n**Claude Code**\n\n```bash\nclaude mcp add tyto --env BONYA_API_KEY=byk_your_key_here -- npx -y @bonya-ai/tyto-mcp\n```\n\nThis registers the server for the **current project directory only** — it won't show up in other\nprojects, and an already-running session needs a full restart (not just a retry) to pick it up\nsince MCP servers only connect at session startup. To make it available in every project instead,\nadd `-s user`:\n\n```bash\nclaude mcp add tyto -s user --env BONYA_API_KEY=byk_your_key_here -- npx -y @bonya-ai/tyto-mcp\n```\n\n**Claude Desktop** — Settings → Developer → Edit Config, and add the JSON above under\n`mcpServers` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`).\n\n**OpenAI Codex CLI** — supports local stdio MCP servers; add the same JSON block to Codex's MCP\nconfig (`codex mcp add`, or its config file — see the Codex CLI's own docs for the current path,\nsince this has moved between releases).\n\n**ChatGPT (web/desktop app)** — the web app only supports remote HTTPS MCP connectors, not local\nstdio processes, so this server can't be added there directly. The desktop app's MCP support\nfollows the same connector model; check OpenAI's current docs for whether local stdio servers are\nsupported in your version.\n\n**Cursor** — Settings → Tools & MCP → \"Add new MCP server\", or add the JSON above to\n`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).\n\n**Windsurf** — add the JSON above to `~/.codeium/windsurf/mcp_config.json`.\n\n**Cline (VS Code)** — Command Palette → \"Cline: Add MCP Server\", or edit its MCP settings JSON\nfrom the Cline panel (⚙️ → MCP Servers → Configure).\n\n**Gemini CLI** — `gemini mcp add tyto --env BONYA_API_KEY=byk_your_key_here -- npx -y @bonya-ai/tyto-mcp`\n\nAny other MCP-compatible client should work the same way: point it at `npx -y @bonya-ai/tyto-mcp`\n(or a global `tyto-mcp` install) as a stdio server, with `BONYA_API_KEY` in its environment.\n\n## What the tools cover\n\n31 tools across 6 groups. Every tool takes/returns plain JSON — ids, not objects, are how you\nchain calls together (e.g. `sandbox_create` → its `sandbox_id` → `sandbox_exec`).\n\n### Sandboxes — create, inspect, and manage compute environments\n`sandbox_create` · `sandbox_list` · `sandbox_get` · `sandbox_delete` · `sandbox_resume`\n\nA sandbox is created from a **template** (see `template_list` below). Creation is async by\ndefault — `sandbox_create` returns immediately with the sandbox in `CREATING` state; pass\n`wait: true` to block until it's ready. Sandboxes suspend automatically when idle;\n`sandbox_resume` is the only explicit lifecycle verb (there's no separate start/stop).\n\n```jsonc\n// sandbox_create\n{ \"template_id\": \"bonya-dev\", \"name\": \"scratch\", \"wait\": true }\n// → { \"sandbox\": { \"sandbox_id\": \"sbx-...\", \"state\": \"RUNNING\", ... } }\n```\n\n### Exec & filesystem — run commands and move files around\n`sandbox_exec` · `fs_read` · `fs_write` · `fs_list` · `fs_stat` · `fs_mkdir` · `fs_rename` · `fs_delete`\n\n`sandbox_exec` runs a command and blocks until it finishes (buffered stdout/stderr) — it's for\nshort, non-interactive commands. For anything long-running or interactive, use a **session**\ninstead (below). The API's WebSocket-based TTY `exec` and session `attach` endpoints aren't\nexposed here; they don't fit a request/response tool.\n\n```jsonc\n// sandbox_exec\n{ \"sandbox_id\": \"sbx-...\", \"cmd\": [\"cat\", \"/etc/os-release\"] }\n// → { \"exit_code\": 0, \"stdout\": \"...\", \"stderr\": \"\", \"output_encoding\": \"utf8\" }\n```\n\n### Sessions — long-lived background processes\n`session_create` · `session_list` · `session_kill`\n\nA session is a named process that keeps running after the tool call returns — a dev server, a\nlog tail, anything `sandbox_exec` shouldn't block on. Sessions are addressed by **name**, not id:\n`session_kill` takes `session_name`, not `name`.\n\n```jsonc\n// session_create\n{ \"sandbox_id\": \"sbx-...\", \"name\": \"dev-server\", \"cmd\": [\"npm\", \"run\", \"dev\"] }\n// session_kill\n{ \"sandbox_id\": \"sbx-...\", \"session_name\": \"dev-server\" }\n```\n\n### Previews — expose a port to the web\n`preview_create` · `preview_list` · `preview_delete`\n\nProxies a port inside a sandbox to a public HTTPS URL. `preview_create`'s result deliberately\nomits the one-time `capability_jws` capability token the API also returns — it's sensitive and\nnot needed for the plain (token-gated or public) preview URL.\n\n### Jobs — one-off runs, tracked to completion\n`job_create` · `job_list` · `job_get` · `job_cancel`\n\nA job is a managed run of a command or script — on a new sandbox (created and, by default,\ndeleted for you) or an existing one. `wait: false` (default) returns a `run_id` immediately;\n`wait: true` blocks for the result. There's no endpoint to edit a run in place: to \"edit and\nrerun\" one, call `job_get` for its stored `job` spec, change what you need, and pass it to\n`job_create` as a new run.\n\n```jsonc\n// job_create\n{\n  \"job\": {\n    \"new_sandbox\": { \"template_id\": \"bonya-dev\" },\n    \"cmd\": [\"./run-tests.sh\"],\n    \"wait\": true,\n    \"disposition\": \"delete\"\n  }\n}\n// → { \"run\": { \"run_id\": \"...\", \"status\": \"completed\", \"result\": { \"exit_code\": 0, ... } } }\n```\n\n### Job schedules — cron, interval, or one-shot triggers\n`job_schedule_create` · `job_schedule_list` · `job_schedule_get` · `job_schedule_update` ·\n`job_schedule_delete` · `job_schedule_pause` · `job_schedule_trigger`\n\nA schedule wraps a `job` spec (same shape as `job_create`'s) with timing: `cron_expressions`,\n`interval_s`, or a one-shot `run_at_unix_nanos` — exactly one of the three. `job_schedule_update`\nreplaces the whole schedule (timing + job), so re-send every field you want to keep, not just the\none you're changing. `job_schedule_trigger` fires a run immediately, ignoring the schedule's own\ntiming — useful for testing a schedule without waiting for it.\n\n### Templates\n`template_list`\n\nLists every `template_id`/version `sandbox_create` and `job_create` will accept, with metadata\n(OS, installed language stacks, which AI agent CLIs are preinstalled) to help pick one.\nSnapshots have no REST endpoints (gRPC SDK only), so they're out of scope for this server.\n\n## Gotchas\n\n- **Sandbox capacity is capped per account** (a low single-digit number by default). If\n  `sandbox_create` or `job_create`'s `new_sandbox` path returns `429 rate_limited: request\n  capacity is exhausted`, you're at your limit — free a slot with `sandbox_delete` or wait for a\n  job-created sandbox to finish, rather than retrying immediately.\n- **`session_kill`'s parameter is `session_name`**, not `name` — easy to get wrong since\n  `session_create` takes `name`.\n- **A job's `disposition` only applies to a sandbox the job itself created** (`new_sandbox`); it's\n  ignored for `existing_sandbox_id`. Default is `delete`, so a job-created sandbox disappears\n  automatically once the run ends, however it ends (including on `job_cancel`).\n- **Errors are RFC 9457 `problem+json`**, surfaced as `Tyto API error <status> (<code>):\n  <message>` — the `code` is the stable machine-readable part if you're branching on error type.\n\n## Develop\n\n```bash\nnpm install\nnpm run typecheck\nnpm run build          # emits dist/index.js (executable)\nnpm run dev            # run from source (tsx, no build step)\nnpm run inspect         # launch the MCP Inspector against the built server\n```\n\n```bash\nBONYA_API_KEY=byk_your_key_here npm run dev\n```\n\nAdding a new tool: each file under `src/tools/` exports one `register<X>Tools(server)` function\nregistered in `src/server.ts`; request/response types live in `src/types.ts`, hand-transcribed\nfrom the API's OpenAPI contract (this package intentionally doesn't import the generated SDK\ntypes, to stay a standalone, dependency-light server). Follow the existing pattern in\n`src/tools/sandboxes.ts` or `src/tools/jobs.ts` — local zod schemas per tool, a call through\n`getHttp()`, wrapped in the `tool()` helper from `src/format.ts` for uniform error handling.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}