Get started | Witnora Docs

Start with one Agent repository and a sandbox workflow. The CLI creates a restricted, project-scoped connection; the first recorded run and independently checked Action result remain separate milestones.

If you do not have an Agent repository, use the offline sample. The GitHub App path is available when that integration is configured for your workspace.

Path 1: Local CLI

You need Node.js 20 or newer, npm, a terminal in your Agent repository, and a Witnora account. Check node --version before starting. These instructions accompany CLI 0.20.13; @latest installs the currently published release.

Sign in at witnora.com/app and create a project.
Hosted opens the Setup Wizard and prepares a metadata-only plan for private discovery, the customer-owned Gateway, outcome probe, CI, policy, and review.
Review the declared privacy and evidence ceiling, choose HTTP Action or MCP Action, then copy and run the displayed command in the Agent repository:
```
npx witnora@latest onboard --project your-project-id --action-transport http
```
Use mcp instead of http for an MCP client. The command stays open while Hosted waits for the first Agent activity and Business Task confirmation. If Witnora detects a safe repository workflow command, Hosted displays it with a copy button; run it in a second terminal. The original command then creates and verifies the sandbox Action automatically. Rerun onboard only as recovery if that original process was closed. If the Agent has no work yet, enter the workspace and resume Action verification after its first real run. Verification does not propose or execute an Action.
Select Approve setup in the browser. This authorizes the displayed plan and one reversible installation.

Check your first result

After setup verification, choose Open workspace. In Agents, check the current Gateway connection and the confirmed task. In Activity & Evidence, open the recorded run to inspect what arrived.

A successful setup means the connection and selected transport passed their setup checks. It does not mean the Gateway is still online or that an external business result occurred. Verified results requires a separately observed outcome and its signed Receipt.

If no run is visible, run the Agent's sandbox workflow first. If the task is not confirmed, finish the Business Task step in setup. If the Gateway is offline, use the Agent's connection guidance; historical setup success does not replace a fresh heartbeat.

What the CLI installs

The CLI then performs the following under the approved setup plan:

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 offers Open workspace after setup verification.

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

Setup distinguishes two connections:

Generated local sandbox: the CLI can create local test credentials and start a sandbox target, controlled Gateway, and separate read-only Probe. LOCAL_SANDBOX_READY means this local test loop is ready. Confirm the exact Business Task and expected result before submitting a test Action. A passed connection check alone does not execute it or verify a business outcome.
Your actual provider: binding a real customer system still requires an appropriate controlled adapter, customer-specific schema and authority, and a separate read-only result credential. An unbound path stays recorded-only; a Probe missing its required credential reports awaiting_customer_secret.

The generated HTTP/MCP Action writes only the Witnora local sandbox. It is not a ready-made Shopify cancellation or Stripe refund connector. Read-only Provider verification does not itself authorize or perform a provider write.

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

Choose the runtime ingress

After onboarding, use the smallest transport already supported by the Agent:

HTTP Actions for any platform that can send an authenticated POST request;
MCP Action integration for an MCP client that should see the same exact sandbox Action as a tool.

Both enter the same customer-owned Gateway and the same approval, idempotent execution, independent Probe, and Receipt path. CLI is the setup mechanism; HTTP and MCP are runtime ingress choices.

Path 2: GitHub App

When the GitHub App is configured for your workspace, its repository automation panel is available to an owner or admin. Select the repository and explicitly authorize 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.

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.

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.