Quickstart

Goal: one task on a local repo, with a verifiable audit trail. ~5 min

What you’ll get

• Daemon healthy (carina doctor)
• A safe-edit session from carina run
• Audit replay + hash-chain verify
• How to list / roll back patches if the agent edited files

Fastest path

1. Install & doctor

   If you have not installed yet: Install.

   carina doctor

   Need a daemon explicitly?

   carina daemon start
   carina status

   Interactive carina also auto-starts the daemon.

2. Run a task in a repo

   run.sh

   cd /path/to/your/repo
   carina run "Summarize the top-level architecture of this repo"

   What this does (current CLI):

   • creates a safe-edit session in cwd
   • submits the prompt as a task
   • waits for completion (or use --background to return when queued)

   Interactive shell:

   carina

   Tool calls that mutate state hit the capability kernelFourteen capability types evaluated before side effects.. Higher risk may prompt for approval — that is expected.

3. Inspect the audit trail

   Use the session id printed by the CLI/TUI:

   audit.sh

   carina sessions
   carina audit SESSION
   carina audit verify SESSION
   carina report SESSION

   • audit — raw event stream (decisions + effects)
   • audit verify — tamper-evident hash chainEach event links to the previous hash; verify detects rewrite.
   • report — violations, files, commands summary

4. Patches (if files changed)

   patch.sh

   carina patch list SESSION
   carina patch show SESSION PATCH_ID
   carina patch rollback SESSION PATCH_ID

   Under safe-edit, writes prefer PatchApply (transactional) over raw FileWrite.

Expected outcomes

Check	Good sign
carina doctor	No hard failures
carina run "…"	Task completes or waits on approval
carina audit verify SESSION	Chain OK
carina patch list SESSION	Empty if no file txns; else list with ids

If it fails

Problem	Fix
daemon unreachable	carina daemon start · check ~/.carina/daemon.sock
Task stuck on approval	carina approve SESSION DECISION_ID or deny · see Policy
Model / auth errors	carina auth list · carina auth login <provider>
Doctor noise	carina doctor --json for machine-readable detail

Optional: headless / SDK stream▾

carina run --input-format stream-json --output-format stream-json

Bidirectional NDJSON protocol for CI and SDKs. See API overview.

How this ties to Carina

This path exercises the three differentiators:

1. Policy — safe-edit on carina run
2. Audit — audit + verify
3. Rollback — patch rollback

Source of truth

• CLI surface: carina --help (also CLI reference)
• Security defaults: docs/security-model.md · Policy
• Audit model: docs/ event/audit notes · Audit

Next

📋Common workflows

Fix tests, review, embed RPC — short recipes.

→🛡Policy

Why approvals fire and what profiles mean.

→⌘CLI & TUI

Day-to-day commands beyond the golden path.

→