How to Use remnawave-api for Remnawave API Automation

remnawave-api is useful when Remnawave operations need repeatable automation rather than manual dashboard clicks. The practical value is safer provisioning: scripts can create users, rotate data, check limits, and record changes consistently when credentials and logging are handled carefully.

What is remnawave-api#

remnawave-api is a Python SDK for working with the Remnawave panel API. In practical terms, it lets you manage Remnawave data from your own scripts instead of clicking through a web dashboard for every task. That matters if you run a VPN service, manage user access, or want to automate repeatable admin work like listing users, checking usage, or creating squads and profiles.

The package name has changed over time, which is important if you are following older tutorials. The legacy package was remnawave_api, but the actively maintained package is now remnawave. The GitHub repository has also moved from sm1ky/remnawave-api to remnawave/python-sdk.

People usually use this SDK when they want to:

• integrate Remnawave into internal tooling
• automate VPN account lifecycle tasks
• pull data into scripts, dashboards, or monitoring jobs
• reduce manual panel work for ops and support teams

If you already understand Python and HTTP APIs, this SDK gives you a cleaner, typed way to talk to Remnawave without hand-writing every request.

Installation#

The recommended route is to install the new package name, remnawave. You only need the legacy package if you are maintaining an older script that still depends on version 1.x.

1) Create a virtual environment#

On Linux and macOS:

python3 -m venv .venv
source .venv/bin/activate

On Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

2) Install the package#

Recommended installation:

pip install remnawave

Legacy installation for older codebases:

pip install remnawave_api

If you want the development branch from GitHub:

pip install git+https://github.com/remnawave/python-sdk.git@development

3) Check your Python version and dependencies#

The SDK depends on modern Python tooling and uses packages like httpx, orjson, and rapid-api-client. If installation fails, make sure your environment is current and that pip is upgraded.

python --version
pip install --upgrade pip

If you are using Poetry in a project, install the package through your normal dependency workflow instead of mixing tools.

poetry add remnawave

Basic Configuration#

The SDK talks to your Remnawave panel using two things:

• the base URL of the panel
• an API token from the panel’s API token section

A simple setup usually looks like this.

export REMNAWAVE_BASE_URL="https://vpn.example.com"
export REMNAWAVE_TOKEN="your-api-token-here"

On Windows PowerShell:

$env:REMNAWAVE_BASE_URL="https://vpn.example.com"
$env:REMNAWAVE_TOKEN="your-api-token-here"

Then use the SDK in an async Python script:

import asyncio
import os

from remnawave import RemnawaveSDK

async def main():
    base_url = os.environ["REMNAWAVE_BASE_URL"]
    token = os.environ["REMNAWAVE_TOKEN"]

    sdk = RemnawaveSDK(base_url=base_url, token=token)

    users_response = await sdk.users.get_all_users_v2()

    print(f"Total users: {users_response.total}")
    for user in users_response.users[:5]:
        print(user)

if __name__ == "__main__":
    asyncio.run(main())

A few things to notice:

• the SDK is asynchronous, so you run it inside asyncio
• the token is used for authentication, so treat it like a secret
• the response objects are typed, which helps you discover fields in your editor

If you want a quick smoke test, use a short script like this one and confirm that it prints a user count instead of raising an auth or connection error.

Common Use Cases#

1) List users for audits or support checks#

A common job in VPN operations is verifying who exists in the panel and whether the account data looks correct. This is useful when a customer says their connection stopped working or when you need to confirm whether a user was created in the right place.

import asyncio
import os

from remnawave import RemnawaveSDK

async def main():
    sdk = RemnawaveSDK(
        base_url=os.environ["REMNAWAVE_BASE_URL"],
        token=os.environ["REMNAWAVE_TOKEN"],
    )

    response = await sdk.users.get_all_users_v2()

    print(f"Users found: {response.total}")
    for user in response.users:
        print(user.id, user.email, user.status)

asyncio.run(main())

This kind of script is handy for support teams, cron jobs, and admin dashboards.

2) Pull configuration profile data#

If you manage multiple VPN plans or different profile types, config profiles let you keep settings consistent. The SDK includes controller-based access for newer Remnawave features, so you can script profile retrieval instead of copying values from the UI.

import asyncio
import os

from remnawave import RemnawaveSDK

async def main():
    sdk = RemnawaveSDK(
        base_url=os.environ["REMNAWAVE_BASE_URL"],
        token=os.environ["REMNAWAVE_TOKEN"],
    )

    profiles = await sdk.config_profiles.get_all_config_profiles()

    for profile in profiles.items:
        print(profile.id, profile.name)

asyncio.run(main())

Use this when you want to compare profiles across environments or confirm that a deployment changed the right settings.

3) Automate squad or infrastructure workflows#

The newer SDK supports controllers for features like internal squads and infrastructure billing. That makes it a better fit for teams that need to organize VPN access by customer group, internal team, or service tier.

import asyncio
import os

from remnawave import RemnawaveSDK
from remnawave.models import CreateInternalSquadRequestDto

async def main():
    sdk = RemnawaveSDK(
        base_url=os.environ["REMNAWAVE_BASE_URL"],
        token=os.environ["REMNAWAVE_TOKEN"],
    )

    request = CreateInternalSquadRequestDto(
        name="security-ops",
        description="Accounts for the security operations team",
    )

    squad = await sdk.internal_squads.create_internal_squad(request)
    print(squad)

asyncio.run(main())

This is the kind of automation that saves time when your team grows and manual panel work starts becoming error-prone.

Tips and Gotchas#

• Use the new package name remnawave for active development. The old remnawave_api package is deprecated and may not receive future fixes.
• Match your SDK version to the Remnawave panel version. Version mismatches are a common source of confusing API errors.
• Keep your API token out of source control. Use environment variables or a secrets manager instead of hardcoding it in scripts.
• Remember that the SDK is async. If you forget asyncio.run(...), your script will not behave correctly.
• Start by reading simple responses like get_all_users_v2() before moving on to create, update, or delete operations.
• If you are migrating from an older script, check import paths carefully. The package name, model names, and controller layout changed in the newer SDK.
• When debugging, verify three things first: the base URL, the token, and whether your panel version matches the SDK contract version.

A practical habit is to build one small script at a time. First, confirm authentication. Then list users. Then move on to writes such as creating squads or updating profiles. That approach makes it much easier to isolate mistakes.

Conclusion#

remnawave-api is a useful Python tool for automating Remnawave administration, especially if you want typed API access instead of manual panel work. If you manage VPN users, config profiles, or operational workflows, the new remnawave package is the version you should learn and use first.

What to read next?#

• Open the GigaTap VPN guides hub for the setup, protocol choice, and troubleshooting path.
• Use the guided VPN start flow if you need to choose between setup, client, docs, or profile checks.
• For device-specific import paths, open the VPN client setup hub.
• Check the official GigaTap docs before changing a client profile or import flow.
• For a nearby scenario, read the Xray-core protocol guide.

If the symptom looks like a mismatch between payment, entitlement, and provider runtime state, capture the client behavior first and change the protocol or profile only after that baseline is clear.

Definition#

• remnawave-api - a Python SDK for automating Remnawave API workflows such as user provisioning, subscription management, checks, and operational reporting.

Comparison#

Workflow	Use when	Watch out for
remnawave-api script	Repeated API work needs auditability and fewer manual clicks.	Store tokens safely and avoid dumping raw responses into logs.
Dashboard changes	A one-off admin action is faster by hand.	Manual edits are harder to reproduce and review.
Custom HTTP client	The SDK does not cover a needed endpoint.	You own retries, validation, pagination, and error handling.

FAQ#

When should teams automate Remnawave tasks?#

Teams should automate tasks that repeat, affect many users, or need consistent records. One-off investigation can stay manual, but provisioning, rotation, and checks are better as reviewed scripts.

What is the main operational risk?#

The main risk is not the SDK itself; it is unsafe credential handling and noisy logs. Tokens, raw user data, and full API responses should be redacted before sharing or storing output.