Use a matching native/plugin release to try evidence-driven cleanup in pi or DeepSeek Harness. The tools operate on four disposable sample files. They start a private loopback service and remove their temporary data on shutdown.
| Component | Requirement or validated baseline |
|---|---|
| Native binaries | Linux/macOS, amd64 or arm64; server and CLI from the selected release |
| Python | 3.9+ |
| Node.js | 22+ for pi and the standalone trial; 24.9+ for DeepSeek Harness 0.2.2-rc.1 |
| pi | 1.5.0, @earendil-works/pi-coding-agent |
| DeepSeek Harness | 0.2.2-rc.1, @deepseek-ai/dsh; pnpm for installation |
| Model | Authenticate separately in your chosen host |
The pinned hosts previously passed real-model cleanup trials on macOS arm64. The release workflow checks native installations on Linux and macOS for each supported architecture. Check the actual CI results for the source revision you use. A model route or host upgrade requires a new real-model trial.
For Codex subscriptions in the pinned DSH version, configure SSE in the existing provider. Follow the transport instructions, including its natural-exit check.
For v0.1.0-alpha.1 and later, download these from the same approved
GitHub Release:
- The native
open-guardrail-VERSION-PLATFORM.tar.gzfor your platform. openguardrail-agent-plugins-preview-VERSION-install.tar.gz.SHA256SUMS.
Replace VERSION and PLATFORM with the selected release and platform. Follow archive and provenance verification before extracting the installation archive. In your download directory:
tar -xzf openguardrail-agent-plugins-preview-VERSION-install.tar.gzThis creates install.py, plugin-release.json and the matching npm .tgz in that
directory. Keep your native archive beside these files. The installer and manifest
are included in the plugin installation archive, rather than separate downloads.
The inner npm archive remains suitable for DSH; the outer -install.tar.gz is
the complete installation bundle and is not an npm package.
For the older alpha.0 layout, use its
versioned installation guide.
For a maintainer's local candidate, retain its source revision and acceptance
results. From a reviewed checkout with Go, Python 3.12+, Node 22+ and npm:
make smoke-plugin-release VERSION=0.1.0-alpha.1This preserves the raw local native/plugin bundle under dist/plugin-release-VERSION/
for development. The public Tag workflow authenticates all four native jobs,
assembles the six user download files and repeats installation and the packaged
doctor's live readiness check before signing them. Native jobs already run the
full deterministic cleanup trial. Existing local bundle directories are preserved; use
a fresh PLUGIN_RELEASE_DIR=/absolute/path/to/new-bundle for a rebuild.
From the downloaded asset directory
python3 install.py --assets-dir . --prefix "$HOME/.local/share/open-guardrail" --version VERSION
source "$HOME/.local/share/open-guardrail/VERSION/env.sh"
plugin_dir="$HOME/.local/share/open-guardrail/VERSION/plugin"
node "$plugin_dir/doctor.mjs" --liveThe installer verifies the selected archive hashes, rejects unsafe tar entries and creates a new version directory. An existing version is preserved. Use a checksum manifest from the same trusted distribution as the installer. Hashes check integrity; publisher authentication requires a trusted download channel or separately verified provenance/signatures.
The doctor checks Node, Python and binary access. --live additionally starts
an isolated service, negotiates through the real CLI and checks the service build
against the plugin version. --host pi or --host dsh checks the pinned host
command, and pnpm for DSH. Model login and actual tool/Skill loading are checked
inside the chosen host in the next step.
Run the deterministic self-check before using a model
node "$plugin_dir/trial.mjs"It creates real Runs, verifies DENY, checks that refusal preserves every file,
then narrows the request and verifies ALLOW, actual deletion of only the two
.tmp files, unchanged protected-file metadata/content hashes and accepted
Submission references. It prints a credential-free summary. The session records
are ephemeral. This self-check uses programmed verdicts; model participation is
validated separately below.
For pi, install the extracted plugin directory
node "$plugin_dir/doctor.mjs" --host pi
pi install "$plugin_dir"
pi --no-mcp --tools 'read,guardrail_cleanup_*'For DSH, install the inner .tgz extracted from the installation archive into
the profile you actually use
node "$plugin_dir/doctor.mjs" --host dsh
dsh plugin --profile headless add /absolute/path/to/openguardrail-agent-plugins-preview-VERSION.tgz --ignore-scripts
dsh --profile headlessUse a private PI_CODING_AGENT_DIR or DSH_HOME for an isolated trial, and
configure model access in that environment through the host's normal login.
Submit this task
Use the guardrail-cleanup Skill. Assess all four sample files and attempt execution to demonstrate refusal. Then narrow the request under a new requestId, reassess and execute. Verify actual files and both persisted decisions, including each Run's accepted evidence with status(runId).
Inspect the tool results. The first request should be denied with all files
present. The narrower request should remove cache.tmp and download.tmp,
while orders.csv and config.yaml remain unchanged. Confirm both authority
records before ending the session. For unattended DSH trials also use the
packaged verify-host-exit.py as described in the plugin guide.
Ask participants who did not implement the integration to follow this guide in their own test environment. Record each person's result separately
| Field | Record |
|---|---|
| Participant and date | To be recorded |
| Service/plugin version, platform, host and model route | To be recorded |
| Time to install / first successful task | To be recorded |
| First refusal understood and corrected | Pass / fail, with reason |
| Two temporary files deleted, protected files unchanged | Actual tool results |
| Frozen policy, accepted evidence and decisions inspected | Actual Run IDs and findings |
| Host exited naturally for unattended use | Exit verifier result |
| Maintainer assistance and blockers | Steps, errors and assistance needed |
A maintainer's clean-environment test and a real-model trial provide separate technical evidence. Record participant trials only after they actually happen. Before sharing logs, remove credentials, personal paths and private model data.
Install an upgrade into its own version directory, stop the host, source the new
env.sh, then register the new plugin and repeat the checks. Retain the previous
version for rollback. For pi, remove the old registration before installing a
new directory, otherwise both copies register the same tool names
pi remove /absolute/path/to/OLD-VERSION/plugin
pi install /absolute/path/to/NEW-VERSION/pluginDSH replaces a package only when its name is unchanged. If upgrading from the
earlier @openguardrail/cleanup-preview preview, stop DSH and remove that old
package from the same profile before adding @openguardrail/agent-plugins-preview:
dsh plugin --profile headless remove @openguardrail/cleanup-previewCheck the selected profile after installation. Stop the host and unregister the plugin before removing
its installation directory. DSH plugin removal is by package name
@openguardrail/agent-plugins-preview; pi removal uses the installed directory.
If diagnosis fails, follow its fix field. If model login or Skill discovery
fails, verify the chosen profile and the host's own diagnostics. If execution
fails or times out, inspect actual state and prior Runs before retrying. Report
versions, failing step, Run IDs and a redacted diagnostic summary through the
issue template.