Introduce Cloud Mode to Hatchbox

[acreeger]

Overview

Add a first-class Cloud Mode to Hatchbox so users can create, run, and manage development environments in the cloud (initial provider: GitHub Codespaces). This complements existing local workflows and keeps hb start / stop / finish semantics consistent.

Motivation

• Enable portable, reproducible, browser-based development.

• Support mobile and remote workflows without relying on a laptop.

• Keep Hatchbox’s per-issue isolation model while running in managed compute.

Scope

• New Cloud Mode configuration in .hatchbox/settings.json.

• A unified hb init that asks: local or cloud, then configures accordingly.

• Codespaces integration for hb start, hb stop, hb finish.

• Minimal .devcontainer/ scaffolding when Cloud Mode is selected.

• Basic secrets handling for Codespaces (dev) and Actions (CI).

High-Level Plan

1) Configuration: .hatchbox/settings.json

Add cloud awareness and defaults (example shown for Codespaces):

{    
    "mode": "cloud",
    "cloud" : {
        "provider": "github-codespaces",
        "cloud.machine": "default",
        "secrets.sync": "manual"
     }
}

Notes:

• Default mode remains local for existing repos.

• Keys above are minimal; values can be extended later.

2) hb init (single command)

Behavior:

• Prompt: “Do you want to work locally or in the cloud?”

• If local: set "mode": "local" in .hatchbox/settings.json. No devcontainer added.

• If cloud: set "mode": "cloud", create a minimal .devcontainer/, and record default cloud settings.

• Idempotent: if a devcontainer already exists, do not overwrite it; just set mode and confirm.

3) hb start (mode-aware)

Cloud Mode behavior:

• Create a Codespace for the repo/branch.

• Branching: create/checkout the issue branch, then provision the Codespace on that branch.

• Naming: org-repo-issue-123 (deterministic).

• Machine size: read from "cloud.machine"; allow --size override.

• Ports: auto-forward common ports (app, db, storybook) and print the URLs.

Local Mode behavior:

• Unchanged: create the local workspace/worktree with the current Hatchbox flow.

4) hb stop and hb finish

• hb stop: stop the Codespace (cloud) or stop local services (local).

• hb finish: clean up the Codespace or local workspace; optionally merge branch per existing rules.

5) Secrets handling (initial version)

• .env tracked in git: no sync needed (arrives via checkout).

• .env ignored (local only): sync to Actions (CI) and Codespaces (dev) as repo secrets.

• .env.local: sync to Codespaces only (developer-specific). On boot, write a .env.local file from env vars if the framework expects one.

6) Billing and policy awareness

• Detect and display who pays for Codespaces (personal vs org).

• Respect org policies for Codespaces creation, idle timeout, and storage.

Acceptance Criteria

• hb init offers a single guided flow (local vs cloud) and writes .hatchbox/settings.json accordingly.

• In Cloud Mode, hb start provisions a Codespace and forwards ports.

• hb stop and hb finish operate on the correct target (cloud or local) with identical command names.

• Secrets flow operates as described above for .env and .env.local.

• Clear CLI messages indicate billing context and next steps.

Out of Scope (for this issue)

• Additional cloud providers (Gitpod, GCP Workstations) — follow-up work.

• Prebuilds optimization — follow-up work.

• Advanced org policy management — follow-up work.

Open Questions

• Do we want an org-level policy to force Cloud Mode or Local Mode by default?

• Minimum machine size defaults per template or repo type?

• Should secrets sync be opt-in per key (whitelist) or opt-out (blacklist) for the first release?