Skip to content New Self-host your password sync in 15 minutes Read more Menu Download OpenVireo

The openvireo package is the Python binding of the core: accounts, vaults, sync, share links and .kdbx files, on the same Rust code as the iOS, desktop and web apps. UniFFI generates the openvireo._core module from bindings/ov-ffi, and openvireo.hosts adds ready-made platform parts, so a script needs no glue.

  • Python 3.10 or later, on macOS (arm64, x86_64), Linux (manylinux 2.28 x86_64 and aarch64, musllinux x86_64) and Windows x64.
  • One wheel per platform (py3-none-<platform>) covers every Python version, because the library is loaded through ctypes rather than the CPython ABI.
  • Every call that touches the network or storage is an asyncio coroutine.

The package source and its developer notes are in bindings/python.

Install

The package isn’t on PyPI yet. Wheels are attached to each core release on GitHub, and pip reads them from the release’s asset list:

pip install "openvireo==X.Y.Z" \
  --find-links https://github.com/openvireo/openvireo-core/releases/expanded_assets/vX.Y.Z

Use the expanded_assets URL. It’s the HTML fragment that lists the release’s files, which pip can read. The releases/tag/vX.Y.Z page loads its asset list with JavaScript, so pip finds nothing there. Pin the version (==X.Y.Z): pip also searches PyPI, and the pin stops it picking up something else named openvireo.

Two optional extras. Their dependencies come from PyPI, so pass --find-links as well:

# async HTTP on httpx (otherwise urllib runs in a worker thread)
pip install "openvireo[httpx]==X.Y.Z" --find-links https://github.com/openvireo/openvireo-core/releases/expanded_assets/vX.Y.Z
# keep sessions and trusted Secret Keys in the OS keychain
pip install "openvireo[keyring]==X.Y.Z" --find-links https://github.com/openvireo/openvireo-core/releases/expanded_assets/vX.Y.Z

Each wheel has a GPG signature (.asc) next to it on the release page.

Check the install:

import openvireo as ov
print(ov.__version__, ov.sha256(b"abc").hex()[:8])   # X.Y.Z ba7816bf

A client

An OvClient needs a ClientConfig (this device) and a Host (the platform parts the core calls: HTTP, secure store, offline cache, clock, log sink). default_host() builds the Host for you:

import openvireo as ov
from openvireo.hosts import default_host

client = ov.OvClient(
    ov.ClientConfig(
        device=ov.DeviceInfo(id=None, name="backup script", platform=ov.Platform.CLI),
        offline=False,
        server=None,
    ),
    default_host(),
)
  • device.name is what the account’s device list shows. Scripts use Platform.CLI.
  • offline=True keeps the offline cache: unlock, list and open vaults without the network, and keep edits until they upload. It needs a persistent cache: pass cache_dir= to default_host.
  • server is a discovery document to use instead of fetching one. Leave it None.

default_host() with no arguments keeps everything in memory, so each run is a new device: it signs in from scratch and needs the Secret Key every time. To keep the session and the trusted Secret Key between runs, give it a persistent store:

from openvireo.hosts import KeyringStore, default_host

host = default_host(store=KeyringStore(), cache_dir="~/.cache/openvireo")

Sign in

import asyncio
import getpass

import openvireo as ov
from openvireo.hosts import KeyringStore, default_host


async def sign_in(client: ov.OvClient, email: str) -> ov.Account:
    account = await client.connect("https://accounts.openvireo.com")
    password = getpass.getpass("Master password: ").encode()

    if account.is_signed_in():
        # A stored session (persistent store): unlock it, no OPAQUE round trip.
        await account.unlock(password, None)
        return account

    login = ov.LoginInput(email=email, password=password, secret_key=None, totp=None, trust_device=True)
    try:
        step = await account.login(login)
    except ov.OvError as e:
        if e.code != ov.OvErrorCode.INVALID_SECRET_KEY:
            raise
        # A new device: the Secret Key isn't stored here yet.
        login.secret_key = getpass.getpass("Secret Key: ").encode()
        step = await account.login(login)

    while isinstance(step, ov.LoginStep.NEEDS_TOTP):
        try:
            step = await account.submit_totp(step.challenge, input("Two-step code: "))
        except ov.OvError as e:
            if e.code != ov.OvErrorCode.INVALID_MFA:
                raise   # mfa_expired: start the sign-in again
            print("Wrong code, try again")
    return account
  • connect fetches the server’s discovery document and loads a stored session if there is one. The account is then signed in but locked, and unlock opens it with the master password.
  • A device that has never seen the account doesn’t have the Secret Key. login without one fails with invalid_secret_key. Ask for the key and try again. With trust_device=True the core stores the key, so the next sign-in on this device doesn’t need it.
  • A wrong password, or an email with no account, is unauthorized (401). A wrong Secret Key is also unauthorized; details tells them apart (see Errors).
  • An account with two-step sign-in returns LoginStep.NEEDS_TOTP. Send the code with submit_totp. A wrong code is invalid_mfa and the same challenge can be used again (challenge.attempt() counts the tries). After the fifth wrong code, or once the challenge expires, the result is mfa_expired and the sign-in starts again. If you already have the code, pass totp="123456" in LoginInput to skip that step.
  • LoginStep.UNLOCKED carries unlocked (offline, deletion_scheduled_for).

await account.sign_out(False) ends the session and deletes this device’s offline cache, including edits that haven’t synced. sign_out(True) also forgets the stored Secret Key and device id.

Vaults and entries

for info in await account.vaults():
    vault = await account.open_vault(info.id)
    for entry in vault.entries(False):          # False: leave out the Recycle Bin
        print(info.name, "/", "/".join(entry.group_path), entry.title, entry.username)

vaults() returns VaultInfo records (id, name, role, org_id, …). open_vault downloads and decrypts one. After that, reading and editing a Vault is local and synchronous:

  • entries(include_recycle_bin) gives EntrySummary records (id, title, username, url, group_path, tags, …). They have no field values.
  • entry(id) gives the full EntryRecord. Its fields are FieldRecord(name, value, protected), and every value is bytes (UTF-8 for text).
  • find("ov://Personal/Servers/Router") looks an entry up by reference: ov://<vault>/[<group>/...]<entry>, where <entry> is a UUID or a unique title. read_field("ov://Personal/Servers/Router/Password") reads one field.
rec = vault.entry(entry.id)
password = next(f.value for f in rec.fields if f.name == "Password").decode()

Add an entry and sync

entry_id = vault.add_entry(
    vault.root_group_id(),                      # or vault.ensure_group("Servers/Prod")
    ov.EntryInput(
        fields=[
            ov.FieldInput(name="Title", value=b"Router", protected=None),
            ov.FieldInput(name="UserName", value=b"admin", protected=None),
            ov.FieldInput(name="Password", value=b"correct horse", protected=None),
        ],
        remove_fields=[],
        tags=None,
        icon_id=None,
        expiry=ov.EntryExpiry.KEEP(),
    ),
)
report = await vault.sync(ov.SyncOptions(local_changed=True))
print(report.outcome)                           # SyncOutcome.UPLOADED, PULLED, ...

Edits stay in the local copy until sync. SyncOptions(local_changed=True) uploads them. It first merges in whatever other devices uploaded, with the same three-way merge as the other apps. local_changed=False only pulls. edit_entry(id, EntryInput(...)) changes an entry: it sets the fields you pass, removes the names in remove_fields, and leaves the rest alone. delete_entry moves an entry to the Recycle Bin.

account.create_vault("Name", None) creates a vault. The second argument is an organisation id.

A share link gives one entry, or some text, to someone without an account. The key is in the URL’s #fragment, so the server never sees it.

rec = vault.entry(entry_id)
payload = ov.item_share_payload(rec, ov.default_share_fields(), None)   # UserName, Password, URL
created = await account.create_share(
    payload,
    ov.ShareOptions(expires_in=3600, max_opens=1, passcode=None, vault_id=vault.id(), entry_id=entry_id),
)
print(created.url.decode())                     # https://share.openvireo.com/s/...#...

created.url is bytes, because it holds the key. ov.text_share_payload(b"text", "Title", None) shares plain text. account.list_shares() and account.revoke_share(id) manage your links.

Opening a link needs no account, only a client:

api = account.server_config().api               # e.g. https://accounts.openvireo.com/api/v1
share_id = ov.parse_share_link(link).id
info = await client.share_info(api, share_id)   # expires_at, opens_left, kdf (passcode needed?)
opened = await client.open_share(api, link.encode(), None, info)
for f in opened.payload.fields:
    print(f.label, f.value.decode())            # f.k: "username", "password", "url", "notes", "text", ...

