add sandbox PoC

.changeset/sandbox-sdk.md

@@ -0,0 +1,6 @@
+---
+"@bunny.net/sandbox": minor
+"@bunny.net/cli": minor
+---
+
+Add @bunny.net/sandbox SDK for programmatic sandbox create, file buffering, command execution, and port exposure; wire sandbox CLI commands onto it

.github/workflows/sandbox-agent.yml

@@ -0,0 +1,37 @@
+name: Sandbox Agent
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - sandbox/**
+  workflow_dispatch:
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: ./sandbox
+          push: true
+          tags: ghcr.io/bunnyway/sandbox-agent:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

AGENTS.md

@@ -69,13 +69,14 @@ Bun replaces the entire Node.js toolchain. There are no separate tools for trans
 
 ## Project Structure
 
-This is a Bun workspace monorepo with four packages:
+This is a Bun workspace monorepo with six packages:
 
 - **`@bunny.net/openapi-client`** (`packages/openapi-client/`) — Standalone, type-safe OpenAPI client for bunny.net, generated from OpenAPI specs. Zero CLI dependencies. Publishable to npm.
 - **`@bunny.net/app-config`** (`packages/app-config/`) — Shared app configuration schemas (Zod), inferred types, JSON Schema generation, and API conversion functions. Used by the CLI and potentially other tools.
 - **`@bunny.net/database-shell`** (`packages/database-shell/`) — Standalone interactive SQL shell for libSQL databases. Framework-agnostic REPL, dot-commands, formatting, masking, and history. Also usable as a standalone CLI (binary: `bsql`).
 - **`@bunny.net/scriptable-dns-types`** (`packages/scriptable-dns-types/`): Ambient TypeScript declarations for the Scriptable DNS runtime globals (`ARecord`, `Monitoring`, `RoutingEngine`, etc.). Types-only, no runtime code: the DNS runtime can't `import`, so these power editor autocomplete and an optional typecheck step. Scaffolded into projects by `bunny dns scripts init`; intended to also feed the dashboard editor. Publishable to npm.
-- **`@bunny.net/cli`** (`packages/cli/`) — The CLI. Depends on `@bunny.net/openapi-client`, `@bunny.net/app-config`, and `@bunny.net/database-shell`.
+- **`@bunny.net/sandbox`** (`packages/sandbox/`) — Standalone sandbox SDK. Code-first DX (`Sandbox.create`, `writeFiles`, `runCommand`, `exposePort`) over Magic Containers provisioning plus an `ssh2` SSH/SFTP transport. Zero CLI dependencies.
+- **`@bunny.net/cli`** (`packages/cli/`) — The CLI. Depends on `@bunny.net/openapi-client`, `@bunny.net/app-config`, `@bunny.net/database-shell`, `@bunny.net/scriptable-dns-types`, and `@bunny.net/sandbox`.
 
 ```
 bunny-cli/
@@ -150,6 +151,19 @@ bunny-cli/
 │   │       ├── types.ts                  # ShellLogger, ShellOptions, PrintMode
 │   │       └── shell.test.ts            # Tests for shell utilities
 │   │
+│   ├── sandbox/                          # @bunny.net/sandbox package
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── src/
+│   │       ├── index.ts                  # Barrel export: Sandbox, Command, types
+│   │       ├── sandbox.ts                # Sandbox class: create/get/fromHandle, runCommand, writeFiles, readFile, mkDir, exposePort, domain, delete
+│   │       ├── provision.ts              # Magic Containers app create/poll/endpoints + auth helpers
+│   │       ├── transport.ts              # ssh2 SSH/SFTP transport (exec, file IO, reachability)
+│   │       ├── command.ts                # Command (detached, logs()) and CommandFinished
+│   │       ├── types.ts                  # Option and handle types
+│   │       ├── errors.ts                 # SandboxError
+│   │       └── sandbox.test.ts           # Tests for pure logic (command building, app extraction)
+│   │
 │   └── cli/                              # @bunny.net/cli package
 │       ├── package.json
 │       ├── tsconfig.json
@@ -366,7 +380,7 @@ bunny-cli/
 
 ### Conventions
 
-- **Monorepo with Bun workspaces.** `packages/openapi-client/` is the standalone API client SDK; `packages/app-config/` provides shared Zod schemas, types, and API conversion functions for `bunny.jsonc`; `packages/database-shell/` is the standalone SQL shell engine; `packages/cli/` is the CLI.
+- **Monorepo with Bun workspaces.** `packages/openapi-client/` is the standalone API client SDK; `packages/app-config/` provides shared Zod schemas, types, and API conversion functions for `bunny.jsonc`; `packages/database-shell/` is the standalone SQL shell engine; `packages/sandbox/` is the standalone sandbox SDK (provisioning + SSH transport); `packages/cli/` is the CLI.
 - **API clients use `ClientOptions`** — an options object with `apiKey`, `baseUrl`, `verbose`, `userAgent`, and `onDebug`. The CLI provides a `clientOptions(config, verbose)` helper to build this from `ResolvedConfig`.
 - **One command per file.** Each file in `commands/` exports a single command or namespace.
 - **Commands are grouped by domain** in subdirectories (`config/`, `db/`, `scripts/`).

CLAUDE.md

@@ -26,12 +26,13 @@ test("example", () => {
 
 ## Monorepo structure
 
-This is a Bun workspace monorepo with four packages:
+This is a Bun workspace monorepo with five packages:
 
 - `packages/openapi-client/` (`@bunny.net/openapi-client`) — standalone, type-safe OpenAPI client, zero CLI deps
 - `packages/app-config/` (`@bunny.net/app-config`) — shared Zod schemas, types, and JSON Schema for `bunny.jsonc`
 - `packages/database-shell/` (`@bunny.net/database-shell`) — standalone SQL shell engine (REPL, formatting, masking)
-- `packages/cli/` (`@bunny.net/cli`) — the CLI, depends on all three
+- `packages/sandbox/` (`@bunny.net/sandbox`) — standalone sandbox SDK (create, file buffering, command exec, port exposure) over Magic Containers + SSH
+- `packages/cli/` (`@bunny.net/cli`) — the CLI, depends on the other four
 
 ## Project conventions
 

packages/app-config/src/convert.test.ts

@@ -339,7 +339,7 @@ describe("configToAddRequest", () => {
     ]);
   });
 
-  test("anycast endpoint stamps type 'iPv4'", () => {
+  test("anycast endpoint stamps type 'ipv4'", () => {
     const req = configToAddRequest({
       version: CURRENT_VERSION,
       app: {
@@ -355,7 +355,7 @@ describe("configToAddRequest", () => {
       },
     });
     const ep = req.containerTemplates?.[0]?.endpoints?.[0];
-    expect(ep?.anycast?.type).toBe("iPv4");
+    expect(ep?.anycast?.type).toBe("ipv4");
     expect(ep?.anycast?.portMappings).toEqual([
       { containerPort: 80, exposedPort: 80 },
     ]);

packages/app-config/src/convert.ts

@@ -120,7 +120,7 @@ function containerConfigToRequest(
     imageNamespace,
     imageTag,
     imageRegistryId: config.registry ?? "",
-    imagePullPolicy: "ifNotPresent",
+    imagePullPolicy: "always",
   };
 
   if (config.command) {
@@ -162,7 +162,7 @@ function endpointConfigToRequest(ep: EndpointConfig): EndpointRequest {
     };
   } else if (ep.type === "anycast") {
     req.anycast = {
-      type: "iPv4",
+      type: "ipv4",
       portMappings: (ep.ports ?? []).map((p) => ({
         containerPort: p.container,
         exposedPort: p.public,