RunVault¶

RunVault is the SDK entry point. It holds the project API key and a small backend HTTP client, and produces Identity objects via register_agent(...).

from runvault import RunVault

rv = RunVault(api_key="rv_live_...")

Construction does no I/O. The first network call happens on register_agent(...).

Constructor¶

RunVault(
    api_key: str,
    be_url: str | None = None,
    timeout: int = 10,
)

Parameter	Required	Notes
`api_key`	yes	Project API key (`rv_live_…`). Used only at registration.
`be_url`	no	Override the backend base URL. Defaults to the `RUNVAULT_BE_URL` environment variable if set, otherwise the production endpoint baked into the SDK. Most users should leave this unset.
`timeout`	no	Seconds. Applies to connect / write / pool phases of backend calls. Read timeout is unbounded.

`register_agent(...)`¶

identity = rv.register_agent(
    agent_id: str,
    name: str,
    budget: float | None = None,
    budget_alert_threshold: float | None = None,
    security_policy: Literal["hard", "soft"] | None = None,
) -> Identity

Registers an agent (or loads it if already registered) and returns a long-lived Identity. Idempotent on agent_id.

On first registration the backend mints an Ed25519 keypair and signs a certificate with the project CA; both are cached to ~/.runvault/<agent_id>/. On re-registration the existing material is loaded from disk.

Dashboard precedence. budget, budget_alert_threshold, and security_policy are honoured only on first registration. The dashboard is authoritative thereafter.

Raises¶

Exception	When
`AgentSuspendedError`	An administrator has suspended this agent.
`RegistrationError`	Backend rejected the request (network, 5xx, validation).
`AuthenticationError`	The project API key was rejected.

Reference¶

`runvault.client.RunVault` ¶

RunVault SDK client.

Holds the API key (used only at registration) and a backend HTTP client. One instance per process is typical, but multiple are supported (e.g. testing against multiple environments).

Parameters:

Name	Type	Description	Default
`api_key`	`str`	Active RunVault project API key (`rv_live_…`).	required
`be_url`	`str \| None`	Override the backend base URL. Defaults to the `RUNVAULT_BE_URL` environment variable if set, otherwise the production endpoint. Most users should leave this unset.	`None`
`timeout`	`int`	HTTP request timeout in seconds for backend calls.	`10`

`register_agent(agent_id, name, budget=None, budget_alert_threshold=None, security_policy=None)` ¶

Register an agent (or load it if already registered) and return a long-lived Identity ready to drive LLM calls.

Idempotent — same agent_id returns the same Identity. On first registration the backend mints an Ed25519 keypair and signs a certificate with the project CA; both are cached to ~/.runvault/<agent_id>/ and held in memory on the returned Identity. On re-registration the existing material is loaded from disk.

Parameters:

Name	Type	Description	Default
`agent_id`	`str`	External agent identifier (e.g. `"research-v1"`).	required
`name`	`str`	Human-readable agent name.	required
`budget`	`float \| None`	Optional hard spending cap in USD.	`None`
`budget_alert_threshold`	`float \| None`	Optional alert percentage (0–100).	`None`
`security_policy`	`Literal['hard', 'soft'] \| None`	Cross-identity guard mode for the LLMs built from this identity. `"hard"` (default) raises `CrossIdentityError` on a mismatch; `"soft"` warns and bills the bound identity. Honoured only on first registration — the backend is authoritative afterwards.	`None`

Returns:

Name	Type	Description
`An`	`Identity`	class:`Identity` ready for `identity.run()` and
	`Identity`	`identity.build_llm()`.

Raises:

Type	Description
`AgentSuspendedError`	Admin has suspended this agent.
`RegistrationError`	Backend registration failed.