Installation¶

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

Install the command and the Python client¶

uv tool install kyvvu-cli

or pip install kyvvu-cli. For the Python client in a project of your own:

pip install kyvvu

or uv add kyvvu in a uv project.

Python 3.11 or newer is required.

Together they include: - The Python client (kyvvu) — decorator and callback integrations for your agent code - The engine (kyvvu-engine) — in-process policy evaluation library - The baseline (kyvvu-baseline) — frozen policy manifests and offline loader - The CLI (kyvvu-cli distribution, kyvvu command) — account management, project scaffolding, an offline policy trial (kyvvu try), a local policy server, and diagnostics (kyvvu doctor)

The CLI includes the dependencies for kyvvu serve. Framework integrations are separate packages: kyvvu-langchain (LangChain and LangGraph), kyvvu-crewai (CrewAI, Python below 3.14) and kyvvu-claude (Claude Code). See Integrations.

Try it before logging in¶

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

kyvvu try

That evaluates a four-step demo agent against the frozen baseline policy set bundled inside the package, warns on its unmarked delivery of model output, 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.

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

Log in¶

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@example.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.

Note

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.

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¶

kyvvu whoami

Email:         you@example.com
API URL:       https://platform.kyvvu.com
Status:        ✓ active
Log location:  stdout (auto — for THIS shell; the kyvvu init scaffold passes agent_key in code and, with KV_API_KEY set, resolves it to https://platform.kyvvu.com)
Incidents:     (inherits log location)
Policy source: ✗ none — an agent here would enforce nothing (missing api_key= / KV_API_KEY, agent_key= / KV_AGENT_KEY)

This is a session logged in to https://platform.kyvvu.com. Logged in to another environment, the Log location line names that environment's URL instead, because kyvvu init writes it into the scaffold's .env.example (see kyvvu whoami).

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 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:

export KV_API_KEY=KvKey-...

Set KV_ENVIRONMENT=development for local work. The environment defaults to production (the argument to Kyvvu(...) wins, then KV_ENVIRONMENT, then production), so an agent you run on your laptop registers as a production agent unless you say otherwise.

export KV_ENVIRONMENT=development

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

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

No account yet? You can still see a block¶

Installing the Python client is enough to get an enforced decision. Its kyvvu-baseline dependency bundles a frozen 15-policy set that loads with no API key, no account and no network:

from kyvvu_baseline import load_baseline_policies
from kyvvu_engine import PolicyEngine
from kyvvu_engine import Behavior, EvalContext, ActionKind

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",
        kind=ActionKind.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 for the full four-step narrative, for what actually clears that block (a completed step.gate recording output.decision: "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 Python client 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 page for details.

Next steps¶

• The Bundled Baseline — get an enforced block with no account
• Your First Agent — create and run a demo agent with kyvvu init
• kyvvu doctor — when a trace arrives without the enforcement you expected
• Architecture — understand how the Python client, 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: