dynoboxdocs

Dynobox Docs

Dynobox is a local test runner for agent and skill workflows. You describe a task, choose one or more local agent harnesses, and assert on observable behavior such as tool calls, shell commands, files in the scenario work directory, transcripts, HTTP requests, and final messages.

Dynobox is useful when you want repeatable checks for agent behavior before shipping a prompt, skill, or workflow change.

Start Here

  • Getting Started: install the CLI, scaffold a dyno, and run your first scenario.
  • How It Works: follow a job from its fresh work directory through evidence capture, assertion evaluation, and the recorded result.
  • Agent Skills: install AI agent skills for creating dynos and debugging failed runs.
  • Config Authoring: write JavaScript, TypeScript, or YAML dynos with the @dynobox/sdk helpers.
  • CLI Reference: commands, flags, output modes, JSON reports, and exit behavior.
  • CI Integration: temporary GitHub Actions pattern from the dynobox/skills repo.

Dynobox Dashboard

The web dashboard lives at dash.dynobox.xyz. It is where you create short-lived CLI tokens for authenticated Dynobox commands. Use dynobox login, open the dashboard URL it prints, create a token, and paste that token back into the CLI.

Authenticated CLI runs can upload compact summaries with dynobox run --save-run. When an upload succeeds, the CLI prints a dashboard URL for reviewing or sharing the saved run. Run owners can compare compatible jobs across saved runs to inspect assertion outcome and evidence changes.

Set DYNOBOX_UPLOAD_URL to post the same schema v4 JSON payload to your own endpoint without Dynobox authentication. Saved-run data is not redacted, so do not upload runs that may contain secrets. See Saving Runs for the payload and custom-endpoint contract.

Agent Resources

The docs site publishes agent-oriented entry points for retrieval and indexing:

  • llms.txt: concise docs map with canonical HTML, markdown, source, package, and command references.
  • llms-full.txt: the full public docs corpus as one plain-text file.
  • docs-index.json: machine-readable page metadata, topics, headings, and canonical URLs.
  • Raw markdown pages such as getting-started.md for direct ingestion without HTML parsing.

What Dynobox Tests

Dynobox runs each scenario in a fresh temporary work directory. Setup commands create the fixture, the selected harness performs the task, and assertions evaluate what happened.

Work directories separate job files but are not security sandboxes. Dynos are trusted code: JavaScript and TypeScript configs are imported, and setup, verification, and harness processes may access the host according to their permissions.

You can assert:

  • Tool calls, including path-aware file tool calls and raw shell escape hatches.
  • Normalized observed shell commands with command.called(...) and command.notCalled(...).
  • Experimental scenario-scoped CLI mocks with static, sequential, or handler-based responses and recorded calls available to command assertions.
  • Skill instruction file references with skill.referenced(...).
  • Ordered behavior sequences and valid alternatives with sequence.inOrder(...) and anyOf(...), including nested verify.command(...) branches.
  • Work-directory artifacts with artifact.exists(...), artifact.notExists(...), artifact.contains(...), and artifact.unchanged(...).
  • Harness transcript and final-message text.
  • HTTP requests made by local child-process tools that honor proxy environment variables.
  • Post-harness verification commands with verify.command(...).

Use dynobox run --iterations <count> to repeat every selected scenario/harness pair and render inline pass-rate sparklines such as .F....

Supported Harnesses

Dynobox currently runs local scenarios through:

  • Claude Code via the claude executable.
  • OpenAI Codex via the codex executable.
  • OpenCode via the opencode executable.
  • Pi via the pi executable.
  • Cursor CLI via the cursor-agent executable.
  • Google Antigravity CLI 1.1.14 or newer via the agy executable.

Each harness must already be installed, authenticated, and available on PATH.

Supported Config Formats

Dynobox discovers *.dyno.{mjs,js,ts,mts,yaml,yml} files recursively when you run a directory. Explicit file paths can use non-*.dyno.* names, such as dynobox.config.ts, as long as they are loadable Dynobox configs.

Supported authoring formats:

  • TypeScript or JavaScript with defineDyno(...) from @dynobox/sdk.
  • YAML with the same type-discriminated assertion objects that SDK helpers return.

JavaScript and TypeScript dynos using defineDyno(...) automatically attach an adjacent fixtures/ directory to scenarios that do not set fixtures explicitly. Dynos authored under .agents/skills/<name>/ or .claude/skills/<name>/ also automatically copy that skill's SKILL.md into each scenario work directory.

CommonJS config files (.cjs and .cts) are not supported because the SDK is ESM-only.

Current Limits

Dynobox is under active development and is currently focused on local execution. These areas are not complete yet:

  • CLI mocking is experimental and its authoring and reporting contracts may change between releases.
  • HTTP capture for harness-native web tools and binaries that ignore proxy/CA environment variables.
  • Hosted or remote runner execution.