maesttro 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# maesttro
+
+Isolated Docker sandbox for local coding agents — `claude`, `opencode`, `codex`,
+and others — running under a dedicated bot GitHub identity, never your personal
+`~/.ssh` or `~/.config/gh`. Install once, then `maesttro` just works from any
+project.
+
+Companion piece to Maesttro's orchestration side: this is the local, single-
+machine entry point — a curated, versioned way to run any supported client
+safely, with sane defaults baked in.
+
+---
+
+## Install
+
+**Global install (recommended for regular use — instant, offline):**
+```bash
+npm i -g maesttro
+```
+
+**Zero-install, try it once (npx/bunx resolve the package by this exact name):**
+```bash
+npx maesttro
+bunx maesttro
+```
+Note: `npx`/`bunx` check the registry for the latest version on every
+invocation (small network hit + latency each time), and typically run
+whatever's tagged `latest` unless you pin a version. Good for a first try or
+demoing to someone else; `npm i -g` is the better daily-driver since all real
+state lives in Docker anyway — the CLI itself is stateless either way.
+
+**From GitHub Packages** — map the scope in `~/.npmrc` first, so `maesttro update`
+resolves against the same registry:
+```ini
+@esatto:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=<GitHub token with read:packages>
+```
+```bash
+npm i -g @esatto/maesttro
+```
+
+**From source** (the package lives in the `stagehand/` directory of the Maesttro monorepo):
+```bash
+npm i -g ./stagehand
+```
+
+---
+
+## Usage
+
+```bash
+maesttro setup /path/to/bot-token.txt   # one-time: build image, create volume, auth bot
+maesttro list                            # see available clients
+maesttro doctor                          # health check anytime
+
+maesttro                                 # launch the default client (claude)
+maesttro opencode                        # launch opencode instead
+maesttro codex                           # launch codex instead
+maesttro bash                            # plain shell inside the sandbox, for debugging
+
+maesttro update                          # bump the package + rebuild image with refreshed configs
+```
+
+---
+
+## Curated clients
+
+Defined in `src/clients.js`, installed in `docker/Dockerfile`, configured via
+`docker/configs/<client>/`:
+
+| Key | Client | Package |
+|---|---|---|
+| `claude` (default) | Claude Code | `@anthropic-ai/claude-code` |
+| `opencode` | opencode | `opencode-ai` |
+| `codex` | OpenAI Codex CLI | `@openai/codex` |
+
+Adding a new client: add an entry to `src/clients.js`, an install line in
+`docker/Dockerfile`, and a `docker/configs/<key>/` directory with any default
+config — then `maesttro update` rebuilds the image with it included.
+
+---
+
+## How `maesttro update` keeps configs current
+
+`docker/configs/<client>/` files are baked into the image at build time —
+they become each client's out-of-the-box defaults inside the sandbox. When you
+publish a new version of `maesttro` with updated curated configs:
+
+```bash
+maesttro update
+```
+
+does two things, in order:
+1. `npm i -g maesttro@latest` — refreshes the installed package files
+   (including the bundled `docker/` directory) in place
+2. Rebuilds the sandbox image from that same, now-refreshed, `docker/`
+   directory
+
+Because the Dockerfile path is resolved relative to the running script's own
+install location, step 2 automatically picks up whatever step 1 just wrote —
+no extra plumbing needed to keep the two in sync.
+
+Your bot identity (in the `maesttro-home` volume) and your project files are
+untouched by an update — only the image (client versions + curated configs)
+gets refreshed.
+
+---
+
+## What's mounted, and why
+
+| Mount | Source | Purpose |
+|---|---|---|
+| `/home/agent` | `maesttro-home` named volume | Bot's persistent identity (`gh` auth, per-client session state). Survives across runs, lives only in Docker. |
+| `/workspace` | current host directory | The project being worked on — repo-level config comes along automatically. |
+| `/home/agent/.claude/skills` (read-only) | `~/agent-shared/skills` on host, if present | Reusable skills/house-style files shared across sessions. Read-only. |
+
+Nothing from your personal `~/.ssh` or `~/.config/gh` is ever mounted.
+
+---
+
+## Package layout
+
+```
+maesttro/
+├── package.json
+├── bin/maesttro.js         # entry point, dispatches subcommands
+├── src/
+│   ├── clients.js            # curated client registry
+│   ├── setup.js               # `maesttro setup`
+│   ├── update.js              # `maesttro update`
+│   ├── doctor.js               # `maesttro doctor`
+│   ├── launch.js                # `maesttro` / `maesttro <client>` / `maesttro list`
+│   └── paths.js                  # locates bundled Dockerfile wherever npm installs the package
+└── docker/
+    ├── Dockerfile
+    └── configs/
+        ├── claude/
+        ├── opencode/
+        └── codex/
+```
+
+## Publishing
+
+Released by CI, not by hand: bumping `version` in `package.json` and merging
+to `main` publishes `maesttro` to npmjs and `@esatto/maesttro` to GitHub
+Packages. `maesttro update` always pulls whatever is tagged `latest` on the
+registry it was installed from.
+
+## Open items
+
+- Fill in real curated defaults in `docker/configs/*` (currently placeholders)
+- Pin exact client CLI versions in the Dockerfile once stable
+- Decide whether each client gets its own bot token/volume for finer audit
+  trail, or shares one (current setup: shared)
+- Homebrew tap as an alternative install path for non-Node users — optional