Errors

Every failure is an ov.OvError, with these fields:

Field
codean ov.OvErrorCode (UNAUTHORIZED, NETWORK_ERROR, PLAN_LIMIT, …)
wire_codethe stable string ("unauthorized"). It’s the server’s own code when that isn’t one of OvErrorCode. Match on this in UI code.
messageEnglish text for logs
statusthe HTTP status, for server errors
retry_afterseconds, for RATE_LIMITED
detailsa JSON object string with camelCase keys, or None
server_codethe server’s code when it isn’t one of OvErrorCode
import json

try:
    step = await account.login(login)
except ov.OvError as e:
    if e.code == ov.OvErrorCode.UNAUTHORIZED:
        reason = json.loads(e.details or "{}").get("reason")
        print("wrong Secret Key" if reason == "keyset_unwrap_failed" else "wrong email or password")
    elif e.code == ov.OvErrorCode.NETWORK_ERROR:
        print("can't reach the server:", e.message)
    elif e.code == ov.OvErrorCode.RATE_LIMITED:
        print(f"try again in {e.retry_after}s")
    else:
        raise

The codes are the TypeScript SDK’s OpenVireoErrorCodes, one for one, plus internal. The SDK’s error list says what each one means. ov.error_code_wire(code) and ov.error_code_from_wire("plan_limit") convert between a code and its string.

The crypto functions raise OvError too, for example decryption_failed from ov.aead_decrypt.

asyncio

  • Any loop. A core call is a coroutine: await it from asyncio.run(...), an existing loop, or a framework built on asyncio (FastAPI, aiohttp). trio and curio aren’t supported.
  • Your Host’s coroutines run on the loop that awaits the core call. The core starts no threads, and every call stays on that loop. The shipped parts send blocking work (urllib, files, the keyring) through asyncio.to_thread, so the loop isn’t blocked.
  • Threads. Objects (OvClient, Account, Vault, …) are thread-safe handles. Each thread that calls the core needs its own running loop. ov.uniffi_set_event_loop(loop) forces one loop for every call, which you only need if you call the core from a thread with no running loop.
  • Synchronous calls (Vault.entries, add_entry, the crypto functions) do CPU work in the core and block the loop while they run. For a very large vault, use asyncio.to_thread.
  • Several asyncio.run calls in one script are fine. HttpxTransport keeps one httpx client per loop.

Cancellation

Two ways:

  • Cancel the task. task.cancel() raises CancelledError in the awaiting code. It drops the core’s future, and with it the Host call in progress (an HTTP request, for example).
  • A CancelToken. Every async method takes an optional cancel=. Calling token.cancel(), from any thread, makes each call that holds the token fail with OvError code ABORTED. One token can be shared by several calls, to cancel them as a group. Once cancelled, a token stays cancelled.
token = ov.CancelToken()
task = asyncio.create_task(vault.sync(ov.SyncOptions(local_changed=True), cancel=token))
...
token.cancel()
try:
    await task
except ov.OvError as e:
    assert e.code == ov.OvErrorCode.ABORTED

Live events

account.subscribe() opens the server’s event stream (server-sent events, parsed in the core):

stream = await account.subscribe()
while (event := await stream.next()) is not None:
    if isinstance(event, ov.AccountEvent.VAULT_CHANGED):
        await (await account.open_vault(event.vault_id)).sync(ov.SyncOptions(local_changed=False))
    elif isinstance(event, ov.AccountEvent.VAULTS_CHANGED):
        print("vault list or access changed")
    elif isinstance(event, ov.AccountEvent.SESSION_ENDED):
        break

stream.close() ends it, from any thread, and a pending next() then returns None.

The Host

openvireo.hosts has a ready-made part for each Host interface:

InterfacePartsdefault_host() uses
HttpTransportHttpxTransport (async, openvireo[httpx]), UrllibTransport (stdlib, in a worker thread)httpx if it’s installed, else urllib
SecureStoreMemoryStore, KeyringStore(service="openvireo") (openvireo[keyring])MemoryStore
BlobCacheFileCache(dir), MemoryCacheFileCache(cache_dir) if cache_dir= is given, else MemoryCache
ClockSystemClockSystemClock
LogSinkLoggingSink(logger=None), which logs to logging.getLogger("openvireo")LoggingSink

