CLI Command Reference

Every exposed command, its output, and whether it accepts --json.

Primary Workflow Commands

dynocap clone

Import a local project directory or Git URL into an isolated sandbox.

dynocap clone SOURCE NAME [options]

• Arguments:
  • SOURCE: Path to a local directory / Git checkout, or an HTTPS/SSH Git repository URL.
  • NAME: Friendly name for the sandbox (e.g. agent-fix, demo).
• Options:
  • --runtime <name:version>: Runtime the sandbox uses. For a local directory, the default comes from its files: package.json → node:24; pyproject.toml, uv.lock, requirements.txt, setup.py, or Pipfile → python:3.14; go.mod → go:1.27. clone prints the runtime it chose. Otherwise, and for repository URLs, the default is shell:1 (bash, git and ssh). The MCP server and SDK follow the same rule when runtimes is omitted.
  • --network <none|filtered|nat>: Outbound network policy. Default: none.
  • --ttl <seconds>: Maximum lifetime from creation (30s to 86400s). Default: 1800 (30m).
  • --cpus <count>: Number of virtual CPUs. Default: 2.
  • --memory <MB>: RAM in megabytes. Default: 1024.
  • --history <branches|head|none>: Git history a local directory brings in. branches (the default) keeps local branches, tags and remote-tracking refs; head keeps only the checked-out commit’s history; none imports files only. The stash, reflogs, refs/original, other worktrees, submodule repositories and unreachable objects are never imported. A repository URL rejects this flag.
  • --json: Output creation object to stdout as JSON.

dynocap exec

Execute a command inside a running sandbox.

dynocap exec NAME [options] -- COMMAND [args...]

• Arguments:
  • NAME: Friendly name or immutable task ID (task-…).
  • -- COMMAND: Command and arguments to execute inside the guest.
• Options:
  • --timeout <seconds>: Execution deadline. Default: 60. Exceeding exits with 124.
  • -t, --tty: Allocate a guest pseudo-terminal (PTY) combining stdout and stderr.
  • --cwd <path>: Working directory inside guest. Default: /workspace (project) or / (raw).
  • --env <KEY=VAL>: Set guest environment variable (repeatable).
  • -i, --interactive: Keep standard input open for interactive input until EOF.
  • --no-input: Send immediate EOF to guest stdin.

dynocap shell

Open an interactive /bin/sh shell in a running sandbox.

dynocap shell NAME

• Behavior:
  • Requires an interactive terminal on the host.
  • Inherits terminal window dimensions and forwards SIGWINCH resize events.
  • Has no command timeout; session stays open until exit or sandbox TTL expires.
  • Exiting the shell leaves the sandbox running.

dynocap diff

Output a unified Git diff of all changes made in /workspace since creation.

dynocap diff NAME

• Output: Streams clean, standard unified diff bytes (diff --git ...) directly to stdout.
• Note: Does not alter, stop, or finish the running sandbox.

dynocap finish

Export verified patch and command logs to the host, and destroy the guest microVM.

dynocap finish NAME [options]

• Options:
  • --json: Output finish result object as JSON.
• Behavior:
  • Closes command admission immediately.
  • Exports changes.patch, full changed files, and execution journals into the host result directory.
  • Destroys the virtual machine and its disposable disk.
  • Prints shell-quoted git apply instructions.
  • Retains exported results on the host for 7 days from creation.

dynocap logs

Inspect or replay recorded execution output from project tasks.

dynocap logs NAME [options]

• Options:
  • --list: Print a table of all recorded command executions for this task.
  • --exec <ID>: Replay stdout and stderr of a specific zero-based execution index.
• Default: Replays stdout and stderr of the most recent execution.

dynocap ls

List active sandboxes and retained task results.

dynocap ls [options]

• Options:
  • --json: Output listing array as JSON.
• Output Columns:
  • NAME/ID: Friendly name or immutable ID.
  • KIND: task (project task) or sandbox (raw).
  • PHASE: booting, running, stopping, stopped, completed, or failed.
  • RUNTIME: Runtime identifier (e.g. node:24 or minimal).
  • NETWORK: none, filtered, or nat.
  • TTL: Remaining time until sandbox expiration.
  • RETENTION: Remaining time until retained host results expire (7 days from creation).

dynocap inspect

Display full metadata for an active or retained task.

dynocap inspect NAME_OR_ID [options]

• Options:
  • --json: Output complete inspection object as JSON.

dynocap rm

Release a sandbox name or purge retained results.

dynocap rm NAME_OR_ID [options]

• Options:
  • --force, -f: Required to remove a sandbox that is still running or finalizing.
  • --purge: Deletes the managed task record, execution logs, and published result directory.
  • --json: Output removal result object as JSON.

dynocap doctor

Check that this Mac can run sandboxes. Each failed check says what is wrong and what to run next. Without --fix, doctor changes nothing.

dynocap doctor [PROJECT] [options]

The runtime checked is the one PROJECT (default: the current directory) uses, judged by its files as clone does. With no project, no runtime is required.

• Options:
  • --fix: Repair failed checks, then check again. Restarts a daemon from an older build (never one with running sandboxes), builds the guest image, and prepares the runtime. Builds need the dynocap checkout and Go.
  • --runtime <name:version>: Check this runtime instead of the project’s (node:24, node:22, python:3.14, go:1.27, shell:1).
  • --json: Output diagnostic report as JSON.

dynocap runtime prepare

Download, build, and verify a runtime rootfs disk.

dynocap runtime prepare [REPO_PATH] [options]

• Arguments:
  • REPO_PATH: Path to the dynocap source tree (defaults to .).
• Options:
  • --runtime <name:version>: Runtime to prepare. Default shell:1. Supported: node:24 and node:22 (npm), python:3.14 (uv), go:1.27 (Go modules), and shell:1 (bash, git and ssh; no language). An unsupported selection fails and lists the supported ones; no version is substituted.
  • --json: Output preparation result object as JSON.

Advanced & Raw Sandbox Commands

dynocap run

Boot an ephemeral raw Linux microVM without a project workspace.

dynocap run [options]

• Options:
  • --name <name>: Assign a friendly name.
  • --network <none|filtered|nat>: Network mode. Default: none.
  • --ttl <seconds>: Lifetime in seconds. Default: 1800.
  • --cpus <count>: Number of vCPUs. Default: 1.
  • --memory <MB>: Memory in megabytes. Default: 1024.
  • --json: Output JSON creation result.

dynocap ps

List only raw sandboxes (kind == sandbox). Supports --json.

dynocap ps [options]

dynocap destroy

Alias for dynocap rm without --purge. Requires --force for running sandboxes.

dynocap destroy NAME_OR_ID [--force]

dynocap daemon

Run the DynoCap background daemon in the foreground.

dynocap daemon [options]

• Emits daemon logs directly to stdout/stderr. Used primarily for debugging daemon lifecycle.

This page is also plain Markdown, for agents and for you.