Skip to content

Run your first Agent

This walkthrough completes one useful cycle: install Persisting, run an Agent inside a staged environment, inspect its effects, and selectively accept them. It assumes macOS or Linux.

1. Install the CLI

The wheel installs pvisor, ppilot, and pchronicle together:

pip install persisting

To use the current nightly build instead:

curl -fsSL https://raw.githubusercontent.com/DeepLink-org/Persisting/main/scripts/install-nightly.sh | bash

On macOS, install macFUSE once before using a staged host workspace:

brew install --cask macfuse

Confirm the entry points:

pvisor --help
ppilot --help
pchronicle --help

See Installation for source builds, VM support, platform requirements, and component overrides.

2. Run one Agent

From a project directory:

pvisor run --safe codex

Replace codex with another Agent command if needed. --safe creates a Run-owned stage for workspace writes and installs the supported platform controls. It does not silently describe every platform as providing the same isolation; the Run Bundle records filesystem, network, and other capability evidence separately.

During the Run, the Agent edits its staged view. The base project is unchanged.

3. Review the effects

pvisor review last
pvisor inspect last -- git status --short

Review the file changes, network counters, effective controls, and warnings before accepting anything.

4. Accept a subset

Apply one area first:

pvisor apply last --path src

The rest remains staged. Review again and select another batch:

pvisor review last
pvisor apply last --include 'tests/**' --exclude 'tests/generated/**'

Finish by accepting everything that remains, or discard it:

pvisor apply last --all
# or
pvisor drop last

This separation is the core local workflow: the Agent can operate without an approval prompt for every edit, while the user controls which effects enter the real project.

5. Choose where to continue