feat(packages/sandbox): sandbox sdk poc

[jamie-at-bunny]

No description provided.

[changeset-bot]

🦋 Changeset detected

Latest commit: 68a89ea

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@bunny.net/sandbox	Minor
@bunny.net/cli	Minor
@bunny.net/cli-linux-x64	Minor
@bunny.net/cli-linux-arm64	Minor
@bunny.net/cli-darwin-x64	Minor
@bunny.net/cli-darwin-arm64	Minor
@bunny.net/cli-windows-x64	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jamie-at-bunny]

@greptile-apps review

[greptile-apps]

Greptile Summary

This PR introduces @bunny.net/sandbox, a standalone SDK for programmatically creating and managing ephemeral bunny.net sandboxes (Magic Containers apps) over SSH/SFTP, and wires three new CLI commands — sandbox create, sandbox delete, and sandbox url add — onto it. Several issues flagged in earlier review rounds have been resolved: the env-var key injection path, the SFTP channel leak, the exposePort orphan-on-failure case, the waitForPublicHost missing terminal-state fast-fail, and the throw lastErr dead code.

• @bunny.net/sandbox (sandbox.ts, transport.ts, provision.ts, command.ts) — provides Sandbox.create/get/fromHandle, runCommand (blocking + detached streaming), writeFiles/readFile, exposePort, and delete, backed by a single reused ssh2 connection.
• CLI commands (sandbox/create.ts, sandbox/delete.ts, sandbox/url/add.ts) — thin wrappers that resolve config, invoke the SDK, and persist sandbox handles (app ID + agent token + SSH host) in the CLI profile file under a sandboxes map.

Confidence Score: 4/5

Safe to merge after adding a duplicate-name guard in sandbox create; all other previously flagged issues have been addressed.

The sandbox create CLI command has no check for whether the requested name is already registered in the config. Running it twice with the same name provisions a new MC app, overwrites the config entry, and leaves the old app running with no CLI handle. Because sandboxes are billable infrastructure, this is a concrete defect on the changed code path rather than a theoretical risk.

packages/cli/src/commands/sandbox/create.ts — needs a pre-flight check against the config before calling Sandbox.create().

Important Files Changed

Filename	Overview
packages/sandbox/src/sandbox.ts	Core Sandbox class with create/get/fromHandle/runCommand/writeFiles/exposePort/delete. Previously flagged issues (env-key injection, exposePort orphan on failure) are now addressed in this version.
packages/sandbox/src/transport.ts	SSH/SFTP transport over a single reused connection. SFTP channel is now lazily cached and reused (previously flagged per-operation leak addressed). SSH host verification remains absent per a deliberate tracked follow-up.
packages/sandbox/src/provision.ts	MC API provisioning helpers. Registry retry loop is now clean (dead lastErr removed). waitForPublicHost now fast-fails on terminal app states. Two POST calls still use (client as any) for undocumented MC endpoints.
packages/sandbox/src/command.ts	Detached Command streaming abstraction over a ClientChannel; correctly drains the queue after close. CommandFinished wraps already-complete data.
packages/cli/src/commands/sandbox/create.ts	CLI sandbox create command. Missing a duplicate-name guard before Sandbox.create() — a repeated invocation with the same name orphans the previously-tracked MC app and overwrites the config entry.
packages/cli/src/commands/sandbox/delete.ts	CLI sandbox delete command. Looks correct: reads from config, confirms with --force bypass, deletes via SDK, removes config entry.
packages/cli/src/commands/sandbox/url/add.ts	CLI sandbox url add command. Correctly resolves sandbox from config, calls exposePort, and outputs the public URL.
packages/sandbox/src/types.ts	Type definitions for the sandbox SDK: SandboxAuth, CreateOptions, SandboxHandle, RunCommandOptions, FileToWrite. Clean and well-documented.
packages/sandbox/src/integration.test.ts	Live integration test guarded by SANDBOX_INTEGRATION=1 env var; skipped in CI. Covers create, exec, file I/O, detached streaming, and cleanup.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant CLI as bunny sandbox create
    participant SDK as Sandbox.create()
    participant MC as Magic Containers API
    participant SSH as SshTransport

    CLI->>SDK: "create({ name, region, apiKey })"
    SDK->>MC: POST /apps (createApp)
    MC-->>SDK: appId
    SDK->>MC: "poll GET /apps/{appId} (waitForSshHost)"
    MC-->>SDK: anycast SSH host
    SDK->>SSH: waitUntilReachable(120s)
    SSH-->>SDK: connected
    loop options.ports
        SDK->>MC: "POST /apps/{appId}/containers/{id}/endpoints"
        MC-->>SDK: endpointId
        SDK->>MC: "poll GET /apps/{appId}/endpoints (waitForPublicHost)"
        MC-->>SDK: publicHost
    end
    SDK-->>CLI: Sandbox instance
    CLI->>CLI: toHandle() + disconnect()
    CLI->>CLI: setSandbox(name, handle) to config file

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant CLI as bunny sandbox create
    participant SDK as Sandbox.create()
    participant MC as Magic Containers API
    participant SSH as SshTransport

    CLI->>SDK: "create({ name, region, apiKey })"
    SDK->>MC: POST /apps (createApp)
    MC-->>SDK: appId
    SDK->>MC: "poll GET /apps/{appId} (waitForSshHost)"
    MC-->>SDK: anycast SSH host
    SDK->>SSH: waitUntilReachable(120s)
    SSH-->>SDK: connected
    loop options.ports
        SDK->>MC: "POST /apps/{appId}/containers/{id}/endpoints"
        MC-->>SDK: endpointId
        SDK->>MC: "poll GET /apps/{appId}/endpoints (waitForPublicHost)"
        MC-->>SDK: publicHost
    end
    SDK-->>CLI: Sandbox instance
    CLI->>CLI: toHandle() + disconnect()
    CLI->>CLI: setSandbox(name, handle) to config file

Loading

_{Reviews (4): Last reviewed commit: "fmt" | Re-trigger Greptile}

[bogdan-at-bunny]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bfb149c111

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".