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.nameis what the account’s device list shows. Scripts usePlatform.CLI.offline=Truekeeps the offline cache: unlock, list and open vaults without the network, and keep edits until they upload. It needs a persistent cache: passcache_dir=todefault_host.serveris a discovery document to use instead of fetching one. Leave itNone.
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
connectfetches the server’s discovery document and loads a stored session if there is one. The account is then signed in but locked, andunlockopens it with the master password.- A device that has never seen the account doesn’t have the Secret Key.
loginwithout one fails withinvalid_secret_key. Ask for the key and try again. Withtrust_device=Truethe 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 alsounauthorized;detailstells them apart (see Errors). - An account with two-step sign-in returns
LoginStep.NEEDS_TOTP. Send the code withsubmit_totp. A wrong code isinvalid_mfaand the same challenge can be used again (challenge.attempt()counts the tries). After the fifth wrong code, or once the challenge expires, the result ismfa_expiredand the sign-in starts again. If you already have the code, passtotp="123456"inLoginInputto skip that step. LoginStep.UNLOCKEDcarriesunlocked(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)givesEntrySummaryrecords (id,title,username,url,group_path,tags, …). They have no field values.entry(id)gives the fullEntryRecord. ItsfieldsareFieldRecord(name, value, protected), and everyvalueisbytes(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.
Share links
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 | |
|---|---|
code | an ov.OvErrorCode (UNAUTHORIZED, NETWORK_ERROR, PLAN_LIMIT, …) |
wire_code | the stable string ("unauthorized"). It’s the server’s own code when that isn’t one of OvErrorCode. Match on this in UI code. |
message | English text for logs |
status | the HTTP status, for server errors |
retry_after | seconds, for RATE_LIMITED |
details | a JSON object string with camelCase keys, or None |
server_code | the 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, useasyncio.to_thread. - Several
asyncio.runcalls in one script are fine.HttpxTransportkeeps one httpx client per loop.
Cancellation
Two ways:
- Cancel the task.
task.cancel()raisesCancelledErrorin 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 optionalcancel=. Callingtoken.cancel(), from any thread, makes each call that holds the token fail withOvErrorcodeABORTED. 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:
| Interface | Parts | default_host() uses |
|---|---|---|
HttpTransport | HttpxTransport (async, openvireo[httpx]), UrllibTransport (stdlib, in a worker thread) | httpx if it’s installed, else urllib |
SecureStore | MemoryStore, KeyringStore(service="openvireo") (openvireo[keyring]) | MemoryStore |
BlobCache | FileCache(dir), MemoryCache | FileCache(cache_dir) if cache_dir= is given, else MemoryCache |
Clock | SystemClock | SystemClock |
LogSink | LoggingSink(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_streamreturnsov.OpenedStream(stream=...)over aByteStreamsubclass (status(),async next_chunk()returningNoneat the end, andclose()). - A store or cache returns
Nonefor a missing key. It raisesov.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) orinternal, with the exception’sreprin 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.