witnora

Zero to Evidence

Witnora has two supported onboarding paths. Both create the same restricted, project-scoped connection and the same isolated onboarding receipt.

Choose the project boundary

A project is an isolated assurance boundary, not one Agent. Put related Agent versions and environments in the same project when they share ownership, policy, retention, and access controls. Create a separate project when those boundaries differ.

Owners and admins manage projects from the project navigator. Archiving a project immediately revokes its active machine credentials and makes it read-only; restoring it does not reactivate those credentials. An archived project can be permanently erased only after the owner or admin enters its exact name. Erasure removes retained project records and stored artifacts, then downloads a JSON erasure receipt. A requested or approved legal hold blocks erasure until the governed hold review is rejected or released.

Path 1: Local CLI

1. Sign in at witnora.com/app and create a project.
2. Hosted opens the Setup Wizard and prepares a metadata-only plan for private discovery, the customer-owned Gateway, outcome probe, CI, policy, and review.

3. Review the declared privacy and evidence ceiling, then open a terminal in the Agent repository and run the displayed command:

   npx witnora@latest onboard --project your-project-id
   

4. Select Approve setup in the browser. This authorizes the displayed plan and one reversible installation.

The CLI then performs the rest without another prompt:

• saves a restricted credential in the user’s Witnora profile, not the repo;
• detects browser, coding, MCP, workflow, and data capability groups without requiring the customer to choose only one;
• writes only missing Gateway, probe, CI, policy, review, configuration, and boundary starter files;
• starts and health-checks the customer-owned Gateway in the background;
• runs a deterministic local evidence-path self-test;
• verifies generated components and removes only files created by a failed install attempt;
• records an isolated receipt under .witnora/onboarding/receipts/, updates Hosted progress, and redirects a successful setup to Current Assurance.

The self-test is not customer-agent evidence. It cannot create a run, evidence object, release decision, or CURRENT assurance.

The default plan does not invent customer credentials. The Gateway remains at RECORDED until a write credential is placed behind a controlled adapter. The outcome probe remains awaiting_customer_secret until a separate read-only credential is supplied. These states are visible in Setup rather than being presented as completed assurance.

Capabilities discovered later enter the pending-confirmation queue under a default-deny policy. The existing Gateway remains installed; reintegration is not required.

Path 2: GitHub App

Choose GitHub App on the same onboarding screen. An owner or admin selects the repository and explicitly authorizes each write. Witnora can open a reviewable setup PR, store a project-scoped CI secret through GitHub’s encrypted secret API, and dispatch an already-reviewed assurance workflow. It never asks for a personal GitHub token and does not merge its own PR.

No agent repository yet

From any empty directory:

npx witnora@latest try --template workflow

Inspect .witnora/try/agentcert-report.html. This offline sample proves local installation, schema validation, reporting, and artifact provenance. It does not connect Hosted or establish CURRENT assurance.

Produce real evidence

After onboarding, instrument or test one real bounded workflow. The generated configuration is a starter, not a claim that the whole agent is covered.

npx witnora@latest run --tripwire .tripwire/latest/tripwire-result.json --push
# or
npx witnora@latest push --evidence ./path/to/agentcert-evidence.json --artifact-root .

Browser agents normally start with Tripwire. MCP servers use MCPBench. Coding, workflow, and data templates generate a dependency-free Universal Event/Action Envelope adapter. A boundary event alone is reported-strength evidence until a deterministic assertion and independent outcome verifier are attached.

Advanced manual templates

Use these only when automatic detection is not appropriate:

npx witnora@latest init --template browser --subject my-browser-agent --github-action
npx witnora@latest init --template coding --subject my-coding-agent
npx witnora@latest init --template mcp --subject my-mcp-agent
npx witnora@latest init --template workflow --subject my-workflow-agent
npx witnora@latest init --template data --subject my-data-agent

SellerShield dogfood workflow

Use a private branch and one sandbox chargeback lifecycle. Run onboard in the normal SellerShield repository; no SellerShield-specific Witnora code is required. Then cover one deterministic mock workflow: create a mock dispute, generate documents, require approval, submit through the mock adapter, observe the final state through a separate read path, and verify recovered amount and fees. Do not use live Shopify credentials or submit a real dispute.

This site is open source. Improve this page.