@computesdk/cocoonstack 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 computesdk
+
+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

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @computesdk/cocoonstack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cocoon Stack provider for ComputeSDK - self-hosted microVM sandboxes served from warm pools by [sandboxd](https://github.com/cocoonstack/sandbox), the sandbox control plane of the Cocoon Stack.
+
+## Installation
+
+```bash
+npm install @computesdk/cocoonstack
+```
+
+## Setup
+
+1. Run a sandboxd node (see the [deployment guide](https://github.com/cocoonstack/sandbox/blob/main/docs/deploy.md)) with a pool for the template you want to claim, and put it behind TLS.
+2. Set the endpoint and a node or tenant API token:
+
+```bash
+export COCOONSTACK_API_URL=https://sandbox.example.com
+export COCOONSTACK_API_KEY=your_api_token
+```
+
+## Quick Start
+
+```typescript
+import { compute } from 'computesdk';
+import { cocoonstack } from '@computesdk/cocoonstack';
+
+compute.setConfig({
+  provider: cocoonstack({
+    baseUrl: process.env.COCOONSTACK_API_URL,
+    apiKey: process.env.COCOONSTACK_API_KEY,
+  }),
+});
+
+const sandbox = await compute.sandbox.create();
+
+const result = await sandbox.runCommand('node -v');
+console.log(result.stdout);
+
+await sandbox.destroy();
+```
+
+Or call the provider factory directly:
+
+```typescript
+import { cocoonstack } from '@computesdk/cocoonstack';
+
+const sdk = cocoonstack({ baseUrl: process.env.COCOONSTACK_API_URL, apiKey: process.env.COCOONSTACK_API_KEY });
+const sandbox = await sdk.sandbox.create({ templateId: 'python-rt:3.12', vcpus: 4, memoryMb: 4096 });
+```
+
+## Configuration
+
+```typescript
+interface CocoonstackConfig {
+  /** sandboxd endpoint - if not provided, will use COCOONSTACK_API_URL env var */
+  baseUrl?: string;
+  /** Node or tenant API token - if not provided, will use COCOONSTACK_API_KEY env var */
+  apiKey?: string;
+  /** Default template, a pool key such as node-rt:24.04 (the default) */
+  template?: string;
+  /** Default network lane: 'none' (default) or 'egress' */
+  net?: 'none' | 'egress';
+  /** Default size tier: small (default), medium, large, xlarge, 2xlarge */
+  size?: 'small' | 'medium' | 'large' | 'xlarge' | '2xlarge';
+  /** Default claim lease in seconds (default 300); the node reaps the sandbox after it */
+  ttlSeconds?: number;
+  /** HTTP request timeout in milliseconds (default 120000) */
+  requestTimeoutMs?: number;
+  /** Open the HTTP/2 session at construction; TLS endpoints only (default false) */
+  preconnect?: boolean;
+}
+```
+
+### Create options
+
+- `templateId` (or `image`) picks the template, e.g. `node-rt:24.04`, `python-rt:3.12`, `rt:24.04`.
+- `size` picks a tier by name. Without it, `vcpus`/`cpus`/`cpu` and `memoryMb`/`memoryMiB`/`memMiB`/`memory` map to the smallest tier that covers the request:
+
+| size | CPU | memory |
+|---|---|---|
+| `small` | 1 | 512 MB |
+| `medium` | 2 | 1 GB |
+| `large` | 4 | 4 GB |
+| `xlarge` | 4 | 8 GB |
+| `2xlarge` | 8 | 16 GB |
+
+- `timeout` (milliseconds) becomes the claim lease, capped at 24 hours.
+
+A claim is served from the node's warm pool for `(template, net, size)`; a request outside the configured pools cold-boots the template, which takes longer.
+
+## Features
+
+- ✅ **Command Execution** - commands run as root through `bash -c` over the sandboxd agent relay, with native `cwd`, `env`, streaming `onStdout`/`onStderr`, `background`, and `timeout`
+- ✅ **Filesystem Operations** - shell-backed `readFile`, `writeFile`, `mkdir`, `readdir`, `exists`, `remove`
+- ✅ **Preview URLs** - `getUrl` mints a signed preview URL when the node has a preview listener
+- ✅ **Listing** - `list` and `getById` read the node's sandbox index
+
+## Limitations
+
+- sandboxd scopes a sandbox to the token minted at claim time, so `getById` and `list` return only the sandboxes this process claimed (the node's own index is visible through the sandboxd API). `destroy` by id also works with a node token.
+- A command without an explicit `timeout` is bounded by `requestTimeoutMs` (120 s by default); pass `timeout` for longer builds.
+- Tokens travel as bearer headers: use an `https://` endpoint outside a private network. Nothing connects until the first call; `preconnect: true` opens the HTTP/2 session when the factory runs instead, so the first sandbox call skips DNS and the TLS handshake.
+- A node in a cluster may answer a claim with a redirect to a peer; this provider refuses it. Point `baseUrl` at a node that serves the pool.
+- Snapshots and templates are managed through sandboxd's own API (checkpoints, promote) and are not exposed here.

package/dist/index.d.mts

@@ -0,0 +1,66 @@
+import * as computesdk from 'computesdk';
+import * as _computesdk_provider from '@computesdk/provider';
+
+declare const SIZES: readonly [{
+    readonly size: "small";
+    readonly cpu: 1;
+    readonly memoryMb: 512;
+}, {
+    readonly size: "medium";
+    readonly cpu: 2;
+    readonly memoryMb: 1024;
+}, {
+    readonly size: "large";
+    readonly cpu: 4;
+    readonly memoryMb: 4096;
+}, {
+    readonly size: "xlarge";
+    readonly cpu: 4;
+    readonly memoryMb: 8192;
+}, {
+    readonly size: "2xlarge";
+    readonly cpu: 8;
+    readonly memoryMb: 16384;
+}];
+type CocoonstackSize = (typeof SIZES)[number]['size'];
+type CocoonstackNet = 'none' | 'egress';
+interface CocoonstackConfig {
+    /** sandboxd endpoint, e.g. https://sandbox.example.com. Falls back to COCOONSTACK_API_URL. */
+    baseUrl?: string;
+    /** Node or tenant API token. Falls back to COCOONSTACK_API_KEY. */
+    apiKey?: string;
+    /** Default template, a pool key such as node-rt:24.04. */
+    template?: string;
+    /** Default network lane. */
+    net?: CocoonstackNet;
+    /** Default size tier. */
+    size?: CocoonstackSize;
+    /** Default claim lease in seconds; the node reaps the sandbox after it. */
+    ttlSeconds?: number;
+    /** HTTP request timeout. */
+    requestTimeoutMs?: number;
+    /** Open the HTTP/2 session at construction so the first call skips DNS and the TLS handshake; TLS endpoints only. */
+    preconnect?: boolean;
+}
+interface CocoonstackSandbox {
+    id: string;
+    /** The claim token; every call on the sandbox authenticates with it. */
+    token: string;
+    template: string;
+    net: CocoonstackNet;
+    size: CocoonstackSize;
+    createdAt: Date;
+    deadline: Date;
+    config: CocoonstackConfig;
+}
+declare class CocoonstackApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare const provider: (config: CocoonstackConfig & _computesdk_provider.ProcessRuntimeOptions) => _computesdk_provider.Provider<CocoonstackSandbox, any, any, computesdk.Volume> & {
+    readonly sizes: computesdk.InstanceSizeManager;
+};
+/** Cocoon Stack provider; `preconnect` opens the HTTP/2 session at construction instead of on the first call. */
+declare const cocoonstack: typeof provider;
+
+export { CocoonstackApiError, type CocoonstackConfig, type CocoonstackNet, type CocoonstackSandbox, type CocoonstackSize, cocoonstack, cocoonstack as default };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import * as computesdk from 'computesdk';
+import * as _computesdk_provider from '@computesdk/provider';
+
+declare const SIZES: readonly [{
+    readonly size: "small";
+    readonly cpu: 1;
+    readonly memoryMb: 512;
+}, {
+    readonly size: "medium";
+    readonly cpu: 2;
+    readonly memoryMb: 1024;
+}, {
+    readonly size: "large";
+    readonly cpu: 4;
+    readonly memoryMb: 4096;
+}, {
+    readonly size: "xlarge";
+    readonly cpu: 4;
+    readonly memoryMb: 8192;
+}, {
+    readonly size: "2xlarge";
+    readonly cpu: 8;
+    readonly memoryMb: 16384;
+}];
+type CocoonstackSize = (typeof SIZES)[number]['size'];
+type CocoonstackNet = 'none' | 'egress';
+interface CocoonstackConfig {
+    /** sandboxd endpoint, e.g. https://sandbox.example.com. Falls back to COCOONSTACK_API_URL. */
+    baseUrl?: string;
+    /** Node or tenant API token. Falls back to COCOONSTACK_API_KEY. */
+    apiKey?: string;
+    /** Default template, a pool key such as node-rt:24.04. */
+    template?: string;
+    /** Default network lane. */
+    net?: CocoonstackNet;
+    /** Default size tier. */
+    size?: CocoonstackSize;
+    /** Default claim lease in seconds; the node reaps the sandbox after it. */
+    ttlSeconds?: number;
+    /** HTTP request timeout. */
+    requestTimeoutMs?: number;
+    /** Open the HTTP/2 session at construction so the first call skips DNS and the TLS handshake; TLS endpoints only. */
+    preconnect?: boolean;
+}
+interface CocoonstackSandbox {
+    id: string;
+    /** The claim token; every call on the sandbox authenticates with it. */
+    token: string;
+    template: string;
+    net: CocoonstackNet;
+    size: CocoonstackSize;
+    createdAt: Date;
+    deadline: Date;
+    config: CocoonstackConfig;
+}
+declare class CocoonstackApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare const provider: (config: CocoonstackConfig & _computesdk_provider.ProcessRuntimeOptions) => _computesdk_provider.Provider<CocoonstackSandbox, any, any, computesdk.Volume> & {
+    readonly sizes: computesdk.InstanceSizeManager;
+};
+/** Cocoon Stack provider; `preconnect` opens the HTTP/2 session at construction instead of on the first call. */
+declare const cocoonstack: typeof provider;
+
+export { CocoonstackApiError, type CocoonstackConfig, type CocoonstackNet, type CocoonstackSandbox, type CocoonstackSize, cocoonstack, cocoonstack as default };