package/bin/maesttro.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+const { setup } = require("../src/setup")
+const { doctor } = require("../src/doctor")
+const { launch, list } = require("../src/launch")
+const { update } = require("../src/update")
+
+const [, , cmd, ...rest] = process.argv
+
+const HELP = `maesttro — isolated sandbox for local coding agents
+
+Usage:
+  maesttro                Launch the default client (claude) in the sandbox
+  maesttro <client>        Launch a specific client — see \`maesttro list\`
+  maesttro list            Show available clients
+  maesttro setup [token]   One-time: build image, create volume, authenticate bot identity
+  maesttro update          Update the package and rebuild the image with refreshed client configs
+  maesttro doctor          Health check — Docker, image, volume, bot auth, isolation, clients
+  maesttro help            Show this message
+`
+
+async function main() {
+  switch (cmd) {
+    case undefined:
+      launch([])
+      break
+    case "setup":
+      await setup(rest)
+      break
+    case "update":
+      update()
+      break
+    case "doctor":
+      doctor()
+      break
+    case "list":
+      list()
+      break
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(HELP)
+      break
+    default:
+      launch([cmd, ...rest])
+  }
+}
+
+main()

package/docker/Dockerfile

@@ -0,0 +1,25 @@
+FROM node:22-slim
+
+RUN apt-get update && apt-get install -y \
+    git curl gh ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Curated client CLIs — keep in sync with src/clients.js
+RUN npm install -g \
+    @anthropic-ai/claude-code \
+    opencode-ai \
+    @openai/codex
+
+RUN useradd -m -s /bin/bash agent
+USER agent
+WORKDIR /workspace
+
+# Bake curated default configs into each client's config path.
+# These become each client's out-of-the-box defaults inside the sandbox;
+# `maesttro update` refreshes them by rebuilding the image.
+COPY --chown=agent:agent configs/claude/   /home/agent/.claude/
+COPY --chown=agent:agent configs/opencode/ /home/agent/.config/opencode/
+COPY --chown=agent:agent configs/codex/    /home/agent/.codex/
+
+ENTRYPOINT ["/bin/bash", "-lc"]
+CMD ["claude"]

package/docker/configs/claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "_comment": "Curated default settings for Claude Code inside the maesttro sandbox. Replace with your actual house defaults."
+}

package/docker/configs/codex/config.json

