Artifacts

Every nax run writes a durable local record under .nax/. The artifact tree is the handoff surface between workflow steps, the dashboard, follow-up prompts, and later debugging sessions.

Artifact layout

• .nax
  • workflows
    • <workflow-run-id>
      • workflow.json
      • events.jsonl
      • artifacts
      • blobs
  • agent-runners
  • agent-sessions
  • blob-refs.jsonl

latest symlinks are created when the filesystem supports them. The most common handoff file is:

.nax/workflows/latest/artifacts/summary.md

Handoff paths

nax handoff
nax handoff -c
nax handoff --session <id> --copy
nax handoff --workflow <id> --flow review
nax handoff --runner <id> --agent codex

The dashboard exposes the same idea through Run details and Send to next agent.

Prompt blob artifacts

When prompts are too large for the safe submission budget, nax mirrors offloaded payloads locally under .nax/workflows/<run-id>/blobs/ and tracks remote refs in .nax/blob-refs.jsonl.

Clean stale refs with:

nax admin clean blobs
nax admin clean blobs --force

Common mistakes

• Treating .nax as disposable cache before the run has been handed off.
• Looking only at terminal output after a failed synthesis. The saved summaries and prompt blobs often contain the full fan-in context.
• Assuming prompt blob cleanup deletes local debug mirrors. Remote blobs are cleaned up, but local copies stay available for inspection.

See also

• Transports for how runs are submitted.
• Run workflows for the commands that produce workflow artifacts.
• Troubleshooting for recovery commands.