DynoCap
Menu

CLI JSON Schemas

When passed --json, management commands print a single line-delimited JSON payload to stdout. Absent values are explicitly represented as null, timestamps are integer Unix epoch seconds (UTC), and consumers must tolerate extra fields.

1. Listing Schema (dynocap ls --json)

Returns an array of sandbox and task records:

JSON
[
  {
    "id": "task-8f92b7c1",
    "name": "demo",
    "kind": "task",
    "phase": "running",
    "runtime": "node:24",
    "network": "none",
    "sandboxExpiresAtUnix": 1794958200,
    "resultExpiresAtUnix": 1795563000,
    "resultDirectory": null
  }
]

Fields

Field Type Description
id string Immutable task ID or raw sandbox name.
name string | null Friendly name assigned at creation, or null.
kind string "task" (project sandbox) or "sandbox" (raw).
phase string Lifecycle phase: "booting", "running", "stopping", "stopped", "completed", "failed".
runtime string Runtime identifier (e.g. "node:24", "minimal").
network string | null "none", "filtered", "nat", or null.
sandboxExpiresAtUnix integer | null Absolute TTL deadline in seconds. null if VM is stopped.
resultExpiresAtUnix integer | null Absolute retention deadline for logs and diffs (7 days from creation).
resultDirectory string | null Absolute path to exported host result directory, or null.

2. Creation Schema (dynocap clone --json)

Returned by dynocap clone and dynocap task start:

JSON
{
  "id": "task-8f92b7c1",
  "name": "demo",
  "phase": "running",
  "runtimeDigest": "sha256:d8b2...",
  "createdAtUnix": 1794956400,
  "expiresAtUnix": 1794958200,
  "sourceUrl": null,
  "sourceRevision": "4b92c41"
}

3. Finish Schema (dynocap finish --json)

Returned when a task is finalized and exported:

JSON
{
  "applyCommand": "git apply --check '/Users/user/.dynocap/tasks/task-8f92b7c1/result/changes.patch' && git apply '/Users/user/.dynocap/tasks/task-8f92b7c1/result/changes.patch'",
  "baseline": "imported_checkout_including_uncommitted_changes",
  "hostCheckout": "unchanged",
  "id": "task-8f92b7c1",
  "name": "demo",
  "patch": "/Users/user/.dynocap/tasks/task-8f92b7c1/result/changes.patch",
  "phase": "completed",
  "priorCommandFailure": false,
  "resultDirectory": "/Users/user/.dynocap/tasks/task-8f92b7c1/result",
  "resultExpiresAtUnix": 1795563000,
  "sandbox": "stopped",
  "sensitivePaths": [
    {
      "kind": "added",
      "path": ".husky/pre-commit",
      "reason": "Git hooks run on commit"
    }
  ]
}

sensitivePaths lists changes that can run code on the host or in CI once the patch is applied: Git hooks, CI workflows, editor tasks, package and build scripts, .envrc, symlinks, and files that become executable. It is empty when there are none. Each entry also appears in changes.json as sensitive.

4. Inspection Schema (dynocap inspect --json)

Returned by dynocap inspect NAME:

JSON
{
  "id": "task-8f92b7c1",
  "name": "demo",
  "kind": "task",
  "taskPhase": "completed",
  "sandboxPhase": "stopped",
  "runtime": "node:24",
  "network": "none",
  "createdAtUnix": 1794956400,
  "sandboxExpiresAtUnix": 1794958200,
  "resultExpiresAtUnix": 1795563000,
  "resultDirectory": "/Users/user/.dynocap/tasks/task-8f92b7c1/result",
  "patchPath": "/Users/user/.dynocap/tasks/task-8f92b7c1/result/changes.patch",
  "sourcePath": "/tmp/demo-project",
  "sourceRevision": "4b92c41"
}

5. Removal Schema (dynocap rm --json)

Returned by dynocap rm and dynocap destroy:

JSON
{
  "target": "demo",
  "removed": true,
  "purged": false
}

6. Doctor Schema (dynocap doctor --json)

Diagnostic report of host readiness. Findings go to stdout in both modes; the command exits 1 when a required check fails.

JSON
{
  "ok": false,
  "home": "/Users/user/.dynocap",
  "arch": "aarch64",
  "runtimes": [{ "name": "node", "version": "24" }],
  "checks": [
    {
      "id": "platform",
      "status": "ok",
      "message": "macOS 13+; guest architecture aarch64",
      "recovery": null,
      "fix": null
    },
    {
      "id": "runtime",
      "status": "error",
      "message": "Runtime node:24 is not prepared for aarch64 yet.",
      "recovery": "Run dynocap doctor --fix to prepare node:24 (downloads verified inputs; takes a few minutes).",
      "fix": "prepare-runtime"
    }
  ]
}
  • status is ok, warning, or error. Only error makes ok false.
  • runtimes is the runtime that was checked: --runtime, or the one the project’s files call for. It is empty when there was no project. The runtime check then lists the prepared runtimes and is a warning if there are none.
  • fix is the repair doctor --fix performs for this check on this machine (restart-daemon, build-images, or prepare-runtime), or null when the check passes or needs a manual step. When it is set, recovery names the exact command.

With --fix, the report describes the state after repairs and adds repairs, in the order they ran:

JSON
"repairs": [
  {
    "fix": "build-images",
    "status": "fixed",
    "summary": "Building the guest image for aarch64",
    "recovery": null,
    "logPath": "/Users/user/.dynocap/image-build-....log",
    "note": null,
    "seconds": 20.4
  }
]

status is fixed, failed, or skipped. A runtime repair is skipped when the daemon restart failed. note reports side effects, such as where mismatched image files were moved.

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