vesta-client (Python)
Python client library for the Vesta protocol.
Installation
pip install vesta-client
Usage
import asyncio
from vesta_client import VestaAppConfig, VestaConnection, create_event, load_or_create_identity
async def main():
identity = load_or_create_identity("myapp-main-alice")
conn = VestaConnection(
app_config=VestaAppConfig(
app_id="myapp",
owner_public_key=identity.public_key_b64,
default_relays=["ws://localhost:5150/ws"],
),
identity=identity,
channels=["myapp/chat"],
)
conn.on_event(lambda msg: print(f"Event: {msg.event.event_type}"))
conn.on_connected(lambda welcome: print(f"Connected to {welcome.server_id}"))
await conn.connect()
# Publish
await conn.publish(create_event(
"myapp/chat", identity.client_id, "app.chat.message",
{"text": "Hello!", "username": "alice"}, identity=identity,
))
# Keep running
await asyncio.Event().wait()
asyncio.run(main())
app_config gives the connection a default file-backed RelayDirectory (override, manifest and
peer cache under ~/.vesta/relays/), resolves its relays from it and derives client_id from the
identity. For a quick local test you can still pass server_url="ws://localhost:5150/ws" and a
client_id instead.
API
VestaConnection
Async WebSocket connection with auto-reconnect.
Constructor
VestaConnection(
server_url: str | None = None, # or pass app_config / relay_directory / relays
client_id: str | None = None, # defaults to identity.client_id
channels: list[str] | None = None,
*,
app_config: VestaAppConfig | None = None, # builds a default RelayDirectory and resolves relays
relays: list[str] | None = None,
auto_reconnect: bool = True,
initial_reconnect_delay: float = 1.0,
max_reconnect_delay: float = 30.0,
last_sequences: dict[str, int] | None = None,
public_key: str | None = None,
identity: VestaIdentity | None = None, # enables device-group helpers
local_store: ClientEventStore | None = None, # offline outbox + event cache
relay_directory: RelayDirectory | None = None, # manifest verification + relay failover
)
Methods
await connect()— Open connection and handshakeawait disconnect()— Gracefully closeawait dispose()— Permanently disposeawait publish(event)— Publish a VestaEventawait subscribe(channel_id, from_sequence=None)— Subscribeawait unsubscribe(channel_id)— Unsubscribeawait fetch(channel_id, from_sequence, to_sequence=None, limit=None)— Fetch historyupdate_sequence(channel_id, sequence)— Update catch-up positionawait delete_channel(channel_id)— Soft-delete a channelawait register_app(app_id)— Register an app namespace (needed when the relay requires app registration)set_user_relay_override(url)/clear_user_relay_override()— Persist or clear the user's manual relay choice (requiresrelay_directory)await switch_relay(url)— Switch to a specific relay from the current candidate list and reconnectawait discover_relays(include_all=False)— Ask a reachable relay which relays host this app (or every relay it knows); show-onlyawait publish_relay_manifest(relays)— Sign and publish an owner relay manifest (identitymust be the app owner)
Device group helpers (require identity in constructor):
await create_device_group(device_name=None)— Create a new group, publish an announce, returngroup_idawait link_device(group_id, target_public_key, reason=None)— Vouch for another deviceawait join_device_group(group_id, device_name=None)— Announce this device joining an existing groupawait unlink_device(group_id, target_public_key, reason=None)— Remove a device from the groupawait get_device_group_members(group_id, timeout=5.0)— Replay the identity channel and return current membership asDeviceGroup
Event callbacks
on_event(callback)— Real-time event receivedon_events_batch(callback)— Batch of events receivedon_ack(callback)— Publish acknowledgedon_error(callback)— Raw server erroron_limited(callback)— Semantic "your app is being limited" signal — see "Limit notices" belowon_connected(callback)— Connection establishedon_reconnected(callback)— Fired instead of/alongsideon_connectedon a subsequent WELCOMEon_disconnected(callback)— Connection loston_relay_switched(callback)— The active relay changedon_manifest_applied(callback)— A newer owner-signed relay manifest was adopted
Limit notices
When the relay refuses a publish (quota, rate limit, unregistered app, ACL), the raw error is
still delivered via on_error, but classify_error_code(code) (also run internally) tells you
whether it's worth surfacing to the user and whether retrying can ever succeed:
conn.on_limited(lambda notice: print(notice.code, notice.message, "transient:", notice.is_transient))
When local_store is configured and the limit is not transient (e.g. QUOTA_EXCEEDED,
UNKNOWN_APP, ACCESS_DENIED), the matching outbox entry is automatically marked "rejected"
via mark_outbox_rejected so it is dead-lettered instead of retried forever.
Offline & persistence
ClientEventStore caches received events and queues outbox publishes made while disconnected.
The package ships InMemoryClientEventStore (non-persistent) and SqliteClientEventStore
(stdlib sqlite3, durable across restarts):
from vesta_client import SqliteClientEventStore
local_store = SqliteClientEventStore("my-app-cache.db")
conn = VestaConnection(server_url="ws://localhost:5150/ws", client_id=client_id,
channels=["myapp/chat"], local_store=local_store)
Projection snapshots
Every built-in reducer (AppendOnlyLog, LwwRegister, LwwMap) supports snapshot() /
restore() so a projection can resume from its last sequence instead of replaying the whole
channel on cold start. Persist snapshots with a ProjectionStore — InMemoryProjectionStore or
SqliteProjectionStore:
from vesta_client import LwwMap, restore_projection, save_projection
from vesta_client.projection_store import SqliteProjectionStore
store = SqliteProjectionStore("my-app-snapshots.db")
presence = LwwMap(project)
await restore_projection(store, channel_id, "presence", presence)
await conn.fetch(channel_id, presence.last_sequence + 1)
# ...later, e.g. on shutdown:
await save_projection(store, channel_id, "presence", presence)
A reducer that hasn't opted in raises SnapshotNotSupportedError — override snapshot() /
_restore_state() on a custom EventReducer subclass to add support.
Relay independence
RelayDirectory resolves an ordered relay candidate list from a user override, the latest
verified owner-signed manifest, and the app's compiled-in defaults (VestaAppConfig). Passing
app_config to VestaConnection attaches RelayDirectory.create_default(app_config) for you,
which gives manifest verification/adoption and set_user_relay_override() / clear_user_relay_override().
To control persistence, build the directory yourself and pass relay_directory:
from vesta_client import InMemoryManifestStore, InMemoryRelayOverrideStore, RelayDirectory, VestaAppConfig
app_config = VestaAppConfig(app_id="myapp", owner_public_key="...", default_relays=["wss://relay.example/ws"])
relay_directory = RelayDirectory(app_config, InMemoryRelayOverrideStore(), InMemoryManifestStore())
conn = VestaConnection(relay_directory=relay_directory, identity=identity, channels=["myapp/chat"])
FileRelayOverrideStore / FileManifestStore / FilePeerCacheStore are the file-backed
equivalents used by create_default.
Federation (server-to-server discovery)
When every relay in the candidate list is failing and no fresher manifest is available,
FederationClient asks any reachable discovery-enabled relay which relays host your app:
from vesta_client import FederationClient
federation = FederationClient(app_config)
base = FederationClient.to_federation_base_url("wss://relay.example/ws") # "https://relay.example/"
relays = await federation.discover_relays_for_app(base)
# Show-only: the user adopts one manually via conn.set_user_relay_override(url).
Every descriptor is verified (self-signature) and cross-checked against the app's owner
(owner_client_id must match derive_client_id(app_config.owner_public_key)) — a relay cannot
spoof hosting your app under a different owner. Uses the stdlib urllib.request internally — no
extra dependency.
create_event(channel_id, client_id, event_type, payload, **kwargs)
Create a VestaEvent with a UUID and current timestamp.
load_or_create_identity(prefix)
Persist a stable clientId in ~/.vesta/{prefix}-identity.json.
Metadata
Release files for vesta-client 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vesta_client-0.2.0.tar.gz | 63.9 kB | With provenance | Details for vesta_client-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vesta_client-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for vesta_client-0.2.0-py3-none-any.whl |
Total release size: 119.0 kB
Release files / vesta_client-0.2.0.tar.gz
| Download URL | vesta_client-0.2.0.tar.gz |
|---|---|
| Size | 63.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3bf1c44e0aa8b9d5d4c009051d3a21bbe367c7076f33fd761450c20983fce4f6
|
|
BLAKE2b-256 checksum How to use checksums |
1ef3e414132979f2d622c8b95abc06975bdca69d7fa736a1e47ab21c4d262f4e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logRelease files / vesta_client-0.2.0-py3-none-any.whl
| Download URL | vesta_client-0.2.0-py3-none-any.whl |
|---|---|
| Size | 55.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
82022d7749a962d24757eca661c414757c3cc049027af5ca9dc51711f5dcb967
|
|
BLAKE2b-256 checksum How to use checksums |
5291edb85fad30e4ab03d26f83d735ae80109c2e2823d59bc5b3386070a87135
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logSecurity for vesta-client 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for vesta_client-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.