@@ -0,0 +1,3 @@
+{
+  "_comment": "Curated default settings for OpenAI Codex CLI inside the maesttro sandbox. Replace with your actual house defaults."
+}

package/docker/configs/opencode/config.json

@@ -0,0 +1,3 @@
+{
+  "_comment": "Curated default settings for opencode inside the maesttro sandbox. Replace with your actual house defaults."
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "maesttro",
+  "version": "0.1.0",
+  "description": "Isolated Docker sandbox for running local coding agents (claude, opencode, codex, ...) under a dedicated bot GitHub identity, with curated configs baked in per client.",
+  "bin": {
+    "maesttro": "./bin/maesttro.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docker"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/esatto/maesttro.git",
+    "directory": "stagehand"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "private": false
+}

package/src/clients.js

@@ -0,0 +1,26 @@
+// Curated list of supported agent clients. Adding a new one here:
+// 1. add the entry below
+// 2. add `RUN npm install -g <npmPackage>` to docker/Dockerfile
+// 3. create docker/configs/<key>/ with any default config to bake in
+// then `maesttro update` (or `agent setup` during dev) picks it up.
+
+module.exports = {
+  claude: {
+    label: "Claude Code",
+    npmPackage: "@anthropic-ai/claude-code",
+    binary: "claude",
+    configDir: "/home/agent/.claude",
+  },
+  opencode: {
+    label: "opencode",
+    npmPackage: "opencode-ai",
+    binary: "opencode",
+    configDir: "/home/agent/.config/opencode",
+  },
+  codex: {
+    label: "OpenAI Codex CLI",
+    npmPackage: "@openai/codex",
+    binary: "codex",
+    configDir: "/home/agent/.codex",
+  },
+}

package/src/doctor.js

@@ -0,0 +1,78 @@
+const { execSync } = require("child_process")
+const { IMAGE, VOLUME } = require("./paths")
+const clients = require("./clients")
+
+function check(label, fn) {
+  try {
+    const detail = fn()
+    console.log(`  [ok]   ${label}${detail ? " — " + detail : ""}`)
+    return true
+  } catch (e) {
+    console.log(`  [fail] ${label}`)
+    return false
+  }
+}
+
+function doctor() {
+  console.log("== maesttro doctor ==\n")
+  let allOk = true
+
+  allOk &= check("Docker daemon reachable", () => {
+    execSync("docker info", { stdio: "ignore" })
+  })
+
+  allOk &= check("Sandbox image built", () => {
+    const out = execSync(
+      `docker image inspect ${IMAGE} --format "{{.Created}}"`,
+    )
+      .toString()
+      .trim()
+    return `built ${out}`
+  })
+
+  allOk &= check("Persistent volume exists", () => {
+    execSync(`docker volume inspect ${VOLUME}`, { stdio: "ignore" })
+  })
+
+  allOk &= check("Bot identity authenticated", () => {
+    const out = execSync(
+      `docker run --rm -v ${VOLUME}:/home/agent ${IMAGE} "gh auth status 2>&1"`,
+    ).toString()
+    const match = out.match(/Logged in to github\.com account (\S+)/)
+    return match ? match[1] : "authenticated"
+  })
+
+  allOk &= check(
+    "Personal SSH key NOT visible inside sandbox (isolation intact)",
+    () => {
+      const out = execSync(
+        `docker run --rm -v ${VOLUME}:/home/agent ${IMAGE} "cat ~/.ssh/id_rsa 2>&1 || echo MISSING"`,
+      ).toString()
+      if (!out.includes("MISSING") && !out.includes("No such file")) {
+        throw new Error(
+          "SSH key is reachable inside the sandbox — isolation broken",
+        )
+      }
+    },
+  )
+
+  for (const [key, c] of Object.entries(clients)) {
+    allOk &= check(`Client available: ${c.label}`, () => {
+      execSync(`docker run --rm ${IMAGE} "which ${c.binary}"`, {
+        stdio: "ignore",
+      })
+    })
+  }
+
+  console.log()
+  if (allOk) {
+    console.log("All checks passed.")
+  } else {
+    console.log(
+      "Some checks failed — run `maesttro setup` or `maesttro update` to fix, or check the failing item above.",
+    )
+    process.exit(1)
+  }
+}
+
+module.exports = { doctor }

package/src/launch.js

@@ -0,0 +1,68 @@
+const { spawnSync, execSync } = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+const { IMAGE, VOLUME } = require("./paths")
+const clients = require("./clients")
+
+const DEFAULT_CLIENT = "claude"
+
+function ensureReady() {
+  try {
+    execSync(`docker image inspect ${IMAGE}`, { stdio: "ignore" })
+    execSync(`docker volume inspect ${VOLUME}`, { stdio: "ignore" })
+  } catch {
+    console.error("Sandbox isn't set up yet. Run `maesttro setup` first.")
+    process.exit(1)
+  }
+}
+
+function list() {
+  console.log("Available clients:\n")
+  for (const [key, c] of Object.entries(clients)) {
+    console.log(`  ${key.padEnd(10)} ${c.label}  (${c.npmPackage})`)
+  }
+  console.log(
+    `\nDefault: ${DEFAULT_CLIENT}. Run \`maesttro <client>\` to pick one, or \`maesttro <client> -- <args>\` to pass args through.`,
+  )
+}
+
+function launch(cmdArgs) {
+  ensureReady()
+
+  const cwd = process.cwd()
+  const sharedSkills =
+    process.env.AGENT_SHARED_SKILLS ||
+    path.join(os.homedir(), "agent-shared", "skills")
+
+  let clientKey = DEFAULT_CLIENT
+  let extraArgs = []
+
+  if (cmdArgs.length > 0 && clients[cmdArgs[0]]) {
+    clientKey = cmdArgs[0]
+    extraArgs = cmdArgs.slice(1)
+  } else if (cmdArgs.length > 0) {
+    // not a known client — treat the whole thing as a raw command, e.g. `maesttro bash`
+    return runRaw(cmdArgs.join(" "), cwd, sharedSkills)
+  }
+
+  const client = clients[clientKey]
+  const command = [client.binary, ...extraArgs].join(" ")
+  runRaw(command, cwd, sharedSkills)
+}
+
+function runRaw(command, cwd, sharedSkills) {
+  const mounts = ["-v", `${VOLUME}:/home/agent`, "-v", `${cwd}:/workspace`]
+  if (fs.existsSync(sharedSkills)) {
+    mounts.push("-v", `${sharedSkills}:/home/agent/.claude/skills:ro`)
+  }
+
+  const result = spawnSync(
+    "docker",
+    ["run", "-it", "--rm", ...mounts, "-w", "/workspace", IMAGE, command],
+    { stdio: "inherit" },
+  )
+  process.exit(result.status ?? 0)
+}
+
+module.exports = { launch, list }

package/src/paths.js

@@ -0,0 +1,12 @@
+const path = require("path")
+
+// __dirname here is <install>/src — package root is one level up.
+// This works identically whether installed via `npm link`, `npm i -g .`,
+// or from the registry — npm always keeps the package's own files together.
+const PKG_ROOT = path.resolve(__dirname, "..")
+const DOCKERFILE_DIR = path.join(PKG_ROOT, "docker")
+
+const IMAGE = "maesttro-runner:latest"
+const VOLUME = "maesttro-home"
+
+module.exports = { PKG_ROOT, DOCKERFILE_DIR, IMAGE, VOLUME }

package/src/setup.js

@@ -0,0 +1,101 @@
+const { execSync, spawnSync } = require("child_process")
+const readline = require("readline")
+const fs = require("fs")
+const { DOCKERFILE_DIR, IMAGE, VOLUME } = require("./paths")
+
+function run(cmd, opts = {}) {
+  return execSync(cmd, { stdio: "inherit", ...opts })
+}
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+  return new Promise((resolve) =>
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve(answer.trim())
+    }),
+  )
+}
+
+async function setup(args) {
+  console.log("== maesttro setup ==\n")
+
+  // 1. Docker present?
+  try {
+    execSync("docker info", { stdio: "ignore" })
+  } catch {
+    console.error(
+      "Docker doesn't seem to be running. Start Docker Desktop (or the docker daemon) and try again.",
+    )
+    process.exit(1)
+  }
+
+  // 2. Build image from the Dockerfile bundled inside this package
+  console.log(
+    "-> Building sandbox image (this pulls node:22-slim + installs CLIs, first run only)...",
+  )
+  run(`docker build -t ${IMAGE} "${DOCKERFILE_DIR}"`)
+
+  // 3. Create persistent volume
+  console.log("\n-> Ensuring persistent volume exists...")
+  execSync(`docker volume create ${VOLUME}`, { stdio: "ignore" })
+
+  // 4. Get bot token — file path arg, or interactive paste
+  const tokenPath = args[0]
+  let token
+  if (tokenPath && fs.existsSync(tokenPath)) {
+    token = fs.readFileSync(tokenPath, "utf8").trim()
+  } else {
+    console.log(
+      "\nPaste the bot account's fine-grained GitHub token (input hidden not supported in plain readline — clear your scrollback after):",
+    )
+    token = await ask("Token: ")
+  }
+  if (!token) {
+    console.error(
+      "No token provided. Run `maesttro setup /path/to/token.txt` or paste one when prompted.",
+    )
+    process.exit(1)
+  }
+
+  // 5. Authenticate the bot identity into the volume
+  console.log("\n-> Authenticating bot identity into the sandbox volume...")
+  const auth = spawnSync(
+    "docker",
+    [
+      "run",
+      "-i",
+      "--rm",
+      "-v",
+      `${VOLUME}:/home/agent`,
+      IMAGE,
+      "gh auth login --with-token && gh auth setup-git",
+    ],
+    { input: token, stdio: ["pipe", "inherit", "inherit"] },
+  )
+  if (auth.status !== 0) {
+    console.error(
+      "\nToken authentication failed — check the token is valid and has repo access.",
+    )
+    process.exit(1)
+  }
+
+  // 6. Verify isolation
+  console.log("\n-> Verifying isolation...")
+  console.log("   gh identity inside sandbox:")
+  run(`docker run --rm -v ${VOLUME}:/home/agent ${IMAGE} "gh auth status"`)
+  console.log("   personal SSH key should NOT be visible:")
+  run(
+    `docker run --rm -v ${VOLUME}:/home/agent ${IMAGE} "cat ~/.ssh/id_rsa 2>&1 || true"`,
+  )
+
+  console.log(
+    "\nSetup complete. Run `maesttro` from any project directory to start a session,",
+  )
+  console.log("or `maesttro list` to see available clients.")
+}
+
+module.exports = { setup }

package/src/update.js

@@ -0,0 +1,22 @@
+const { execSync } = require("child_process")
+const { DOCKERFILE_DIR, IMAGE, PKG_ROOT } = require("./paths")
+const { name: packageName } = require(`${PKG_ROOT}/package.json`)
+
+function update() {
+  console.log("== maesttro update ==\n")
+
+  console.log(`-> Updating ${packageName} package...`)
+  execSync(`npm i -g ${packageName}@latest`, { stdio: "inherit" })
+
+  console.log("\n-> Rebuilding sandbox image with refreshed client configs...")
+  execSync(`docker build -t ${IMAGE} "${DOCKERFILE_DIR}"`, { stdio: "inherit" })
+
+  console.log(
+    "\nUpdate complete. Bot identity and your project files are untouched —",
+  )
+  console.log(
+    "only the image (client versions + curated configs) was refreshed.",
+  )
+}
+
+module.exports = { update }