OMP development shell kit

A standalone Docker Sandboxes kit for Oh My Pi (omp) and Herdr with Zsh, fnm, pnpm, architecture-native Chromium, and repository-aware Node.js setup.

What it does

During sandbox creation, the kit:

• installs the latest OMP and Herdr prebuilt releases available for the sandbox architecture;
• configures OMP as the sandbox entrypoint with --approval-mode=yolo;
• configures Herdr panes to start OMP automatically;
• loads the repository's AGENTS.md through the kit's agentInstructions;
• installs Zsh, Ubuntu's build-essential toolchain, and fnm;
• installs Playwright's pinned, architecture-native Chromium build and its system libraries;
• exposes OMP, Herdr, fnm, Chromium, pnpm, and the installed language servers on the sandbox PATH;
• binds the sipgate_os, sonarqube, and langsmith sandbox secrets to proxy-managed SIPGATE_OS_API_KEY, SONARQUBE_TOKEN, and LANGSMITH_API_KEY environment variables;
• initializes fnm from ~/.zshrc.

At sandbox startup, fnm detects the repository's requested Node.js version and installs it when necessary. Detection supports:

• .node-version;
• .nvmrc;
• package.json#engines.node;
• version files in parent directories.

It installs pnpm plus the TypeScript and ESLint language servers once per selected Node.js version. A pinned Playwright release installs an architecture-native Chromium build once per sandbox, then exposes it as chromium in the agent's PATH. OMP automatically enables ESLint when the repository root contains an ESLint configuration file.

If fnm cannot select or install the repository's requested version, the setup installs and uses the latest Node.js LTS release.

The selected or fallback fnm runtime becomes the agent user's Node.js default, so OMP tool calls and non-interactive commands use it instead of the base image's system Node.js.

Allow the kit publisher

Docker Sandboxes restricts remote kit publishers through kit.allowedSources. Add github.com/fgladisch/ while preserving any sources you already trust:

sbx settings get kit.allowedSources
sbx settings set kit.allowedSources \
  '["docker.io/","github.com/docker/","github.com/fgladisch/"]'

The exact array is an example based on the default Docker sources. Include any additional entries from your existing setting.

Usage

sbx run \
  "git+https://github.com/fgladisch/sbx-kit-omp-dev-shell.git" \
  "$PWD"

Launcher

bin/omp-sbx wraps the full per-project lifecycle. Run it from a repository to:

1. derive the sandbox name omp-<repository> from the current directory name;
2. create the sandbox when necessary, with the current directory as its primary workspace and any additional directories mounted alongside it;
3. copy the host's complete ~/.omp/agent directory into a newly created sandbox;
4. replace the copied commands and add the shared skills configured by OMP_COMMANDS_DIR and OMP_SKILLS_DIR;
5. update OMP and its installed plugins on every launch;
6. attach to OMP and forward arguments following --, or arguments beginning with -, to OMP.

Link it into ~/bin:

ln -s "$(pwd)/bin/omp-sbx" "$HOME/bin/omp-sbx"

Then launch OMP from any repository:

omp-sbx

Pass additional workspace directories before OMP arguments. They are mounted read-write at the same absolute paths as on the host. Append :ro to mount a directory read-only:

omp-sbx ../ai-agents-telco-service ../sipgate-app-admin
omp-sbx ../shared-docs:ro

Use -- to separate workspace directories from OMP arguments. A leading OMP option also ends workspace parsing, so existing option-only calls remain valid:

omp-sbx ../shared-docs:ro -- --continue

Additional workspace arguments apply only when the sandbox is first created. An existing sandbox keeps its original mounts. Remove it with sbx rm omp-<repository> before changing the workspace list.

Resume the latest project session with --continue, or open OMP's session picker with --resume:

omp-sbx --continue
omp-sbx --resume

The launcher uses the published Git kit by default. Set OMP_KIT to a local directory or another supported kit reference when testing a different build:

OMP_KIT=/path/to/sbx-kit-omp-dev-shell omp-sbx

The initial copy places the host's full ~/.omp/agent directory at /home/agent/.omp/agent, then replaces its commands entry with the configured commands directory. Existing sandboxes keep independent configuration, databases, sessions, commands, and skills. Changes made to the corresponding host files are not synchronized on later launches. Removing the named sandbox with sbx rm also removes that sandbox-local state.

Herdr launcher

bin/herdr-sbx creates a separate herdr-<repository> sandbox with the same configuration, skills, commands, and multi-folder mounts as omp-sbx. It opens Herdr in the current directory, and Herdr starts OMP automatically in each new pane without arguments. Arguments after --, or arguments beginning with -, are forwarded to Herdr.

Link it into ~/bin:

ln -s "$(pwd)/bin/herdr-sbx" "$HOME/bin/herdr-sbx"

Launch Herdr from a repository, optionally mounting additional directories:

herdr-sbx
herdr-sbx ../ai-agents-telco-service ../shared-docs:ro
herdr-sbx ../shared-docs:ro -- --session project

Workspace paths must precede Herdr arguments. Additional workspaces apply only when the sandbox is first created. Remove it with sbx rm herdr-<repository> before changing the workspace list.

When the launcher resolves to a checkout containing spec.yaml, it uses that local kit so the script and sandbox setup stay in sync. Otherwise it falls back to the published Git kit. OMP_KIT overrides either default.

Skills

Keep shared skills in a dedicated Git repository. The launcher copies ~/code/omp-skills/skills by default; override the source directory with OMP_SKILLS_DIR.

Expose the same repository to host OMP through its canonical user skills path:

skills_dir="${OMP_SKILLS_DIR:-$HOME/code/omp-skills/skills}"
mkdir -p "$HOME/.agents"
ln -sfn "$skills_dir" "$HOME/.agents/skills"
rm -f "$HOME/.omp/agent/skills"

When creating a sandbox, the launcher copies the source directory to /home/agent/.agents/skills. Existing sandboxes and their skills are left unchanged on later launches.

Commands

Keep shared commands in a dedicated Git repository. The launcher copies ~/code/omp-skills/commands by default; override the source directory with OMP_COMMANDS_DIR.

When creating a sandbox, the launcher replaces the copied host ~/.omp/agent/commands entry, including a symlink, with the source directory at /home/agent/.omp/agent/commands. Existing sandboxes and their commands are left unchanged on later launches.

Credentials

Store the three credentials used by the kit globally before creating a sandbox:

sbx secret set -g sipgate_os
sbx secret set -g sonarqube
sbx secret set -g langsmith

Schema v2 third-party kits also require credential bindings. Before using the non-interactive launcher, merge these approvals into ~/.config/sbx/credentials.yaml without removing existing bindings:

bindings:
  sipgate_os:
    apiKey:
      domains:
        - coding.sipgate.ai
  sonarqube:
    apiKey:
      domains:
        - api.sonarcloud.io
  langsmith:
    apiKey:
      domains:
        - eu.api.smith.langchain.com

Alternatively, run the kit interactively once and approve each requested binding at the prompt. Non-interactive sbx create runs with unbound credentials withheld.

Existing sandboxes retain the network policy and credential injection domains from creation time. After changing a binding or kit domain, remove and recreate the sandbox before retrying the affected service.

The sandbox receives proxy-managed sentinel values rather than the real credentials. The host-side proxy injects bearer tokens for Sipgate and SonarCloud requests, and the X-Api-Key header for LangSmith requests.

Network access

The kit allows the domains needed for:

• Ubuntu and Docker APT metadata;
• Herdr, OMP, fnm, Node.js, npm, pnpm, and Playwright installation;
• GitHub API access and release downloads;
• OpenAI and Anthropic authentication and model endpoints;
• Sipgate model endpoint;
• SonarCloud and LangSmith API access.

Review permissions.network.allow in spec.yaml before use if your environment requires a narrower egress policy.

Compatibility

The kit uses schemaVersion: "2" with the current kind: sandbox, sandbox, agentInstructions, permissions, credentials, and setup fields. It validates with Docker Sandboxes v0.39.0.

Validate it locally with:

sbx kit validate .

Lifecycle

• setup.install installs OMP, Herdr, Zsh, fnm, and a pinned architecture-native Chromium build with Playwright's browser dependencies during sandbox creation.
• setup.files configures Herdr's automatic OMP panes and writes the repository-aware Node.js setup command plus executable LSP bootstraps.
• setup.startup selects the repository's Node.js version and provisions its pnpm and language-server tools. A bootstrap invocation shares the locked setup path if OMP launches a server before provisioning finishes.

All installation steps are idempotent so sandbox startup and recreation can safely repeat them.