Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,7 @@ guide, with a CI example, is [docs/headless-run.md](docs/headless-run.md).
| `harness-probe.js` | The impure half of the above: spawns the probes for all eight harnesses concurrently with a 5s ceiling, `shell: false` (so a shell function cannot answer for the binary) and stdin on `/dev/null` (one harness with no key opens a browser and blocks forever), then formats one row per harness. Read-only — it never writes. |
| `harness-auth.js` | `e2b-box auth` itself: probe, show, ask **once** for the whole batch, write. `buildPlan` turns probe rows into what will be kept and is pure given its file reader; `renderAuthToml` and `formatPlan` are pure; only `writeAuthFile` touches disk. It writes a GENERATED `auth.toml` beside `config.toml` at mode `0600`, regenerated whole on every run, and never touches `config.toml` — one writer each is what makes "hand-written always wins" true. ADR 0009's split lives here: a value read out of a **file** is stored, a value seen only in the **shell** records the variable's NAME and nothing else. Missing credentials are reported and never prompted for; `--yes` skips the question, and no terminal plus no flag writes nothing. It also warns when a variable it recorded by NAME is invisible to a login shell (`invisibleToLoginShell`, one `bash -lc` for the whole batch, names only in both directions) — herdr launches plugin commands from one, so a key exported from a zsh rc is found here and absent at create time. Two entry points, one implementation: the verb a user types, and `install.sh`'s `harness_discovery` on first run — the installer shells out to the very same subcommand with `--yes` (a build step has no TTY), indents its report, and treats any failure as a report rather than a failed install. |
| `run-agent.js` | The headless agent table `e2b-box run` drives a box with: `DEFAULT_RUN_AGENTS` (template → that vendor's verified **non-interactive** command, `claude -p`, `codex exec`, `opencode run`, `amp -x`, each with its skip-approvals flag, each reading the task from `TASK_FILE` inside the box, never from argv) and `runCommand` (`[run.agents]` over those, by key presence, so `""` means "no headless agent"). Kept apart from `fleetAgents` on purpose: the interactive command for a template is not a flag away from its headless one. All eight shipped agent templates have one; `base` and a user's own template have no default and `run` refuses them by name. Also the CLI bash calls (`<template>`, `--task-path`, `--shipped`). |
| `model-pin.js` | `[templates.<name>] model` / `reasoning`, delivered the way each harness reads its defaults: `modelEnv` (the variables for the env-route harnesses, claude and opencode, plus `HERDR_E2B_MODEL` / `HERDR_E2B_REASONING` on every pinned box) and `pinCommand` (one-line commands that write the file-route harnesses' own config: codex `config.toml`, grok `[models]`, droid and prime `settings.json`, muse `reasoning_effort`). Same rules as the seeds: one line, variable names never values, never overwrite a key that is set. `resolveEnv` merges the env below the user's own table; `provision.js` runs the command right after the seed. Pure, and the commands are executed by `test/model-pin.test.js` against fake homes. |
| `fleet-seed.js` | The first-run state a member's agent needs before it will work instead of asking questions: `DEFAULT_SEEDS` (the verified `~/.claude.json` / `~/.codex/auth.json` shapes, as one-line POSIX sh) and `seedCommand` (`[fleet.seed]` over those, by key presence, so `""` means "seed nothing"). The shell lives here rather than in bash so `node --test` can execute it. Every command names the credential's **variable**, computes what it needs (Claude approves a key by its last 20 characters) inside the box, and refuses to overwrite a file that already exists. |

### Grader — `bin/e2b-bench` + `tui/src/{bench,grade}.rs` + `tui/src/bin/e2b-bench.rs`
Expand Down
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,16 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### Added

- `[templates.<name>] model = "…"` and `reasoning = "…"`: pin which model a
template's agent uses and how hard it thinks, for every box booted from it
(`open`, `fleet`, `run`). Delivered the way each harness reads its defaults
(`src/model-pin.js`): claude and opencode through their environment
(`ANTHROPIC_MODEL`, `CLAUDE_CODE_EFFORT_LEVEL`, `OPENCODE_CONFIG_CONTENT`),
codex, grok, droid, prime and muse through their own config file, written right
after the first-run seed and never over a key that is already set. Every pinned
box also carries `HERDR_E2B_MODEL` / `HERDR_E2B_REASONING` for your own launch
commands. `[templates.<name>.env]` still wins for the same variable.

- `e2b-box run` drives every shipped agent template headless: `grok`
(`--prompt-file`), `droid` (`droid exec -f`), `muse` (`muse exec --prompt-file`)
and `prime` (`prime-agent -p`) join `claude`, `codex`, `opencode` and `amp` in
Expand Down
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,8 +188,21 @@ OPENAI_API_KEY = "sk-…"

[sandbox.env] # optional — every box, whatever it booted from
HTTPS_PROXY = "http://proxy.internal:3128"

[templates.opencode] # optional: which model, how hard it thinks
model = "openrouter/qwen/qwen3.8-max-0902"
[templates.codex]
model = "gpt-5.4"
reasoning = "high"
```

`model` and `reasoning` pin what a template's agent runs, for every box booted
from it (`open`, `fleet`, `run`), in the harness's own way: claude and opencode
read a variable, codex, grok, droid, prime and muse get their config file written
right after the first-run seed. An agent left alone runs whatever its provider
ranks first, which on an OpenRouter key was an image model. Per-harness keys and
what each can pin are in `config.example.toml`.

| Agent | Template | Key it reads | Started unattended as |
| --- | --- | --- | --- |
| Claude Code | `claude` | `CLAUDE_CODE_OAUTH_TOKEN` (a `claude setup-token` token, on a Pro/Max/Team subscription) or `ANTHROPIC_API_KEY` (a Console key) | `claude --dangerously-skip-permissions` |
Expand Down
40 changes: 40 additions & 0 deletions config/config.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,46 @@ server_port = 3000
# # ANTHROPIC_API_KEY = "sk-ant-…"
# # OPENAI_API_KEY = "sk-…"

# Which MODEL a template's agent uses, and how hard it thinks, for EVERY box booted
# from that template: open, fleet and run alike. Every harness has a default and a
# TUI to change it; a box has nobody at the TUI, so an agent left alone runs whatever
# its vendor or provider ranks first (an opencode member on an OpenRouter key came up
# on an image model with no tool use). Set here once instead of `-m` in every launch
# command.
#
# Both keys are optional, free strings, each harness's own vocabulary:
#
# template model reasoning
# claude a Claude model id or alias low | medium | high | xhigh
# codex an OpenAI model id minimal | low | medium | high | xhigh
# grok a grok model id (grok-build, grok-4.5) none … max
# droid a Factory model id (glm-5.2, kimi-k3) off | low | medium | high | max, per model
# prime "<provider>/<model>", split at the prime's thinking levels (off … max)
# first slash (openai-codex/gpt-6-astra,
# prime-inference/z-ai/glm-5.2)
# opencode "<provider>/<model>" as `opencode (not pinned: opencode does reasoning as
# models` prints it per-model variants)
# muse (not pinned: no verified settings key, none … ultra
# use --model in your agent command)
# amp (nothing: amp has no model setting, `--mode low|medium|high|ultra` is its knob)
#
# How it reaches the agent is the harness's own way (src/model-pin.js): claude and
# opencode read it from the environment (ANTHROPIC_MODEL, CLAUDE_CODE_EFFORT_LEVEL,
# OPENCODE_CONFIG_CONTENT); codex, grok, droid, prime and muse get it written into
# their config file right after the first-run seed, and only for keys that file does
# not already set. Every pinned box also carries HERDR_E2B_MODEL and
# HERDR_E2B_REASONING, so a CLI this plugin has no route for can still take it from
# your own [fleet.agents] / [run.agents] command: `mine --model "$HERDR_E2B_MODEL"`.
# A value in [templates.<name>.env] for the same variable wins over the pin. Applied
# at CREATE, like everything else in this table.
# [templates.opencode]
# model = "openrouter/qwen/qwen3.8-max-0902"
# [templates.codex]
# model = "gpt-5.4"
# reasoning = "high"
# [templates.claude]
# reasoning = "xhigh"

[dashboard]
# View shortcuts are configured separately in Herdr's config.toml:
# e2b-dev.herdr-e2b.dashboard — e2b-dash (pane view)
Expand Down
19 changes: 19 additions & 0 deletions docs/headless-run.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,25 @@ The skip-approvals flags are the point of a box: disposable, isolated from your
machine, nobody attached to approve an edit. They are not a cage. The box has
network egress and holds the credential `[templates.<name>.env]` gave it.

## Model and reasoning

`run` does not take a model flag. The model is the template's, set once in config
and applied to every box booted from it, headless or not:

```toml
[templates.opencode]
model = "openrouter/qwen/qwen3.8-max-0902"
[templates.codex]
model = "gpt-5.4"
reasoning = "high"
```

The plugin delivers it the way each harness reads it (environment for claude and
opencode, the harness's own config file for codex, grok, droid, prime and muse;
`config.example.toml` has the per-harness table). Every pinned box also carries
`HERDR_E2B_MODEL` and `HERDR_E2B_REASONING`, so a `[run.agents]` command of your
own can use `--model "$HERDR_E2B_MODEL"`.

## What becomes of the box

| flag | afterwards | when |
Expand Down
16 changes: 15 additions & 1 deletion src/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import os from "node:os"
import TOML from "@iarna/toml"

import { HARNESSES, readHarnessFile } from "./harnesses.js"
import { modelEnv, normalizePin } from "./model-pin.js"
import { AUTH_PATH, CONFIG_PATH, CONNECTIONS_DIR } from "./config-paths.js"
import { applyConnection, readConnections, selectConnection } from "./connections.js"
export { AUTH_PATH, CONFIG_PATH } from "./config-paths.js"
Expand Down Expand Up @@ -264,20 +265,26 @@ function nameTable(raw) {
export function resolveEnvConfig({ sandbox = {}, templates = {} } = {}) {
const byTemplate = {}
const prefer = {}
const models = {}
if (templates && typeof templates === "object" && !Array.isArray(templates)) {
for (const [template, section] of Object.entries(templates)) {
const name = String(template).trim()
if (!name) continue
const env = envTable(section?.env)
if (Object.keys(env).length) byTemplate[name] = env
// `model` / `reasoning`: which model that template's agent uses and how hard it
// thinks, for every box booted from it. Free strings, each harness has its own
// vocabulary; src/model-pin.js knows where each harness reads them from.
const pin = normalizePin(section)
if (pin) models[name] = pin
// `prefer = "env"` — the documented way to take back the precedence a
// discovered SESSION otherwise wins (ADR 0010). Only that one value means
// anything; anything else is left unset rather than guessed at, so a typo
// cannot quietly change which credential a box gets.
if (String(section?.prefer ?? "").trim() === "env") prefer[name] = "env"
}
}
return { envShared: envTable(sandbox?.env), envByTemplate: byTemplate, templatePrefer: prefer }
return { envShared: envTable(sandbox?.env), envByTemplate: byTemplate, templatePrefer: prefer, templateModels: models }
}

/**
Expand Down Expand Up @@ -433,6 +440,11 @@ export function resolveEnv(cfg, template, env = {}, now = Date.now(), readFile =
const session = sessionValue(cfg, template, now, readFile)
const merged = {
...(cfg?.templateEnvDefaults?.[template] || {}),
// The model pin (`[templates.<name>] model` / `reasoning`), as the variables the
// harness reads plus the two shared ones the file-route pin command reads
// (src/model-pin.js). Below the user's own `env` table, so a hand-written
// ANTHROPIC_MODEL still wins over the pin.
...modelEnv(template, cfg?.templateModels?.[template]),
// The discovered rung has two halves, and forwarding wins between them: a name
// resolves from THIS run's environment, while a stored value is a copy taken
// whenever `e2b-box auth` last ran. When both name the same box variable the
Expand Down Expand Up @@ -923,6 +935,8 @@ export function loadConfig() {
// hand-written value — and `templatePrefer` is how the user takes that back.
envSession: auth.envSession,
templatePrefer: env.templatePrefer,
// `[templates.<name>] model` / `reasoning` → {model, reasoning} per template.
templateModels: env.templateModels,
// Shipped per-template env (behaviour, never credentials). Carried through
// from DEFAULTS rather than read from the file: nothing in config.toml sets
// it, and resolveEnv puts the user's own tables OVER it.
Expand Down
Loading
Loading