Skip to content

Adopt devcontainer spec as box configuration source #12

@Gandalf-Le-Dev

Description

@Gandalf-Le-Dev

Tracking issue for the devcontainer-spec adoption initiative. Replaces #6.

Why

Current state: tool installation scattered across `internal/wizard/wizard.go` and `internal/containers/builder.go`, hand-rolled `USER root`/`USER dev` orchestration, tools/install-methods encoded inline as switch cases, no path for users to bring their own box definition.

Decision

Adopt the devcontainer spec as the first-class configuration artifact for a hopbox box. Drop `profile.toml` entirely (breaking change, we're pre-1.0, no migration). Build pipeline consumes `devcontainer.json` + features via `@devcontainers/cli` (or a minimal in-house resolver). Wizard generates a `devcontainer.json`. Users can import their own.

Benefits:

  • Free ecosystem (dozens of community features for CLIs, languages, toolchains)
  • VSCode Remote / Codespaces / JetBrains Gateway compatibility for free
  • Features are self-contained units with standard metadata — user-vs-root USER dance moves out of hopbox code
  • User-authored `devcontainer.json` becomes first-class (share + version-control dev envs)
  • Clear policy chokepoint (feature allowlist) for multi-tenant / commercial use

Constraints:

  • Sysbox runtime stays enforced (already in place). Commercial multi-tenant mandates it.
  • Feature allowlist policy: deny `docker-outside-of-docker` and other tenant-escape risks. Keep hopbox's existing `docker-in-docker via Sysbox` posture.

Sub-projects (each its own spec + PR)

  • (1) Build pipeline — devcontainer-cli integration. Rewrites `internal/containers/builder.go` to drive `devcontainers/cli` instead of generating a Dockerfile from scratch. Foundation. Risk concentrated here.
  • (2) Hopbox-authored features. Package claude-code, codex, gemini-cli, atuin, and hopbox CLI as devcontainer features publishable to GHCR.
  • (3) Policy layer. Feature allowlist/denylist, Sysbox enforcement, per-box resource and network policy. Security hardening pass.
  • (4) Wizard UI rework. Wizard selects features from curated catalog + options; writes `devcontainer.json`.
  • (5) Profile replacement. `profile.toml` deleted, `devcontainer.json` is the box's single source of truth. Pre-1.0 breaking change, no migration.
  • (6) User-imported `devcontainer.json`. `hop box create --from-devcontainer ` or auto-detect `.devcontainer/devcontainer.json` in the bind-mounted home. Depends on (3) for safety.

Each sub-project will get its own issue when it becomes active, so this list doubles as the roadmap.

Out of scope

  • MOSH adoption (tracked separately in Use MOSH for reliability #4).
  • Runtime version managers (mise, nvm) — they stay as-is unless a sub-project specifically rethinks them.

Supersedes

Closes #6.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions