Installation

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

---

Install the SDK

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, local server

Log in

kyvvu auth

This starts a device-code flow — no password is ever entered into the CLI. 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 [e-mail]

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.

Verification: Organization founders get full access instantly. Team members joining an existing org (grouped by email domain) need an admin to verify them before they can create agents or API keys — kyvvu auth still logs you in, but kyvvu whoami will show "pending verification" until an admin approves you.

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 Settings → 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

kyvvu whoami

Email:         [e-mail]
API URL:       https://platform.kyvvu.com
Verification:  ✓ verified
Log location:  stdout
Incidents:     (inherits log location: stdout)

Environment variables

Set KV_API_KEY in your shell profile or .env file:

export KV_API_KEY=KvKey-...

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

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

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. See the Licensing page for details.

---

Next steps

• Your First Agent — create and run a demo agent with kyvvu init

• Architecture — understand how the SDK, engine, and platform fit together