@agimon-ai/po-sandbox 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuong Ngo
+
+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,170 @@
+# @agimon-ai/po-sandbox
+
+Run the Po web cockpit, its sessions, and their tools in a container while the browser stays on the host.
+
+Part of the [Po distribution](https://www.npmjs.com/package/@agimon-ai/po).
+
+## Requirements
+
+- Node.js 24 or newer
+- `@earendil-works/pi-coding-agent` 0.85.0
+- One of `docker`, `podman`, `nerdctl`, or `finch` on the host for the cockpit container
+
+## Install
+
+```bash
+npm install @agimon-ai/po-sandbox
+```
+
+The cockpit container is started by the web cockpit (`po`, which runs `po-web`) and requires this package in the
+selected major mode's layers, as shown below.
+
+## Enable the sandbox
+
+This layer is still in development, so `po init` does not add it to any mode. Opt in by hand:
+name it as a layer in `.po/modes.yaml`, then list that layer on the mode you want it in.
+
+```yaml
+layers:
+  sandbox:
+    packages:
+      - '@agimon-ai/po-sandbox'
+
+majorMode:
+  copilot:
+    description: General-purpose coding mode.
+    layers: [team, ask-user, task, sandbox]
+```
+
+A mode without this layer offers no cockpit container, and the cockpit refuses containment rather
+than running uncontained.
+
+## Web cockpit container
+
+With this layer in the selected major mode, the web cockpit can hand over to one long-lived Linux
+container that holds the hub and every session it spawns:
+
+1. The cockpit resolves this package's `./cockpitHarness` export and delegates the container
+   lifecycle.
+2. The layer detects the first available engine in the order `docker`, `podman`, `nerdctl`,
+   `finch` (override with `PO_SANDBOX_ENGINE`), and builds a
+   cockpit image when that tag is not cached. The digest covers the image definition and bridge
+   source. The image installs `@agimon-ai/po-web` from the registry rather than copying the
+   host's platform-specific packages.
+3. It starts a detached container with each configured workspace bind-mounted at its host path,
+   a named home volume, and the cockpit port published on host loopback, then waits until the
+   cockpit inside answers `/api/health`.
+
+The browser stays on the host while bash, file edits, extensions, MCP servers, and skills all
+execute inside the container. `PO_SANDBOX=1` marks every sandboxed process; nesting is refused.
+See [The container plan and current wiring](../../../docs/securities.md#the-container-plan-and-current-wiring)
+for what the current server runtime connects.
+
+Only an allowlisted environment enters the container: terminal and locale variables, proxy
+settings, and `PO_PRESET`. Everything else a shell accumulates stays on the host.
+
+## Engine and runtime selection
+
+The harness invokes each supported engine with Docker-compatible arguments. The engine and its
+VM, if any, must already be running on the host.
+
+`PO_SANDBOX_RUN_FLAGS` passes extra options straight to the engine, which is how you select a
+different isolation runtime without the layer having to know about it:
+
+```bash
+PO_SANDBOX_RUN_FLAGS=--runtime=runsc po
+```
+
+Options must be self-contained (`--flag` or `--flag=value`). A separated value such as
+`--runtime runsc` is refused, because a bare word cannot be told apart from an image name and
+would silently launch a different container.
+
+Alternative isolation runtimes such as Kata or Firecracker are not verified here. Check their
+mount and broker-transport support before relying on them.
+
+## Workspace dev containers
+
+The cockpit container ignores a workspace `.devcontainer` configuration. That file is
+author-controlled and could mount anything, including the container socket, which would make the
+containment claim false.
+
+## Signing in from inside the sandbox
+
+Subscription logins are not brokered. The cockpit container publishes only the cockpit port on
+host loopback, so a `/login` callback that a provider sends to `localhost:<port>` does not reach
+the container. Use a provider API key, which the credential broker below carries. Credentials stored inside the container land in the cockpit home
+volume, so they survive later runs.
+
+## Provider credential broker
+
+For supported providers with a host API key, the credential broker:
+
+1. Starts a broker on the host and grants the container exactly one route to it.
+2. Replaces the credential variable with a random per-session token.
+3. Redirects the provider's base URL at a loopback bridge inside the container, which forwards
+   raw bytes to the broker.
+
+How the container reaches the broker depends on the engine:
+
+| Host                          | Transport                                   | Why                                                                                |
+| ----------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Linux                         | Unix socket, bind-mounted, owner-only       | Container and host share a kernel, so no port is needed                            |
+| macOS, Windows, any VM engine | Loopback TCP through `host.docker.internal` | A container in a virtual machine cannot connect to a mounted host socket (ENOTSUP) |
+
+On the TCP path the broker binds `127.0.0.1` on an ephemeral port, so it is never exposed beyond
+the host, and the launch passes `--add-host` so the gateway name resolves on every engine. Another
+local process could reach that port, and the session token is what stops it being useful.
+
+The broker validates the token, swaps in the real key, and streams the provider response back.
+Credentials for providers it cannot carry are withheld from the container rather than passed
+through. Turn the whole mechanism off with `PO_SANDBOX_BROKER=0`.
+
+## In-session command
+
+```text
+/doom-sandbox
+```
+
+Reports whether the current session runs inside the sandbox container or directly on the host.
+
+## Current limits
+
+- The broker carries a curated provider list. OAuth subscription logins are not brokered, and
+  their callbacks cannot reach the cockpit container.
+- A host `*_BASE_URL` override is dropped rather than used as the broker's upstream.
+- Compositions that declare local workspace packages cannot load their platform-specific
+  dependencies inside the Linux container; use registry-installed layers for sandboxed work.
+- One container holds every cockpit session, so sessions can read each other's mounted
+  workspaces.
+- Container network access follows the engine's defaults and is not restricted yet.
+- Mounted repositories are writable. Containers do not protect those files from agent edits,
+  and the container engine remains part of the trusted base.
+
+## Public API
+
+```ts
+import { DefaultSandboxExtensionService } from '@agimon-ai/po-sandbox';
+import { createCockpitHarness, startCockpitContainer } from '@agimon-ai/po-sandbox/cockpitHarness';
+```
+
+The service layer is host-neutral. `/extensions/server` registers the in-session command, and
+`/cockpitHarness` owns the web cockpit's container lifecycle and credential broker.
+
+## Development
+
+Run from this package directory in the workspace:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+pnpm exec vibe-lint check .
+npm pack --dry-run
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
+
+## License
+
+MIT

package/dist/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = (0, require("@agimon-ai/po-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,4CAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/po-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}