remnawave-client

Sync and async client for the Remnawave API, generated from the panel's OpenAPI specification.

pip install remnawave-client

Requires Python 3.11 or newer.

Versions

The library version equals the API version it was generated from. A tag exists for every minor release of the panel from 2.0 onwards, so pin the one matching your deployment:

pip install remnawave-client==<your panel version>

Quick start

from remnawave import Remnawave

with Remnawave("https://panel.example.com", token) as rw:
    user = rw.users.get_user_by_username("zen")
    print(user.username, user.status, user.expire_at)

    for u in rw.users.iter_users():
        print(u.username)

The async client mirrors it:

import asyncio

from remnawave import AsyncRemnawave

async def main() -> None:
    async with AsyncRemnawave("https://panel.example.com", token) as rw:
        stats = await rw.system.get_stats()
        nodes = await rw.nodes.get_nodes()
        async for user in rw.users.iter_users():
            print(user.username)

asyncio.run(main())

More in examples/: pagination, partial updates, error handling, webhooks and swapping out the client's parts.

Background jobs

Some checks run as panel jobs: one request starts the job and returns a jobId, another polls its status. wait_* does both and returns the result:

result = rw.connections.wait_connections_by_user(user_id, timeout=120)
for node in result.nodes:
    print(node.node_name, [ip.ip for ip in node.ips])

A job the panel reports as failed raises JobFailedError; one still running after timeout seconds raises JobTimeoutError. The underlying start and poll methods stay available.

Errors

Everything the library raises inherits from RemnawaveError. Below it the hierarchy splits by cause: ApiError for anything the panel answered with, TransportError when the request never got a reply, SerializationError when the payload did not match the schema.

from remnawave.exceptions import NotFoundError

try:
    rw.users.get_user_by_id(42)
except NotFoundError as error:
    print(error.status, error.error_code)  # 404 'A025'

error_code is the panel's own code and is more specific than the HTTP status — branch on it when you need to tell cases apart.

Webhooks

from remnawave.webhooks import SIGNATURE_HEADER, WebhookReceiver

hooks = WebhookReceiver(secret=os.environ["WEBHOOK_SECRET_HEADER"])
event = hooks.receive(request.body, request.headers[SIGNATURE_HEADER])

if event.scope == "user":
    print(event.event, event.data.username)

Pass the raw request body: the signature covers those exact bytes, so re-serialising parsed JSON breaks verification.

Regenerating

src/remnawave/_generated/ is machine-written and must not be edited by hand. Regenerating it against the version the package declares takes no arguments:

python -m tools.codegen

To move the project onto a newer panel release, drop its specification into specs/ and pass the version once:

python -m tools.codegen <version>

Where the specification is wrong or awkward, overlay.yaml patches it before generation: type names, forced field types, fields kept out of repr. Editing the generated code directly would be lost on the next run; editing the vendored specification would be lost on the next update.