Skip to main content

Start with the question you have

Persisting has two independent entry points. Start with the one that matches the work in front of you, then follow the short path to a useful result.

I want to run an Agent safely and review its changes​

Start with pVisor. It lets one Agent work in an isolated Run, records the execution boundary, and leaves filesystem changes staged until you decide to write them into the real project or discard them.

  1. Install the command line tools.
  2. Run your first Agent.
  3. Review and selectively apply changes.
  4. Choose a host, OCI, or VM environment.

When it finishes, the Agent has stopped and its changes remain staged for you to review, apply, or discard.

pvisor run --stage ./runs/task-001 -- codex
pvisor review last
pvisor apply last --path src

I already have Agent trajectories​

Start with pChronicle. It can inspect local or object-store data and can also import supported external formats. The first walkthrough creates temporary example data, so you can learn the query flow before preparing a Dataset.

  1. Explore a first Dataset.
  2. Discover and query your own data.
  3. Import or export a supported format.
  4. Serve a Dataset locally.

You should finish with a read-only query, a normalized view, and a clear sense of which data and which source you inspected.

pchronicle onboard query
pchronicle query ./trajectory-data \
  --sql 'SELECT source, COUNT(*) FROM dataset.steps GROUP BY source'

I want execution and history together​

Connect the two products only after each standalone workflow works. Configure pVisor capture to publish selected Gateway trajectory events and lifecycle records into pChronicle. The handoff is explicit and narrow: it does not move the private Run Bundle or invent evidence that the original Source did not provide.

pVisor capture and pchronicle serve --gateway are separate entry points: pVisor capture shares an Agent Run lifecycle and boundary; pchronicle serve --gateway receives or forwards traffic from an existing Agent or SDK without starting a pVisor Run.

  1. Capture Agent trajectories.
  2. Understand the event and sidecar contract (for protocol changes or troubleshooting).
  3. Read the execution-to-history architecture.
pVisor Run ── configured capture ──> canonical event Source ──> Dataset views
external trajectory Source ──────────────────────────────────> Dataset views

I need to understand the boundary before I run anything​

Read the concepts in this order:

  1. Run, Attempt, and Effect — the stable objects.
  2. Capabilities and evidence — what a Run can claim.
  3. Execution environments — how provider choice changes the boundary.
  4. Security and evidence — what persists and what stays local.

The documentation uses one rule throughout: a successful command does not imply that every requested capability was enforced. The Run Bundle records the mechanisms and limitations that actually applied.

Keep going​