> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/getting-started-1/quickstart.md).

# Quickstart

Get from account creation to a policy-gated, approved, auditable action in about five minutes. This path uses Warrant's hosted sandbox and a mock Kubernetes actuator, so it does not touch a real cluster.

### 1. Create an application

Open the [hosted dashboard](https://warrant-api-production.up.railway.app/app), create an account, and keep the Kubernetes SRE starter policy selected.

Signup creates:

* an organization;
* an isolated application (a Warrant tenant);
* a versioned starter policy;
* a mock actuator for safe evaluation; and
* one agent API key, shown only once.

Copy the key from the welcome screen. Warrant stores the key hash, not the recoverable secret.

```sh
export WARRANT_URL='https://warrant-api-production.up.railway.app'
export WARRANT_API_KEY='<agent-key-shown-once>'
```

Confirm the service and key:

```sh
curl -sS "$WARRANT_URL/v1/health"

curl -sS "$WARRANT_URL/v1/integration" \
  -H "Authorization: Bearer $WARRANT_API_KEY"
```

`GET /v1/integration` returns the key scope, tenant, active policy revision, endpoint map, and an example proposal derived from that policy.

### 2. Submit a bounded action

```sh
curl -sS "$WARRANT_URL/v1/actions" \
  -H "Authorization: Bearer $WARRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proposal_id": "quickstart-scale-001",
    "actor": {
      "agent_id": "quickstart-agent",
      "run_id": "run-001"
    },
    "summary": "Scale checkout in staging",
    "action": {
      "target_system": "kubernetes",
      "operation": "scale_deployment",
      "parameters": {
        "deployment": "checkout",
        "namespace": "staging",
        "replicas": 3
      },
      "rollback_plan": "restore the previous replica count"
    },
    "risk": {
      "level": "medium",
      "blast_radius": "checkout staging deployment"
    }
  }'
```

The starter policy requires approval at `medium` risk, so the expected decision is:

```json
{
  "proposal_id": "quickstart-scale-001",
  "decision": "needs_approval",
  "action_status": "pending_approval",
  "review_route": "platform-oncall"
}
```

The real response also includes the authenticated principal, effective risk, policy and catalog commitments, individual checks, blocking reasons, and audit reference. The submitted `actor` and `risk` remain caller claims; Warrant derives authoritative identity from the API key and may raise risk from a reviewed catalog.

### 3. Approve it

In the dashboard, open the application, choose **Approvals**, add an optional note, and approve the held action.

Warrant records the authenticated approver, enqueues the execution job, and invokes the mock actuator. The final status becomes `executed`, and the result includes `"dry_run": true`.

To automate approval instead, create an approver-scoped key in the application's **Keys** tab:

```sh
export WARRANT_APPROVER_KEY='<approver-key-shown-once>'

curl -sS "$WARRANT_URL/v1/actions/quickstart-scale-001/approve" \
  -X POST \
  -H "Authorization: Bearer $WARRANT_APPROVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "approved for the sandbox quickstart"}'
```

Do not put approver keys in the same agent runtime that proposes actions.

### 4. Inspect the trace

```sh
curl -sS "$WARRANT_URL/v1/actions/quickstart-scale-001" \
  -H "Authorization: Bearer $WARRANT_API_KEY"

curl -sS "$WARRANT_URL/v1/actions/quickstart-scale-001/audit-export" \
  -H "Authorization: Bearer $WARRANT_API_KEY"
```

The action trace contains proposal, verdict, approval, execution result, current job state, and sequenced audit events. The audit export adds proof data and an integrity version so a verifier can distinguish legacy and canonical signed records.

### Handle every response correctly

`POST /v1/actions` can complete inline or return durable work:

| HTTP/status                                | Caller behavior                                                           |
| ------------------------------------------ | ------------------------------------------------------------------------- |
| `200` + `executed`                         | Treat the recorded result as terminal.                                    |
| `200` + `pending_approval`                 | Stop and wait for approval.                                               |
| `200` + `denied`                           | Stop and surface `blocking_reasons`.                                      |
| `202` + `execution_pending` or `executing` | Poll the returned `polling_url`; do not perform the side effect yourself. |
| `outcome_unknown`                          | Stop automation and reconcile the downstream system manually.             |

Use a unique `proposal_id` for each logical action. Retrying the same body with the same ID returns the existing action; reusing the ID with different content returns a conflict.

### Put Warrant in an agent loop

The thin Python client wraps the same HTTP contract:

```python
from warrant.client import WarrantClient

warrant = WarrantClient.from_env()
verdict = warrant.submit_action(proposal)

if verdict["decision"] == "needs_approval":
    return {"status": "held", "action_id": verdict["proposal_id"]}
if verdict["decision"] == "deny":
    return {"status": "denied", "reasons": verdict["blocking_reasons"]}
return verdict
```

The agent never calls the provider after an `allow`; Warrant's registered actuator owns the side effect. Continue with Agent and actuator integration.

### Before production

The hosted quickstart proves the control flow, not a real connector. Before allowing production mutations:

1. register a real actuator behind Warrant;
2. persist a reviewed, closed operation catalog;
3. make the downstream system honor Warrant's idempotency key;
4. run Postgres-backed execution workers;
5. configure audit signing; and
6. remove or isolate every bypass credential and unguarded tool path you control.

Use Production readiness and strict rollout for the complete rollout sequence.

### Self-hosted operator path

Running Warrant yourself has a separate setup path covering local startup, operator bootstrap, tenant creation, persistence, and production handoff. Continue with Self-hosted setup.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/getting-started-1/quickstart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.