Remnawave

https://docs.rw/
Admin
Remnawave is a powerful proxy management tool built on Xray-core, focusing on simplicity and ease of...
Tokens:88,460
Snippets:737
Trust Score:7.1
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install Go SDK with go get

Source: https://docs.rw/sdk/go-sdk/

Install the Remnawave Go SDK. Always pin the SDK version to match the Remnawave panel version.

```bash
go get github.com/Jolymmiles/remnawave-api-go/v2@latest
```

--------------------------------

### Example .env file with miscellaneous environment variables

Source: https://docs.rw/install/environment-variables/

Example .env file showing how to set the miscellaneous environment variables. The values shown are examples; adjust them according to your needs.

```bash
SHORT_UUID_LENGTH=16
IS_HTTP_LOGGING_ENABLED=true
ENABLE_DEBUG_LOGS=false
JWT_AUTH_LIFETIME=12
SERVICE_CLEAN_USAGE_HISTORY=false
SERVICE_DISABLE_USER_USAGE_RECORDS=false
USER_USAGE_IGNORE_BELOW_BYTES=0
```

--------------------------------

### DATABASE_URL example

Source: https://docs.rw/install/environment-variables/

Example DATABASE_URL environment variable.

```bash
DATABASE_URL="postgresql://postgres:postgres@remnawave-db:5432/postgres"
```

--------------------------------

### Ports .env example

Source: https://docs.rw/install/environment-variables/

Example .env file showing the default values for APP_PORT and METRICS_PORT.

```bash
APP_PORT=3000
METRICS_PORT=3001
```

--------------------------------

### Scaling API .env example

Source: https://docs.rw/install/environment-variables/

Example .env file showing the default value for API_INSTANCES.

```bash
API_INSTANCES=1
```

--------------------------------

### Database .env example

Source: https://docs.rw/install/environment-variables/

Example .env file for PostgreSQL database configuration, including POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and DATABASE_URL.

```bash
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=postgres

DATABASE_URL="postgresql://postgres:postgres@remnawave-db:5432/postgres"
```

--------------------------------

### Redis .env example

Source: https://docs.rw/install/environment-variables/

Example .env file for Redis configuration. Sets REDIS_HOST and REDIS_PORT.

```bash
REDIS_HOST=remnawave-redis
REDIS_PORT=6379
```

--------------------------------

### Install required dependencies (Git and wget)

Source: https://docs.rw/migrate/marzban/

Updates system packages and installs Git and wget. Verify installation with `git --version` and `wget --version`.

```bash
# Update system packages
sudo apt-get update

# Install Git and wget
sudo apt-get install -y git wget
```

--------------------------------

### Example .env file for webhook configuration

Source: https://docs.rw/install/environment-variables/

Example .env file enabling webhook notifications and setting the webhook URL and secret header.

```bash
WEBHOOK_ENABLED=true
WEBHOOK_URL=https://your-server.com/webhook-path
WEBHOOK_SECRET_HEADER=strong_secret_key
```

--------------------------------

### Install logrotate

Source: https://docs.rw/install/remnawave-node/

Installs logrotate if not already installed.

```bash
sudo apt update && sudo apt install logrotate
```

--------------------------------

### Bandwidth usage notifications .env example

Source: https://docs.rw/install/environment-variables/

Example .env file enabling bandwidth usage notifications and setting a threshold array. The threshold must be in ascending order, an array of integers between 25 and 95, with no more than 5 values.

```bash
BANDWIDTH_USAGE_NOTIFICATIONS_ENABLED=true
BANDWIDTH_USAGE_NOTIFICATIONS_THRESHOLD=[60, 80]
```

--------------------------------

### APP_SECRET .env example

Source: https://docs.rw/install/environment-variables/

Example .env file for setting the APP_SECRET environment variable.

```bash
APP_SECRET=strong_secret_key
```

--------------------------------

### Complete public config profile example

Source: https://docs.rw/learn-en/server-routing/

This is a complete Xray public config profile example. It includes an inbound with VLESS+Reality, outbounds for DIRECT, BLOCK, and Shadowsocks to DE, and routing rules that block private IPs/domains and bittorrent, direct Russian traffic, and proxy the rest to SS_OUTBOUND_TO_DE. Note that placeholders like 'USE YOUR OWN VALUE!' must be replaced.

```json
{
    "log": {
        "loglevel": "none"
    },
    "inbounds": [
        {
            "tag": "PUBLIC_RU_INBOUND",
            "port": 443,
            "listen": "0.0.0.0",
            "protocol": "vless",
            "settings": {
                "clients": [],
                "decryption": "none"
            },
            "sniffing": {
                "enabled": true,
                "destOverride": ["http", "tls", "quic"]
            },
            "streamSettings": {
                "network": "raw",
                "security": "reality",
                "realitySettings": {
                    "target": "USE YOUR OWN VALUE!",
                    "show": false,
                    "xver": 0,
                    "shortIds": [""],
                    "privateKey": "USE YOUR OWN KEY!",
                    "serverNames": ["USE YOUR OWN VALUES!"]
                }
            }
        }
    ],
    "outbounds": [
        {
            "protocol": "freedom",
            "tag": "DIRECT"
        },
        {
            "protocol": "blackhole",
            "tag": "BLOCK"
        },
        {
            "tag": "SS_OUTBOUND_TO_DE",
            "protocol": "shadowsocks",
            "settings": {
                "servers": [
                    {
                        "address": "DE NODE ADDRESS",
                        "password": "PASSWORD FROM PREVIOUS STEP",
                        "port": 9999,
                        "level": 0,
                        "method": "chacha20-ietf-poly1305"
                    }
                ]
            }
        }
    ],
    "routing": {
        "rules": [
            {
                "ip": ["geoip:private"],
                "outboundTag": "BLOCK"
            },
            {
                "domain": ["geosite:private"],
                "outboundTag": "BLOCK"
            },
            {
                "protocol": ["bittorrent"],
                "outboundTag": "BLOCK"
            },
            {
                "ip": ["geoip:ru"],
                "outboundTag": "DIRECT"
            },
            {
                "domain": ["geosite:category-ru"],
                "outboundTag": "DIRECT"
            },
            {
                "inboundTag": ["PUBLIC_RU_INBOUND"],
                "outboundTag": "SS_OUTBOUND_TO_DE"
            }
        ]
    }
}
```

--------------------------------

### Start or recreate TinyAuth container

Source: https://docs.rw/security/tinyauth-for-nginx/

Use these commands to start or recreate the TinyAuth container and follow its logs. After running, open a protected application to confirm Nginx redirects to https://tinyauth.example.com.

```bash
docker compose up -d --force-recreate tinyauth
docker compose logs -f tinyauth
```

--------------------------------

### Public Profile Example (JSON)

Source: https://docs.rw/learn-en/server-routing/

Full example of a public profile configuration with inbounds, outbounds, and routing rules. The inbounds section is not the focus; the outbounds, routing, and rules arrays are to be modified. Placeholder values like 'USE YOUR OWN VALUE!' and 'USE YOUR OWN KEY!' must be replaced.

```json
{
    "log": {
        "loglevel": "none"
    },
    "inbounds": [
        {
            "tag": "PUBLIC_RU_INBOUND",
            "port": 443,
            "listen": "0.0.0.0",
            "protocol": "vless",
            "settings": {
                "clients": [],
                "decryption": "none"
            },
            "sniffing": {
                "enabled": true,
                "destOverride": ["http", "tls", "quic"]
            },
            "streamSettings": {
                "network": "raw",
                "security": "reality",
                "realitySettings": {
                    "target": "USE YOUR OWN VALUE!",
                    "show": false,
                    "xver": 0,
                    "shortIds": [""],
                    "privateKey": "USE YOUR OWN KEY!",
                    "serverNames": ["USE YOUR OWN VALUES!"]
                }
            }
        }
    ],
    "outbounds": [
        {
            "protocol": "freedom",
            "tag": "DIRECT"
        },
        {
            "protocol": "blackhole",
            "tag": "BLOCK"
        }
    ],
    "routing": {
        "rules": [
            {
                "ip": ["geoip:private"],
                "outboundTag": "BLOCK"
            },
            {
                "domain": ["geosite:private"],
                "outboundTag": "BLOCK"
            },
            {
                "protocol": ["bittorrent"],
                "outboundTag": "BLOCK"
            }
        ]
    }
}
```

--------------------------------

### Start container and follow logs

Source: https://docs.rw/install/reverse-proxies/try-cloudflare/

Starts the Docker Compose services in detached mode and then follows the logs to see the tunnel URL.

```bash
docker compose up -d && docker compose logs -f
```

--------------------------------

### Install Docker using official script

Source: https://docs.rw/install/requirements/

Run this command to install Docker with the Docker Compose plugin on Ubuntu or Debian. Requires sudo privileges.

```bash
sudo curl -fsSL https://get.docker.com | sh
```

--------------------------------

### Create and manage users

Source: https://docs.rw/sdk/go-sdk/

Demonstrates creating a user, then disabling, enabling, and deleting that user using the sub-client methods.

```go
package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Create user
    createResp, err := client.Users().CreateUser(ctx, &remapi.CreateUserRequest{
        Username: "john_doe",
    })
    if err != nil {
        log.Fatal(err)
    }

    user := createResp.(*remapi.UserResponse).Response
    fmt.Printf("Created user: %s (UUID: %s)\n", user.Username, user.UUID)

    // Disable user
    _, err = client.Users().DisableUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User disabled")

    // Enable user
    _, err = client.Users().EnableUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User enabled")

    // Delete user
    _, err = client.Users().DeleteUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User deleted")
}
```

--------------------------------

### Example .env file for Telegram notifications

Source: https://docs.rw/install/environment-variables/

Example .env file showing how to configure Telegram notification environment variables. The chat_id format is 'chat_id' or 'chat_id:thread_id', and Telegram Group Chat IDs always start with '-100'.

```bash
# Disable/Enable Telegram notifications
IS_TELEGRAM_NOTIFICATIONS_ENABLED=false

# Telegram bot token
TELEGRAM_BOT_TOKEN=change_me

# Optional: proxy for Telegram Bot
# TELEGRAM_BOT_PROXY=socks5://user:password@host:port

# Notifications (format: chat_id or chat_id:thread_id)
TELEGRAM_NOTIFY_USERS=change_me
TELEGRAM_NOTIFY_NODES=change_me
TELEGRAM_NOTIFY_CRM=change_me
TELEGRAM_NOTIFY_SERVICE=change_me
TELEGRAM_NOTIFY_TBLOCKER=change_me
```

--------------------------------

### Basic usage: create client and get user by UUID

Source: https://docs.rw/sdk/go-sdk/

Shows how to create a base client with a static token, wrap it with sub-clients, and fetch a user by UUID. Handles success, not-found, and validation error responses.

```go
package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    // Create base client
    baseClient, err := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    if err != nil {
        log.Fatal(err)
    }

    // Wrap with organized sub-clients
    client := remapi.NewClientExt(baseClient)

    // Get user by UUID - simplified signature
    resp, err := client.Users().GetUserByUuid(ctx, "user-uuid-here")
    if err != nil {
        log.Fatal(err)
    }

    switch r := resp.(type) {
    case *remapi.UserResponse:
        fmt.Printf("User: %s\n", r.Response.Username)
    case *remapi.NotFoundError:
        fmt.Println("User not found")
    case *remapi.BadRequestError:
        fmt.Printf("Validation error: %v\n", r.Errors)
    }
}
```

--------------------------------

### Install remnawave via pip

Source: https://docs.rw/sdk/python-sdk/

Install the Remnawave Python SDK using pip.

```bash
pip install remnawave
```

--------------------------------

### Start Caddy container

Source: https://docs.rw/install/reverse-proxies/caddy/

Starts the Caddy container in detached mode and follows the logs.

```bash
docker compose up -d && docker compose logs -f -t
```

--------------------------------

### Install dependencies: cron and socat

Source: https://docs.rw/install/reverse-proxies/nginx/

Installs cron and socat, required for acme.sh and certificate renewal.

```bash
sudo apt-get install cron socat
```

--------------------------------

### Create Caddyfile directory and file

Source: https://docs.rw/install/reverse-proxies/caddy/

Creates the /opt/remnawave/caddy directory and opens the Caddyfile in nano for editing.

```bash
mkdir -p /opt/remnawave/caddy && cd /opt/remnawave/caddy && nano Caddyfile
```

--------------------------------

### Full .env file reference

Source: https://docs.rw/install/subscription-page/bundled/

Complete .env file with all optional settings including CUSTOM_SUB_PREFIX, MARZBAN_LEGACY_LINK_ENABLED, CADDY_AUTH_API_TOKEN, and TRUST_PROXY.

```bash
APP_PORT=3010

### Remnawave Panel URL, can be http://remnawave:3000 or https://panel.example.com
REMNAWAVE_PANEL_URL=http://remnawave:3000
REMNAWAVE_API_TOKEN=API_TOKEN_FROM_REMNAWAVE

# Serve at custom root path, for example, this value can be: CUSTOM_SUB_PREFIX=sub
# Do not place / at the start/end
CUSTOM_SUB_PREFIX=

# Support Marzban links
MARZBAN_LEGACY_LINK_ENABLED=false
MARZBAN_LEGACY_SECRET_KEY=

# If you use "Caddy with security" addon, you can place here X-Api-Key, which will be applied to requests to Remnawave Panel.
CADDY_AUTH_API_TOKEN=

# Express `trust proxy` setting, used so the real client IP is resolved from
# the trusted hop and cannot be spoofed via X-Forwarded-For. Accepts:
#   - "true" / "false"                          -> trust all / none
#   - a non-negative integer (e.g. 1, 2)        -> number of trusted hops
#   - a comma-separated list of preset names    -> loopback, linklocal, uniquelocal
#     and/or IP addresses / CIDR subnets        -> e.g. 127.0.0.1, 172.16.0.0/12
# See https://expressjs.com/en/guide/behind-proxies/
TRUST_PROXY=1
```

--------------------------------

### Install acme.sh

Source: https://docs.rw/install/reverse-proxies/nginx/

Downloads and installs acme.sh using the provided email address. Replace EMAIL with your email.

```bash
curl https://get.acme.sh | sh -s email=EMAIL && source ~/.bashrc
```

--------------------------------

### Download docker-compose.yml and .env.sample

Source: https://docs.rw/install/remnawave-panel/

Downloads the docker-compose.yml and .env files from the Remnawave backend repository. The .env file is created from the .env.sample template.

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/remnawave/backend/refs/heads/main/docker-compose-prod.yml && curl -o .env https://raw.githubusercontent.com/remnawave/backend/refs/heads/main/.env.sample
```

--------------------------------

### Install @remnawave/xtls-sdk

Source: https://docs.rw/sdk/xtls-sdk/

Install the official Remnawave XTLS SDK via npm. This is the core package for interacting with the gRPC Xray API.

```bash
npm install @remnawave/xtls-sdk
```

--------------------------------

### Create project directory

Source: https://docs.rw/install/remnawave-panel/

Creates the /opt/remnawave directory and changes into it. This is the first step before downloading the required files.

```bash
mkdir /opt/remnawave && cd /opt/remnawave
```

--------------------------------

### Practical chain configuration with include-proxies

Source: https://docs.rw/guides/templates/mihomo/

Complete example of creating a chain through a Russian server for access to European servers. Includes a proxy-provider with dialer-proxy and additional-prefix, and a proxy-group using the chain. The comment '# LEAVE THIS LINE!' indicates a required placeholder.

```yaml
# Creating chain through Russian server for access to European servers
proxy-providers:
    russlanddialer: # Chain from Russia to other countries
        type: inline
        exclude-filter: '🇷🇺|🇳🇱' # Filter for proxies that won't be used for chaining
        remnawave: # Custom field used only in Remnawave
            include-proxies: true # Adds proxies for chain creation
        override:
            dialer-proxy: 🇷🇺 Russia # Host name that will be chain for European exit (can also be proxy-group)
            additional-prefix: '🇷🇺➡️' # Prefix for proxy name (indicates bridge from Russia)
        payload:

# Using chain in group
proxy-groups:
    - name: PROXY
      icon: https://cdn.jsdelivr.net/gh/Koolson/Qure@master/IconSet/Color/Hijacking.png
      type: select
      proxies:
          - ⚡️ Fastest
          # LEAVE THIS LINE!
      use: # This parameter adds chains to the group
          - russlanddialer
    - name: ⚡️ Fastest
      icon: https://cdn.jsdelivr.net/gh/Koolson/Qure@master/IconSet/Color/Auto.png
      type: url-test
      tolerance: 150
      url: https://cp.cloudflare.com/generate_204
      interval: 300
      include-all: true # Core functionality, adds all available proxies to this group
      exclude-filter: '🇷🇺' # Excludes Russia from them
      remnawave: # Custom field used only in Remnawave (disables adding all proxies to this section, except manually specified)
          include-proxies: false
      proxies:
          # LEAVE THIS LINE!
