{"_id":"@alineo-labs/sandbox","_rev":"5-41fde340cd5728702580f6cde777fc4a","name":"@alineo-labs/sandbox","dist-tags":{"latest":"0.4.2"},"versions":{"0.2.0":{"name":"@alineo-labs/sandbox","version":"0.2.0","license":"Apache-2.0","_id":"@alineo-labs/sandbox@0.2.0","maintainers":[{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"}],"homepage":"https://github.com/DrejT/alineo#readme","bugs":{"url":"https://github.com/DrejT/alineo/issues"},"dist":{"shasum":"822581af38635071550b9d1ee1e6ae49438a163d","tarball":"https://registry.npmjs.org/@alineo-labs/sandbox/-/sandbox-0.2.0.tgz","fileCount":4,"integrity":"sha512-0smOTr/m7FOVm7DfT2EPiNF8edBSMruFuaR/v21cUVD5V+27iQz/Zc7fgej7HCSbnG2UPvoJAm0CXZ6ODnTz5w==","signatures":[{"sig":"MEQCIGW3YEd6Au80obFkvX5tjN5/WdULv6rXuj225fsDzKyXAiAJgL6mR3N6nhgp4zUdq4uqDXktI74IFTsjEg0FIystPg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alineo-labs%2fsandbox@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":45174},"main":"./src/index.ts","type":"module","types":"./src/index.ts","exports":{".":{"types":"./src/index.ts","import":"./dist/index.mjs"}},"gitHead":"68d77069e3789b1d20291f0ba9a21a2c1345d183","scripts":{"test":"vitest run","build":"tsdown","test:watch":"vitest"},"_npmUser":{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"},"repository":{"url":"git+https://github.com/DrejT/alineo.git","type":"git","directory":"packages/sdks/typescript"},"_npmVersion":"10.9.8","description":"Sandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"@alineo-labs/core":"0.2.0","@alineo-labs/opensandbox":"0.1.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"0.22.3","vitest":"4.1.9","bun-types":"1.3.14","typescript":"6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/sandbox_0.2.0_1787410952307_0.6819071278073305","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@alineo-labs/sandbox","version":"0.3.0","license":"Apache-2.0","_id":"@alineo-labs/sandbox@0.3.0","maintainers":[{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"}],"homepage":"https://github.com/DrejT/alineo#readme","bugs":{"url":"https://github.com/DrejT/alineo/issues"},"dist":{"shasum":"06114d359fd520cfb78c55d0bd75825659f559ba","tarball":"https://registry.npmjs.org/@alineo-labs/sandbox/-/sandbox-0.3.0.tgz","fileCount":4,"integrity":"sha512-3TzKIyi2RbaLSZqIM3JWj/7PzS814Ztfj25IV5cPc9Nw2iMOkmsFnAzwJF6pbBKblYP+w2YnyvCIojzMuPuqhw==","signatures":[{"sig":"MEYCIQC5jHR39R6ZHwA27wQaKfUTXxbsWiKQeVuxCkUthwZkHQIhAK0YkJPAmo9+En16Md9lmgudwpI0qsBS5QmwVEoUZJxO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alineo-labs%2fsandbox@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":52520},"main":"./src/index.ts","type":"module","types":"./src/index.ts","exports":{".":{"types":"./src/index.ts","import":"./dist/index.mjs"}},"gitHead":"8bd54ff750438ee67b032d48e20abfade662099a","scripts":{"test":"vitest run","build":"tsdown","test:watch":"vitest"},"_npmUser":{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"},"repository":{"url":"git+https://github.com/DrejT/alineo.git","type":"git","directory":"packages/sdks/typescript"},"_npmVersion":"10.9.8","description":"Sandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"@alineo-labs/core":"0.3.0","@alineo-labs/vault":"0.2.0","@alineo-labs/opensandbox":"0.2.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"0.22.3","vitest":"4.1.9","bun-types":"1.3.14","typescript":"6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/sandbox_0.3.0_1788102919603_0.9494509190930673","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@alineo-labs/sandbox","version":"0.4.0","license":"Apache-2.0","_id":"@alineo-labs/sandbox@0.4.0","maintainers":[{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"}],"homepage":"https://github.com/DrejT/alineo#readme","bugs":{"url":"https://github.com/DrejT/alineo/issues"},"dist":{"shasum":"2dd757d04ba5d1135ddad1879ab1f06c92a9ec56","tarball":"https://registry.npmjs.org/@alineo-labs/sandbox/-/sandbox-0.4.0.tgz","fileCount":4,"integrity":"sha512-xX7mahvq9jt5SY9EtNj4gKJ95fy/p6k/N7AOYFWkmwZS0x0TrSNPHgdGXmkD04n+95aM0Ndawgu3uIaKpLHU2Q==","signatures":[{"sig":"MEUCIEjb2QMYWfOR3sx/UPlHmY4SgBljS4Zs7hG647/CoxNHAiEAlCufLO33DNtm1P73TYoYYG61CiBQpUeQJwkhLWx7LGA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alineo-labs%2fsandbox@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":54044},"main":"./src/index.ts","type":"module","types":"./src/index.ts","exports":{".":{"types":"./src/index.ts","import":"./dist/index.mjs"}},"gitHead":"0a4efc6f2b7e9cc4b02acf303b2439788d55907c","scripts":{"test":"vitest run","build":"tsdown","test:watch":"vitest"},"_npmUser":{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"},"repository":{"url":"git+https://github.com/DrejT/alineo.git","type":"git","directory":"packages/sdks/typescript"},"_npmVersion":"10.9.8","description":"Sandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"@alineo-labs/core":"0.4.0","@alineo-labs/vault":"0.3.0","@alineo-labs/opensandbox":"0.3.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"0.22.3","vitest":"4.1.9","bun-types":"1.3.14","typescript":"6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/sandbox_0.4.0_1788628605335_0.9144345874506004","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@alineo-labs/sandbox","version":"0.4.1","license":"Apache-2.0","_id":"@alineo-labs/sandbox@0.4.1","maintainers":[{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"}],"homepage":"https://github.com/DrejT/alineo#readme","bugs":{"url":"https://github.com/DrejT/alineo/issues"},"dist":{"shasum":"6ff2a078453d845164c954abeea9b2c6f227a8f2","tarball":"https://registry.npmjs.org/@alineo-labs/sandbox/-/sandbox-0.4.1.tgz","fileCount":4,"integrity":"sha512-0ST8Ai/8vUxSKgoMag0VsmQCBs2XK8tNVvY8Lx7DFq92egOAUBCEY2ywhrj98C6KfGVyi5XxDS070A0GZ/5xmA==","signatures":[{"sig":"MEQCIH9LfdOIEPRneFlRExoTDRCJAHqVV1suVqyBoOfjkue7AiB+7p3EMqOQ6sA28VsfJIZRk+4xUJ5zkoIy676TTUzUww==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alineo-labs%2fsandbox@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":54049},"main":"./src/index.ts","type":"module","types":"./src/index.ts","exports":{".":{"types":"./src/index.ts","import":"./dist/index.mjs"}},"gitHead":"d3323f599d24aade22d8e26ed1ae695e1d236280","scripts":{"test":"vitest run","build":"tsdown","test:watch":"vitest"},"_npmUser":{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"},"repository":{"url":"git+https://github.com/DrejT/alineo.git","type":"git","directory":"packages/sdks/typescript"},"_npmVersion":"10.9.8","description":"Sandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"@alineo-labs/core":"0.4.1","@alineo-labs/vault":"0.3.1","@alineo-labs/opensandbox":"0.3.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"0.23.0","vitest":"5.0.0","bun-types":"1.4.2","typescript":"6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/sandbox_0.4.1_1789325263192_0.2591793085299896","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@alineo-labs/sandbox","version":"0.4.2","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/DrejT/alineo.git","directory":"packages/sdks/typescript"},"type":"module","main":"./src/index.ts","types":"./src/index.ts","exports":{".":{"import":"./dist/index.mjs","types":"./src/index.ts"}},"publishConfig":{"access":"public","provenance":true},"scripts":{"build":"tsdown","test":"vitest run","test:watch":"vitest"},"dependencies":{"@alineo-labs/core":"0.4.1","@alineo-labs/opensandbox":"0.3.0","@alineo-labs/vault":"0.3.1"},"devDependencies":{"bun-types":"1.4.2","tsdown":"0.23.0","typescript":"6.0.3","vitest":"5.0.0"},"_id":"@alineo-labs/sandbox@0.4.2","gitHead":"f93158d7a5153f9889db2e32e001b12cba151d6c","description":"Sandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.","bugs":{"url":"https://github.com/DrejT/alineo/issues"},"homepage":"https://github.com/DrejT/alineo#readme","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-jwTHR/hDx2lK9LOUcVvsCBNK+qwD1CGZFyqFVjP1E8PMK0HIMB/JiD3FgtzixiGTv3NNExPNTdUq/VaMwKp/lQ==","shasum":"0fb7c05d13117dafd74c91d8b9d8a5f431da346d","tarball":"https://registry.npmjs.org/@alineo-labs/sandbox/-/sandbox-0.4.2.tgz","fileCount":4,"unpackedSize":54561,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alineo-labs%2fsandbox@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDdzUQsvY92CY/oOWv+WGtoTvrKdE97Lwvd186D+h/AigIhANuzm8GjRYsXHLt8dsCFpaxUl911QPM+Ik1JSD/x3JSQ"}]},"_npmUser":{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"},"directories":{},"maintainers":[{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sandbox_0.4.2_1789538437465_0.431681883761482"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-22T15:02:32.027Z","modified":"2026-09-16T06:00:38.494Z","0.2.0":"2026-08-22T15:02:32.461Z","0.3.0":"2026-08-30T15:15:19.730Z","0.4.0":"2026-09-05T17:16:45.478Z","0.4.1":"2026-09-13T18:47:43.340Z","0.4.2":"2026-09-16T06:00:37.578Z"},"bugs":{"url":"https://github.com/DrejT/alineo/issues"},"license":"Apache-2.0","homepage":"https://github.com/DrejT/alineo#readme","repository":{"type":"git","url":"git+https://github.com/DrejT/alineo.git","directory":"packages/sdks/typescript"},"description":"Sandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.","maintainers":[{"name":"drejtoolwell","email":"vivekpatel4049@gmail.com"}],"readme":"# @alineo-labs/sandbox\n\nSandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.\n\n```bash\nbun add @alineo-labs/sandbox @alineo-labs/sqlite\n```\n\n**[Full documentation →](https://docs.alineo.tech/docs/core)**\n\n---\n\n## Quickstart\n\n```ts\nimport { Sandbox } from \"@alineo-labs/sandbox\";\nimport { SQLiteAdapter } from \"@alineo-labs/sqlite\";\n\nconst client = new Sandbox({\n  baseUrl: \"http://localhost:8080\",\n  adapter: new SQLiteAdapter(\"./ledger.db\"),\n});\n\nconst sb = await client.sandbox({\n  image: \"ubuntu:22.04\",\n  resources: { cpu: \"500m\", memory: \"512Mi\" },\n});\n\nconst { stdout } = await sb.exec(\"node --version\");\nconsole.log(stdout); // v20.x.x\n\nawait sb.close();\n```\n\n---\n\n## Core concepts\n\n**Sandbox as object** — `client.sandbox()` returns a live `Sandbox`. Call exec, file ops, checkpoint, and fork directly on it. No special API needed for multiple sandboxes — just multiple variables.\n\n**ExecHandle** — `sb.exec(\"cmd\")` returns an `ExecHandle` — a `PromiseLike<ExecResult>` with streaming built in.\n\n```ts\n// Await result\nconst { stdout, stderr, exitCode } = await sb.exec(\"npm test\");\n\n// Stream to a writable\nawait sb.exec(\"npm run build\").pipe(process.stdout);\n\n// Async iteration\nfor await (const chunk of sb.exec(\"npm run build\").stdout()) {\n  process.stdout.write(chunk);\n}\n```\n\n**Durable ledger** — every exec is written to the storage adapter. `client.resume(sandboxId)` restores the container and replays cached results from before the last checkpoint.\n\n---\n\n## File operations\n\n```ts\nawait sb.writeFile(\"/app/main.py\", \"print('hello')\");\nconst content = await sb.readFile(\"/app/main.py\");\n\nawait sb.createDirectory(\"/app/dist\");\nconst info = await sb.getFileInfo(\"/app/main.py\");\n\n// In-place patch\nawait sb.replaceInFiles([{ path: \"/app/main.py\", old: \"hello\", new: \"world\" }]);\n\n// Search, move, delete\nconst files = await sb.searchFiles(\"*.py\", \"/app\");\nawait sb.moveFile(\"/tmp/out.txt\", \"/app/out.txt\");\nawait sb.deleteFile(\"/app/main.py\");\n\n// Copy to another sandbox\nawait sb.transfer(\"/app/output.json\", anotherSb);\n```\n\n## Checkpoint and resume\n\n```ts\nconst sb = await client.sandbox({\n  image: \"ubuntu:22.04\",\n  resources: { cpu: \"500m\", memory: \"512Mi\" },\n});\n\nawait sb.exec(\"apt-get install -y curl\");\nawait sb.checkpoint(\"after-setup\");\nawait sb.close();\n\n// Later — or after a crash\nconst restored = await client.resume(sb.sandboxId);\nawait restored.exec(\"curl https://example.com\").pipe(process.stdout);\nawait restored.close();\n```\n\n## Environments\n\nDefine a named environment with a setup recipe. Built once, restored from snapshot on every subsequent call.\n\n```ts\nconst env = client.environment(\"python-data\", {\n  image: \"python:3.11-slim\",\n  resources: { cpu: \"1\", memory: \"1Gi\" },\n  setup: async (sb) => {\n    await sb.exec(\"pip install numpy pandas scikit-learn\");\n  },\n});\n\nconst sb = await env.sandbox(); // ~2s after first run\nawait sb.exec(\"python3 -c 'import pandas; print(pandas.__version__)'\").pipe(process.stdout);\nawait sb.close();\n```\n\n## Forking\n\n```ts\nawait sb.exec(\"npm ci\");\nconst fork = await sb.fork();\n\nawait Promise.all([\n  sb.exec(\"npm test\").pipe(process.stdout),\n  fork.exec(\"npm run build\").pipe(process.stdout),\n]);\n\nawait Promise.all([sb.close(), fork.close()]);\n```\n\n## Error handling\n\n```ts\nimport { CommandError } from \"@alineo-labs/sandbox\";\n\ntry {\n  await sb.exec(\"exit 1\"); // strict: true by default\n} catch (e) {\n  if (e instanceof CommandError) {\n    console.log(e.exitCode, e.command);\n  }\n}\n\n// Opt out of strict mode\nconst { exitCode } = await sb.exec(\"exit 1\", { strict: false });\n```\n\n---\n\n## Configuration\n\n```ts\nconst client = new Sandbox({\n  baseUrl: \"http://localhost:8080\", // OpenSandbox server URL\n  apiKey: \"\", // API key (empty for local dev)\n  adapter: new SQLiteAdapter(\"./alineo.db\"),\n  maxConcurrency: 4, // cap simultaneous active sandboxes\n  useServerProxy: true, // required when server runs in Docker via alineo init\n});\n```\n\n---\n\n## Local setup\n\nRequires a running [OpenSandbox](https://open-sandbox.ai) instance:\n\n```bash\nbunx alineo-cli init        # starts OpenSandbox in Docker, recommended\n# or\nuvx opensandbox-server # manual, see docs for ~/.sandbox.toml config\n```\n\n---\n\n## License\n\nApache 2.0\n","readmeFilename":"README.md"}