Local Validation Runbook

This runbook documents the shared validation flows for this repository. Machine-specific paths, preferred runtimes, tokens, and host-only notes should live in an untracked .codex-local/ directory instead of tracked docs.

Where To Put Local Notes

Keep host-specific details in files under:

.codex-local/

Examples:

• local Docker or VM binary paths
• preferred demo roots or external-volume locations
• required environment variables for local services
• machine-specific SSH targets used for validation

Packaged Validation

Run the packaged validation flow with:

./scripts/pilot_test.sh

This validates the installed CLI and daemon, runs openscope doctor, and checks the supported local app surfaces.

OpenClaw Messaging Validation

If you want to validate the OpenClaw Cylonix plugin path, provide a real authentication token and run:

export CYLONIX_AUTH_TOKEN="<token>"
bash scripts/openclaw_cylonix_plugin_test.sh

If this fails with Authentication failed, the plugin flow is wired up but the token was not accepted by the local Cylonix service.

NemoClaw Container Validation

Use the helper that starts a temporary host HTTP bridge and runs the NemoClaw pilot in a container:

scripts/run_nemoclaw_http_bridge_test.sh

Optional pilot arguments are forwarded through:

scripts/run_nemoclaw_http_bridge_test.sh --folder Notes --note Example

Useful environment overrides:

• ASCOPE_LOCAL_ROOT
• NEMOCLAW_DEMO_ROOT
• DOCKER_BIN
• OPENSCOPE_HTTP_PORT
• PPTXGENJS_PATH

SSH Validation

For scoped SSH validation, you need:

• a configured SSH target alias in root-owned admin config
• a scoped policy rule for the action and target
• the specific service or approved path you want to validate

Typical setup:

sudo openscope ssh targets add \
  --alias target-name \
  --host example.internal \
  --user root \
  --services myservice

sudo openscope policy allow \
  --agent openclaw \
  --app ssh \
  --action service_status \
  --target target-name \
  --service myservice

Then validate with:

openscope ssh service_status --agent openclaw --target target-name --service myservice