default_host(http=..., store=..., cache=..., clock=..., log=..., cache_dir=...) replaces any of them. The transports take timeout=. UrllibTransport also takes ssl_context= and proxies=. By default it uses the HTTPS_PROXY environment variables. HttpxTransport takes client= or other httpx.AsyncClient options.

The cache holds only ciphertext and public data (vault blobs encrypted under the vault key, the wrapped keyset, the discovery document). FileCache writes files 0600 in folders 0700.

Writing a part

Subclass the interface. HttpTransport, SecureStore and BlobCache have async methods. Clock.now_unix_ms and LogSink.log are plain methods, and the core may call log from any thread.

A transport wrapper that logs each request’s method and URL:

from openvireo.hosts import UrllibTransport


class LoggedTransport(ov.HttpTransport):
    def __init__(self, inner: ov.HttpTransport) -> None:
        self.inner = inner

    async def send(self, req: ov.HttpRequest) -> ov.HttpResponse:
        res = await self.inner.send(req)
        print(req.method.name, req.url, res.status)   # never log req.headers: they hold tokens
        return res

    async def open_stream(self, req: ov.HttpRequest) -> ov.OpenedStream:
        return await self.inner.open_stream(req)


host = default_host(http=LoggedTransport(UrllibTransport()))

The rules:

  • A transport must not follow redirects, must not store or send cookies, must send the core’s headers as given, and must return every HTTP status as a response (a 404 or a 500 is not an exception). It raises ov.TransportError (Offline(), Timeout(), Tls(message), Other(message)) only when there is no response. open_stream returns ov.OpenedStream(stream=...) over a ByteStream subclass (status(), async next_chunk() returning None at the end, and close()).
  • A store or cache returns None for a missing key. It raises ov.make_ov_error(ov.OvErrorCode.INTERNAL, "why") when it can’t read or write, so the core can tell a failure from a missing value.
  • Any other exception from a Host method reaches the core as network_error (from a transport) or internal, with the exception’s repr in the message. UniFFI also prints the traceback to stderr.

Secrets

Passwords, Secret Keys, field values and stored session tokens are plain bytes when they cross into Python. Python can’t wipe bytes, and copies may stay in memory until the garbage collector reuses it. The core zeroizes its own copies. If that matters for your program, keep secrets in Python for as short a time as you can, and don’t log the records: their __str__ prints field values.

Self-hosted servers

Your own OpenVireo account server. Pass its issuer URL to connect:

account = await client.connect("https://accounts.example.com")

The issuer must be https://. The exception is loopback (http://localhost:8000, for a local stack). Any other http:// URL fails with insecure_url. The core reads the API, sync and share URLs from the issuer’s discovery document.

A standalone sync server (no account, .kdbx files synced between paired devices): pair once with a code from a device that is already paired, then sync the database’s bytes:

sh = await ov.SelfHosted.pair(client, "https://sync.example.com", "ABCD-1234", "backup script")
# Later runs, with the same persistent store:
sh = await ov.restore_self_hosted(client, "https://sync.example.com")

creds = ov.KdbxCredentials(password=b"database password", key_file=None)
result = await sh.sync_database("passwords", kdbx_bytes, creds)

The pairing token is kept in the Host’s SecureStore and the sync state in its BlobCache, so use a persistent store (KeyringStore) and cache_dir=. result.kdbx is the merged database: save it as the local file.

Service accounts (an ov_sa_... token, for CI): await ov.ServiceAccount.from_token(client, token). Then vaults(refresh), read("ov://Vault/Entry/Field"), write(...) and inject(template). close() wipes its keys and cached vaults from memory, and later calls fail with signed_out.

Local .kdbx files

No account is needed:

creds = ov.KdbxCredentials(password=b"pw", key_file=None)
vault = await client.open_local(open("db.kdbx", "rb").read(), creds)
...
open("db.kdbx", "wb").write(await vault.save_local())

client.create_local("Name", creds) makes a new database. account.import_kdbx(data, creds, mode) turns one into a vault.

The examples are tested

The samples on this page run as tests/test_docs.py in bindings/python, against the in-memory servers (cargo xtask python --smoke).

The Core bindings docs cover OpenVireo core, develop (bcbf55a), last updated 21 November 2026. Found a mistake? Edit this page on GitHub.