@enclave-run/sdk 0.0.0-dev

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 FOUNDRYLABS, INC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @enclave-run/sdk
+
+JavaScript/TypeScript SDK for [Enclave](https://enclave.run) — secure, isolated cloud sandboxes for AI agents and AI apps.
+
+A sandbox is a persistent Linux VM your code can treat as a remote execution target: run shell commands, read and write files, start long-running processes, forward ports, or build templates. Sandboxes start in ~150 ms and hibernate to disk on timeout.
+
+## Install
+
+```bash
+npm install @enclave-run/sdk
+```
+
+Set your API key:
+
+```bash
+export ENCLAVE_API_KEY=enclave_...
+```
+
+Get one from [app.enclave.run](https://app.enclave.run).
+
+## Quick start
+
+```ts
+import { Sandbox } from "@enclave-run/sdk";
+
+const sandbox = await Sandbox.create();
+
+const result = await sandbox.commands.run("echo hello");
+console.log(result.stdout); // "hello\n"
+
+await sandbox.files.write("/tmp/note.txt", "persisted");
+const contents = await sandbox.files.read("/tmp/note.txt");
+
+await sandbox.kill();
+```
+
+## Core surface
+
+| Area | API |
+|------|-----|
+| Lifecycle | `Sandbox.create`, `sandbox.connect`, `sandbox.pause`, `sandbox.kill` |
+| Filesystem | `sandbox.files.{read, write, list, exists, remove, makeDir, watch}` |
+| Commands | `sandbox.commands.{run, start, list, kill, sendStdin}` |
+| PTY | `sandbox.pty.{create, sendInput, resize}` |
+| Snapshots | `Sandbox.createSnapshot`, `Sandbox.list` |
+| Templates | `Template().fromImage(...).copy(...)`, `Template.build`, `Template.exists` |
+
+## Runtimes
+
+Node.js 20+, Bun, and Deno are supported. The SDK has no Node-specific runtime dependencies in its hot path; platform-specific features (like reading files from disk during a template build) use `node:fs` behind a dynamic import.
+
+## Sandbox region and ownership
+
+The SDK uses the launched default region (`yyz`) unless you choose another
+supported region. It sends create directly to that regional API and keeps the
+authoritative API base on the sandbox handle, so pause, resume, timeout,
+snapshot, and kill never take a hidden global round trip.
+
+```ts
+const sandbox = await Sandbox.create("base", { region: "yyz" });
+console.log(sandbox.sandboxRegion); // "yyz"
+```
+
+You can override the client default once with `ENCLAVE_REGION=yyz`. Static
+lifecycle helpers can take `region`; an instance returned by `create` or
+`connect` already carries its owner. SDK releases from before the regional
+default continue through the bounded global compatibility endpoint.
+
+Every logical create has an idempotency key (generated by the SDK unless you
+provide one). A timeout or lost response raises `OutcomeUnknownError` with the
+same-region recovery URL. Only an explicit pre-admission capacity rejection can
+be considered for another region; a transport timeout must never be retried
+elsewhere.
+
+The chosen region is also part of the sandbox host:
+
+```
+sbx-{id}-{port}.{region}.onenclave.com
+```
+
+## Env vars
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `ENCLAVE_API_KEY` | API authentication | — |
+| `ENCLAVE_DOMAIN` | API/sandbox apex | `onenclave.com` |
+| `ENCLAVE_API_URL` | Override API URL | — |
+| `ENCLAVE_REGION` | Regional API used for create/lifecycle | `yyz` |
+| `ENCLAVE_ACCESS_TOKEN` | Alternative auth (user tokens) | — |
+| `ENCLAVE_DEBUG` | Debug logging | `false` |
+
+## Docs
+
+Full reference at [enclave.run/docs](https://enclave.run/docs). Source: [github.com/enclave-run/docs](https://github.com/enclave-run/docs).