dynobox

Cross-harness testing for multi-step agent and skill workflows.

Dynobox runs agent scenarios through local harnesses such as Claude Code and Codex, captures observable behavior, and evaluates assertions against what actually happened.

• Site: dynobox.xyz
• Docs: docs.dynobox.xyz
• GitHub: github.com/dynobox/dynobox

Install

npm install -g dynobox

The selected harness executable must already be installed, authenticated, and available on PATH.

Quick Start

Create a starter dyno file, then run it:

dynobox init
dynobox run

dynobox init writes dynobox/example.dyno.mjs by default. dynobox run with no argument discovers *.dyno.{mjs,js,ts,mts,yaml,yml} files recursively under the current directory.

Scope a run to a directory or file:

dynobox run dynobox
dynobox run my-skill.dyno.yaml

Pick a harness at runtime when needed:

dynobox run --harness claude-code
dynobox run --harness codex
dynobox run --harness claude-code,codex

Repeat each selected scenario/harness pair when you want a pass-rate signal:

dynobox run --harness claude-code,codex --iterations 5

What You Can Assert

Dynobox supports assertions for:

• Tool calls with tool.called(...) and tool.notCalled(...).
• Shell command matchers with equals, includes, startsWith, or matches.
• File tool path matchers such as tool.called('read_file', {path: 'package.json'}).
• Ordered tool-call sequences.
• Skill instruction loading.
• Work-directory artifacts.
• Harness transcript and final response text.
• HTTP requests from local child-process tools that honor proxy environment variables.

Output Modes

• --quiet: compact dots-and-failures output for CI.
• --verbose: expand scenario details even when they pass.
• --debug: include work directory, artifact paths, and debug log paths.
• --reporter json: emit newline-delimited JSON reports.
• --iterations <count>: repeat each selected scenario/harness pair.
• --permission-mode default|dangerous: override harness permission behavior.

Auth

Use dynobox login to paste a dashboard-generated CLI token into local config, then dynobox whoami to verify the saved identity. dynobox logout removes the saved token. CLI tokens expire after 24 hours; when a token expires, run dynobox login again to re-authenticate.

Documentation

• Getting Started
• Config Authoring
• CLI Reference