```

--------------------------------

### Iterate through users with PaginationHelper

Source: https://docs.rw/sdk/go-sdk/

Shows how to create a client, use PaginationHelper to page through all users, and print each user's username and UUID. Requires a valid panel URL and API token.

```go
package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Use PaginationHelper for iterating through pages
    pager := remapi.NewPaginationHelper(50) // 50 items per page

    for pager.HasMore {
        resp, err := client.Users().GetAllUsers(ctx,
            pager.Limit,  // size
            pager.Offset, // start
        )
        if err != nil {
            log.Fatal(err)
        }

        users := resp.(*remapi.GetAllUsersResponse)
        for _, user := range users.Response.Users {
            fmt.Printf("User: %s (UUID: %s)\n", user.Username, user.UUID)
        }

        // Advance to next page
        pager.SetTotal(int(users.Response.Total))
        pager.NextPage()
    }

    fmt.Printf("Total users: %d\n", *pager.Total)
}
```

--------------------------------

### Install certificate with acme.sh

Source: https://docs.rw/install/reverse-proxies/nginx/

Installs the issued certificate to the specified key and fullchain files. Replace DOMAIN with your domain. This command is used after the certificate is issued.

```bash
acme.sh --install-cert -d 'DOMAIN' --key-file /opt/remnawave/nginx/privkey.key --fullchain-file /opt/remnawave/nginx/fullchain.pem --reloadcmd "docker exec remnawave-nginx nginx -s reload"
```

--------------------------------

### Install Remnawave TypeScript SDK with npm

Source: https://docs.rw/sdk/typescript-sdk/

Install the @remnawave/backend-contract package. Always pick and pin the correct version of the SDK to match the version of the Remnawave backend.

```bash
npm install @remnawave/backend-contract
```

--------------------------------

### Example webhook payload

Source: https://docs.rw/features/webhooks/

JSON payload structure sent by Remnawave. Contains scope, event, timestamp, and data fields. The example shows a service.panel_started event with the panel version.

```json
{
    "scope": "service",
    "event": "service.panel_started",
    "timestamp": "2026-01-07T11:57:29.426Z",
    "data": {
        "panelVersion": "2.5.0"
    }
}
```

--------------------------------

### Create Angie folder

Source: https://docs.rw/install/reverse-proxies/angie/

Creates the directory /opt/remnawave/angie and changes into it. Run this before configuring Angie.

```bash
mkdir -p /opt/remnawave/angie && cd /opt/remnawave/angie
```

--------------------------------

### Create .env file for subscription page

Source: https://docs.rw/install/subscription-page/bundled/

Creates the directory and opens a new .env file for the subscription page.

```bash
mkdir -p /opt/remnawave/subscription && cd /opt/remnawave/subscription && nano .env
```

--------------------------------

### Download Caddyfile for full security setup with MFA

Source: https://docs.rw/security/caddy-with-minimal-setup/

Downloads the Caddyfile for the full security setup with MFA, which protects all routes including /api/sub/* endpoints and requires OTP-based MFA for login.

```bash
curl -o Caddyfile https://raw.githubusercontent.com/remnawave/caddy-with-auth/refs/heads/main/examples/minimal-security-setup-with-mfa/Caddyfile
```

--------------------------------

### Node management: list and get nodes

Source: https://docs.rw/sdk/go-sdk/

Shows how to retrieve all nodes and then fetch a single node by UUID, printing connection status and details.

```go
package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Get all nodes
    nodesResp, err := client.Nodes().GetAllNodes(ctx)
    if err != nil {
        log.Fatal(err)
    }

    nodes := nodesResp.(*remapi.NodesResponse).Response
    fmt.Printf("Total nodes: %d\n", len(nodes))

    for _, node := range nodes {
        fmt.Printf("  - %s (%s): connected=%v\n",
            node.Name, node.Address, node.IsConnected)
    }

    // Get single node
    if len(nodes) > 0 {
        nodeResp, _ := client.Nodes().GetOneNode(ctx, nodes[0].UUID.String())
        node := nodeResp.(*remapi.NodeResponse).Response
        fmt.Printf("\nNode details: %s\n", node.Name)
    }
}
```
Tokens:
Raw