@axiom-lattice/microsandbox-service 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @axiom-lattice/microsandbox-service
 
+## 0.1.12
+
+### Patch Changes
+
+- a19e0aa: Unify the sandbox service base-URL env and treat missing sandbox files as a structured not-found (ADR-174 / ADR-175).
+
+  The resident plugin deployment runtime now reads `MICROSANDBOX_SERVICE_BASE_URL` only (dropping `MICROSANDBOX_SERVICE_URL`), so a provider-only config also enables `manage_plugin` deploy/undeploy/status; `sandbox-console` reads `VITE_MICROSANDBOX_SERVICE_BASE_URL`. `MICROSANDBOX_SERVICE_URL` no longer has any effect.
+
+  `opensandbox-gateway` now preserves the sandbox's upstream HTTP status (and surfaces execd's `{ code, message }`) instead of collapsing every failure to `500 "Download failed"`, and `MicrosandboxServiceClient` attaches the HTTP status to request errors; `microsandbox-service` `readFile`/`downloadFile` map missing files to `404 FILE_NOT_FOUND` (matching `deleteFile`). A missing sandbox file (e.g. the plugin-skill manifest) is therefore classified as not-found rather than a hard failure, fixing `Error loading skill content: ... Download failed`.
+
 ## 0.1.11
 
 ### Patch Changes

package/README.md

@@ -54,6 +54,9 @@ Supported environment variables:
 - `MICROSANDBOX_IDLE_TIMEOUT_SEC` default: `600` — auto-stop after N seconds of inactivity. Set to `0` to disable
 - `MICROSANDBOX_VOLUME_QUOTA_MIB` default: `2048` — storage quota for named volumes
 - `MICROSANDBOX_CLI_PATH` default: `~/.microsandbox/bin/msb` — path to the `msb` binary
+- `MICROSANDBOX_API_KEY` — when set, every `/api/*` request must send `Authorization: Bearer <key>` (`/health` stays open)
+- `MICROSANDBOX_HOST_PORT_MIN` default: `40000` — lowest host port used when publishing guest ports
+- `MICROSANDBOX_HOST_PORT_MAX` default: `60000` — highest host port used when publishing guest ports
 
 Example:
 
@@ -132,6 +135,73 @@ pnpm --filter @axiom-lattice/microsandbox-service dev
 
 This command watches source files, rebuilds the package, and restarts the service automatically.
 
+## HTTP API
+
+Every response uses a JSON envelope: success is `{ "success": true, "data": ... }`, failure is
+`{ "success": false, "error": { "code": "...", "message": "..." } }`. When `MICROSANDBOX_API_KEY`
+is set, all `/api/*` requests require `Authorization: Bearer <key>` (`/health` stays open).
+
+### Sandbox lifecycle
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/api/sandboxes` | List sandboxes |
+| `GET` | `/api/sandboxes/:name` | Inspect one sandbox |
+| `PUT` | `/api/sandboxes/:name` | Create-or-reuse (`ensure`) |
+| `POST` | `/api/sandboxes/:name/start` | Start / resume |
+| `POST` | `/api/sandboxes/:name/stop` | Pause |
+| `POST` | `/api/sandboxes/:name/kill` | Kill |
+| `DELETE` | `/api/sandboxes/:name` | Delete |
+| `GET` | `/api/sandboxes/:name/status` | Status |
+| `POST` | `/api/sandboxes/:name/logs` | Logs |
+| `GET` | `/api/sandboxes/:name/endpoints/:port` | Resolve a published guest port |
+| `ANY` | `/api/sandboxes/:name/proxy/:port/*` | Stream to a published guest port |
+
+File/shell operations are under `/api/files/*` and `/api/shell/exec`; image and named-volume
+operations under `/api/images/*` and `/api/volumes/:name/fs/*`.
+
+### Resident-service primitives
+
+`PUT /api/sandboxes/:name` accepts three optional fields beyond image/resource/volume config:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `entrypoint` | `string[]` | Main process command; replaces the default `tail -f /dev/null`. Use this to run a long-lived service (e.g. a plugin host daemon). |
+| `timeoutSeconds` | `number` \| `null` | Sandbox lifetime. `null` means no expiry. **Currently inert** in the registry — positive values are not yet applied and changes do not force a recreate (scheduled for Plan 3). |
+| `exposePorts` | `number[]` | Guest ports to publish. Each is mapped to a deterministic host port within `[MICROSANDBOX_HOST_PORT_MIN, MICROSANDBOX_HOST_PORT_MAX]`. |
+
+Create a resident service and resolve its endpoint:
+
+```bash
+curl -X PUT http://127.0.0.1:4002/api/sandboxes/plugin-weather \
+  -H 'content-type: application/json' \
+  -d '{
+    "image": "kioko12520/sandbox:0.1.0",
+    "entrypoint": ["node", "/root/.agents/.plugin-host/server.js"],
+    "exposePorts": [8080]
+  }'
+
+curl http://127.0.0.1:4002/api/sandboxes/plugin-weather/endpoints/8080
+# { "success": true, "data": { "endpoint": "/api/sandboxes/plugin-weather/proxy/8080" } }
+```
+
+`GET /api/sandboxes/:name/endpoints/:port` responses:
+
+- `200` — `{ "success": true, "data": { "endpoint": "/api/sandboxes/<name>/proxy/<port>" } }`
+  (a relative proxy path the caller composes with its configured service base URL; may also
+  include `headers` for proxied backends)
+- `400 INVALID_REQUEST` — `:port` is not an integer in `1..65535`
+- `404 ENDPOINT_NOT_PUBLISHED` — the port was not published for this sandbox
+
+The guest→host mapping is recovered from the sandbox's persisted config, so it survives service
+restarts. The loopback mapping stays internal; the returned path points at the proxy route below.
+
+`ANY /api/sandboxes/:name/proxy/:port/*` streams the request to the sandbox's published guest
+port (any method, unbuffered, so SSE and large payloads pass through). Authenticate to this
+service with `Authorization: Bearer <MICROSANDBOX_API_KEY>`; the proxy **strips** that header
+before forwarding, so the service key never reaches the (unauthenticated) sandbox host behind
+the loopback-bound port.
+
 ## Operational Notes
 
 - Invalid startup configuration exits non-zero.

package/dist/{chunk-7PYAXMHC.mjs → chunk-O5VQK7SY.mjs}

@@ -1,6 +1,6 @@
 import {
   buildApp
-} from "./chunk-2GSPCUXK.mjs";
+} from "./chunk-Z6NN3T6H.mjs";
 
 // src/lib/server-cli.ts
 function parsePort(raw, source) {
@@ -97,4 +97,4 @@ async function startServer({
 export {
   startServer
 };
-//# sourceMappingURL=chunk-7PYAXMHC.mjs.map
+//# sourceMappingURL=chunk-O5VQK7SY.mjs.map