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

# Installation

**What you'll learn:** How to install the Kyvvu SDK, log in, get an API key, and verify your setup.

***

## Install the SDK

```bash
pip install kyvvu
```

This installs the `kyvvu` Python package, which includes:

* The **SDK** (`kyvvu`) — decorator and callback integrations for your agent code
* The **engine** (`kyvvu-engine`) — in-process policy evaluation library
* The **CLI** (`kyvvu` command) — account management, project scaffolding, an offline policy trial (`kyvvu try`), a local policy server, and diagnostics (`kyvvu doctor`)

## Try it before logging in

You do not need an account to see the engine work:

```bash
kyvvu try
```

That evaluates a three-step demo agent against the [frozen baseline policy set](/policy-authoring/bundled-baseline.md) bundled inside the package, and blocks its ungated code execution — with no account, no API key and nothing on the network. `kyvvu try --manifest my-manifest.yaml` does the same for a manifest of your own, and `kyvvu serve --baseline` serves the same policies over HTTP. See [kyvvu try](/cli-reference/try.md).

Everything below — traces in the dashboard, incidents, assigned manifests, the audit trail — is what an account adds on top.

## Log in

```bash
kyvvu auth
```

This starts a device-code flow. There is no password to enter here or anywhere else — magic link is Kyvvu's only way in. It opens your browser automatically, with a one-time code already filled in:

```
Opening your browser to approve this login...
If it doesn't open, visit this URL manually: https://platform.kyvvu.com/cli-auth.html?user_code=7K2M9XQP
(Code: 7K2M9XQP)

Waiting for you to approve...

✓ Logged in as you@company.com
```

In the browser (signing up first if you don't have an account yet), confirm the code matches your terminal and click **Approve**. The CLI polls in the background and finishes automatically once you approve. If the browser doesn't open on its own — for example over SSH — copy the printed URL (or just the code) and open it manually on any device.

{% hint style="info" %}
**You get your own workspace, immediately.** Signing up creates your account's personal workspace. Your email domain decides nothing: nobody is placed in somebody else's organisation by having an address at the same domain, and you join an organisation by **invitation** only.

The one thing that can hold a new account back is Kyvvu's platform-wide registration limit. If it has been reached, `kyvvu whoami` shows `Status: ✗ waiting to be admitted by Kyvvu` — you can sign in, but not create agents or API keys. **Only Kyvvu lifts that**, not an administrator at your organisation. A different status, `✗ suspended in this workspace`, means an administrator there has stopped you, and they can undo it.
{% endhint %}

## Get an API key

`kyvvu auth` logs the CLI in, but it does not create an API key — that's dashboard-only, by design (a CLI login can never mint an agent-scoped credential). To get `KV_API_KEY`:

1. Open the dashboard.
2. Go to **Workspace → API Keys**.
3. Create a key and save it — it's shown only once.

Save the API key — it authenticates your agents with the Kyvvu platform.

## Verify

```bash
kyvvu whoami
```

```
Email:         you@company.com
API URL:       https://platform.kyvvu.com
Status:        ✓ active
Log location:  stdout (auto — for THIS shell; an agent that supplies agent_key itself, as the kyvvu init scaffold does, resolves it to https://platform.kyvvu.com)
Incidents:     (inherits log location: stdout)
Policy source: ✗ none — an agent here would enforce nothing (missing KV_AGENT_KEY / agent_key)
```

**Read `Policy source` first.** It answers the only question that matters before you ship anything: whether an agent started in this shell would enforce anything at all. [`kyvvu doctor`](/cli-reference/doctor.md) asks the same question in more detail, and is the right thing to run when a trace arrives without the enforcement you expected.

## Environment variables

Set `KV_API_KEY` in your shell profile or `.env` file:

```bash
export KV_API_KEY=KvKey-...
```

For self-hosted deployments, also set the API URL:

```bash
export KV_API_URL=https://your-kyvvu-instance.com
```

## No account yet? You can still see a block

Installing the SDK is enough to get an enforced decision. The `kyvvu` package bundles a frozen 15-policy baseline set that loads with no API key, no account and no network:

```python
from kyvvu.baseline import load_baseline_policies
from kyvvu_engine import PolicyEngine
from kyvvu_engine.schemas import Behavior, EvalContext, StepType

engine = PolicyEngine()
engine.load_policies(load_baseline_policies())

# agent_allowed_tools is required in practice, not optional: the allowlist
# policy fails CLOSED, so an absent or empty allowlist blocks every
# step.resource / step.exec / step.credential regardless of what it is.
context = EvalContext(
    agent_id="hello-kyvvu",
    task_id="task-1",
    risk_classification="minimal",
    agent_allowed_tools=["run_script"],
)

result = engine.evaluate(
    Behavior(
        agent_id="hello-kyvvu",
        task_id="task-1",
        step_type=StepType.step_exec,
        step_name="run_script",
        input={"code": "print('hi')"},
    ),
    context,
)

print(result.action.value, f"{result.risk_score:.2f}")
assert result.action.value == "block"
assert [p.name for p in result.policies if p.violated] == [
    "Code execution requires a preceding gate"
]
```

Code execution with no approval gate in front of it: `block` 1.00, OWASP ASI05. See [The Bundled Baseline](/policy-authoring/bundled-baseline.md) for the full three-step narrative, for what actually clears that block (a `step.gate` recording `guard.result: "pass"` — a bare gate does not), and for the licence boundary — the manifests are Apache 2.0, but the engine that evaluates them is not.

## Licensing note

The SDK itself is licensed under Apache 2.0. It depends on `kyvvu-engine`, which is licensed under the Business Source License 1.1 (BSL 1.1). Production use of the engine requires a Kyvvu commercial subscription. This applies to the bundled baseline too: Apache-2.0 policy content does not make the trial Apache-licensed end to end, because the BSL engine still evaluates it. See the [Licensing](/reference/licensing.md) page for details.

***

## Next steps

* [The Bundled Baseline](/policy-authoring/bundled-baseline.md) — get an enforced block with no account
* [Your First Agent](/getting-started/first-agent.md) — create and run a demo agent with `kyvvu init`
* [`kyvvu doctor`](/cli-reference/doctor.md) — when a trace arrives without the enforcement you expected
* [Architecture](/core-concepts/architecture.md) — understand how the SDK, engine, and platform fit together

### Where things are in the dashboard

The rename of the old Settings item leaves one question worth answering up front:

| what you want                                      | where it is                                                          |
| -------------------------------------------------- | -------------------------------------------------------------------- |
| API keys, members, usage, platform events, reports | **Workspace**, in the sidebar                                        |
| your own display name and email                    | **Account settings**, in the account menu at the foot of the sidebar |
| light / dark / auto theme                          | **Appearance**, in that same account menu                            |
| connecting a manifest repository                   | **Manifests → Add Repository**                                       |