3x-ui

https://docs.sanaei.dev
Admin
3x-ui is an open-source web control panel for deploying and managing Xray-core servers, proxy...
Tokens:125,534
Snippets:784
Trust Score:2.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install latest stable version

Source: https://docs.sanaei.dev/docs/guide/installation

Run the official script installer as root or with sudo. It generates random credentials, sets up the service, and installs the x-ui management command.

```bash
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
```

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

### GET /panel/api/server/getXrayVersion

Source: https://docs.sanaei.dev/docs/reference/api/server

Lists Xray binary versions available for installation on the host.

```APIDOC
## GET /panel/api/server/getXrayVersion

### Description
Lists Xray binary versions available for installation on the host.

### Method
GET

### Endpoint
`/panel/api/server/getXrayVersion`

### Authorization
`bearerAuth` - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>` in the header.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **obj** (array of strings) - List of available Xray versions.

#### Response Example
```json
{
  "success": true,
  "obj": [
    "v25.10.31",
    "v25.9.15",
    "v25.8.1"
  ]
}
```
```

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

### Response body for GET /panel/api/server/getNewX25519Cert

Source: https://docs.sanaei.dev/docs/reference/api/server

Example 200 response containing the generated private and public keys.

```json
{
  "success": true,
  "obj": {
    "privateKey": "uN9qLfV3zH8w...",
    "publicKey": "5v8xPqR2sM7k..."
  }
}
```

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

### Start Docker with PostgreSQL profile

Source: https://docs.sanaei.dev/docs/reference/database

Command to start 3x-ui with the bundled PostgreSQL service. Uncomment the two XUI_DB_* lines in docker-compose.yml and use the postgres profile.

```bash
docker compose --profile postgres up -d
```

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

### GET getWebCertFiles - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/server

Example successful response for the getWebCertFiles endpoint, showing certificate and key file paths.

```json
{
  "success": true,
  "obj": {
    "webCertFile": "/root/cert/example.com/fullchain.pem",
    "webKeyFile": "/root/cert/example.com/privkey.pem"
  }
}
```

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

### Install rolling dev build

Source: https://docs.sanaei.dev/docs/guide/installation

Pass dev-latest to install the latest per-commit pre-release from main, not a stable release.

```bash
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
```

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

### JSON subscription URL example

Source: https://docs.sanaei.dev/docs/config/subscription

An example of a generated JSON subscription URL.

```text
https://sub.example.com:2096/your-json-path/user-1
```

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

### Unattended install with XUI_NONINTERACTIVE

Source: https://docs.sanaei.dev/docs/guide/installation

Set XUI_NONINTERACTIVE=1 to run the installer non-interactively with zero prompts. It generates random credentials and writes them to /etc/x-ui/install-result.env.

```bash
XUI_NONINTERACTIVE=1 bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
```

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

### GET getXrayVersion - cURL request

Source: https://docs.sanaei.dev/docs/reference/api/server

Lists Xray binary versions available for install on the host. Requires a bearer token in the Authorization header.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/server/getXrayVersion" \
  -H "Authorization: Bearer "
```

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

### POST /panel/api/setting/defaultSettings - Get computed default settings

Source: https://docs.sanaei.dev/docs/reference/api/settings

Returns the computed default settings based on the request host, useful to preview what a fresh install would use. Requires a logged-in session or Bearer token. The response body is shown for a 200 status.

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/setting/defaultSettings" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

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

### Base64 subscription URL example

Source: https://docs.sanaei.dev/docs/config/subscription

An example of a generated Base64 subscription URL.

```text
https://sub.example.com:2096/your-sub-path/user-1
```

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

### Install Xray Version (cURL)

Source: https://docs.sanaei.dev/docs/reference/api/server

Sends a POST request to download and install a specified Xray version. The version path parameter accepts a tag like v25.10.31 or "latest". Requires an Authorization header with a bearer token.

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/server/installXray/string" \
  -H "Authorization: Bearer "
```

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

### Install pinned version v3.4.0

Source: https://docs.sanaei.dev/docs/guide/installation

Append a version tag to the install command to install a specific version.

```bash
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0
```

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

### Install and issue certificate with Certbot standalone

Source: https://docs.sanaei.dev/docs/config/ssl-certificates

Install Certbot and issue a standalone certificate for yourdomain.com. Requires port 80 free and the domain resolving to the server. The dry-run renewal verifies the renewal process.

```bash
apt-get install certbot -y
certbot certonly --standalone --agree-tos --register-unsafely-without-email -d yourdomain.com
certbot renew --dry-run
```

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

### GET getNewUUID - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/server

Example successful response for the getNewUUID endpoint, containing a sample UUID.

```json
{
  "success": true,
  "obj": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

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

### POST /panel/api/server/installXray/{version}

Source: https://docs.sanaei.dev/docs/reference/api/server

Downloads and installs the specified Xray version. Pass "latest" for the newest release. Requires bearer token authentication.

```APIDOC
## POST /panel/api/server/installXray/{version}

### Description
Downloads and installs the specified Xray version. Pass "latest" for the newest release.

### Method
POST

### Endpoint
/panel/api/server/installXray/{version}

### Parameters
#### Path Parameters
- **version** (string) - Required - Xray tag (e.g. v25.10.31) or "latest".

#### Authorization
- **Authorization** (header) - Required - Bearer token. API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **msg** (string) - Message describing the result.
- **obj** (null) - Additional data (null in this case).

#### Response Example
```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

### Request Example
```bash
curl -X POST "https://docs.sanaei.dev/panel/api/server/installXray/string" \
  -H "Authorization: Bearer "
```
```

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

### Credential summary file /etc/x-ui/install-result.env

Source: https://docs.sanaei.dev/docs/guide/first-login

A script install writes the generated credentials to this root-only file (mode 600). Contains username, password, panel port, web base path, access URL, API token, and DB type.

```text
XUI_USERNAME=...
XUI_PASSWORD=...
XUI_PANEL_PORT=...
XUI_WEB_BASE_PATH=...
XUI_ACCESS_URL=...
XUI_API_TOKEN=...
XUI_DB_TYPE=sqlite
```

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

### Response body for GET /panel/api/server/descendants

Source: https://docs.sanaei.dev/docs/reference/api/server

Example 200 response showing a successful retrieval with an array of node summaries.

```json
{
  "success": true,
  "obj": [
    {
      "guid": "c3d4-...",
      "parentGuid": "a1b2-...",
      "name": "Node3",
      "address": "10.0.0.3",
      "status": "online"
    }
  ]
}
```

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

### PostgreSQL environment configuration in /etc/default/x-ui

Source: https://docs.sanaei.dev/docs/reference/database

Environment variables that select the PostgreSQL backend at runtime. The installer writes these to /etc/default/x-ui. Tune the connection pool with XUI_DB_MAX_OPEN_CONNS and XUI_DB_MAX_IDLE_CONNS.

```bash
XUI_DB_TYPE=postgres
XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable
```

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

### Response: Get last N lines of panel log

Source: https://docs.sanaei.dev/docs/reference/api/server

Example 200 response for the logs endpoint, showing an array of log lines.

```json
{
  "success": true,
  "obj": [
    "2025/01/01 12:00:00 [INFO] Server started",
    "2025/01/01 12:00:01 [INFO] Xray is running"
  ]
}
```

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

### POST /panel/api/setting/all - Return all panel settings

Source: https://docs.sanaei.dev/docs/reference/api/settings

Returns every panel setting (web server, Telegram bot, subscription, security, LDAP) as a JSON blob. Requires a logged-in session or Bearer token. The response body is shown for a 200 status.

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/setting/all" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

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

### GET getXrayVersion - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/server

Example successful response for the getXrayVersion endpoint. The response includes a success flag and an array of version strings.

```json
{
  "success": true,
  "obj": [
    "v25.10.31",
    "v25.9.15",
    "v25.8.1"
  ]
}
```

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

### POST /panel/api/server/setUpdateChannel

Source: https://docs.sanaei.dev/docs/reference/api/server

Toggles the panel update channel between stable and the rolling per-commit dev release.

```APIDOC
## POST /panel/api/server/setUpdateChannel

### Description
Toggle the panel update channel between stable and the rolling per-commit dev release. Only effective on dev builds.

### Method
POST

### Endpoint
/panel/api/server/setUpdateChannel

### Parameters
#### Request Body
- **dev** (boolean) - Required - true = dev channel, false = stable.

### Request Example
dev=true

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Status message.
- **obj** (null) - Null object.

#### Response Example
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

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

### AmneziaWG client .conf example

Source: https://docs.sanaei.dev/docs/config/amneziawg

Client configuration file for AmneziaWG, used as the downloadable .conf and encoded in the vpn:// share link. Contains interface settings (private key, address, DNS, obfuscation parameters) and a peer section with server public key, allowed IPs, endpoint, and keepalive.

```ini
[Interface]
PrivateKey = <client private key>
Address = 10.8.1.2/32
DNS = 8.8.8.8, 8.8.4.4
Jc = 4
Jmin = 65
Jmax = 220
S1 = 87
S2 = 44
S3 = 21
S4 = 9
H1 = 463065432
H2 = 912345678
H3 = 1345678901
H4 = 1987654321
I1 = <r 148>
HeaderProtectionKey = 8Iu83eHDA3fMKKSGaEsVW9Ycd2lYYzc0MYlk1jJTvE4=
ContentPaddingAddition = 17-49
RekeyAfterTime = 111-139
RekeyTimeout = 4-7
RejectAfterTime = 187-251
KeepaliveTimeout = 9-14
MaxHandshakeAttempts = 19-36
RandomTrailers = on
DisableCookies = on

# my-client
[Peer]
PublicKey = <server public key>
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = your-server:443
PersistentKeepalive = 25
```

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

### GET /panel/api/hosts/tags - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/hosts

Example successful response for the tags endpoint. Shows the structure with a success flag and an array of tag strings.

```json
{
  "success": true,
  "obj": [
    "CDN",
    "EU",
    "FAST"
  ]
}
```

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

### GET /panel/api/server/fail2banStatus

Source: https://docs.sanaei.dev/docs/reference/api/server

Reports whether per-client IP limits can be enforced on this host. The panel uses it to gate the 'IP Limit' field, since enforcement depends on Fail2ban being installed.

```APIDOC
## GET /panel/api/server/fail2banStatus

### Description
Reports whether per-client IP limits can be enforced on this host. The panel uses it to gate the "IP Limit" field, since enforcement depends on Fail2ban being installed.

### Method
GET

### Endpoint
/panel/api/server/fail2banStatus

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **obj** (object) - Contains status details.
  - **enabled** (boolean) - Whether Fail2ban is enabled.
  - **installed** (boolean) - Whether Fail2ban is installed.
  - **usable** (boolean) - Whether Fail2ban is usable.
  - **windows** (boolean) - Whether the host is running Windows.

### Response Example
{
  "success": true,
  "obj": {
    "enabled": true,
    "installed": true,
    "usable": true,
    "windows": false
  }
}
```

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

### 200 Response for GET /panel/api/hosts/list

Source: https://docs.sanaei.dev/docs/reference/api/hosts

Example 200 response body for the list hosts endpoint. Shows the full host object structure with fields such as allowInsecure, alpn, inboundIds, and security.

```json
{
  "success": true,
  "obj": [
    {
      "allowInsecure": false,
      "alpn": [
        ""
      ],
      "echConfigList": "",
      "excludeFromSubTypes": [
        ""
      ],
      "finalMask": "",
      "fingerprint": "",
      "groupId": "",
      "hostHeader": "",
      "hosts": [
        ""
      ],
      "inboundIds": [
        0
      ],
      "isDisabled": false,
      "isHidden": false,
      "keepSniBlank": false,
      "mihomoIpVersion": "dual",
      "mihomoX25519": false,
      "muxParams": "",
      "nodeGuids": [
        ""
      ],
      "overrideSniFromAddress": false,
      "path": "",
      "pinnedPeerCertSha256": [
        ""
      ],
      "port": 0,
      "remark": "",
      "security": "same",
      "serverDescription": "",
      "shuffleHost": false,
      "sni": "",
      "sockoptParams": "",
      "sortOrder": 0,
      "tags": [
        ""
      ],
      "verifyPeerCertByName": "",
      "vlessRoute": ""
    }
  ]
}
```

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

### POST /panel/api/setting/all

Source: https://docs.sanaei.dev/docs/reference/api/settings

Returns every panel setting: web server, Telegram bot, subscription, security, LDAP. The full JSON blob that the Settings page edits.

```APIDOC
## POST /panel/api/setting/all

### Description
Returns every panel setting: web server, Telegram bot, subscription, security, LDAP. The full JSON blob that the Settings page edits.

### Method
POST

### Endpoint
/panel/api/setting/all

### Parameters
#### Authorization
- **bearerAuth** (header) - Required - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.

### Request Example
```
curl -X POST "https://docs.sanaei.dev/panel/api/setting/all" \
  -H "Authorization: Bearer "
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Response message.
- **obj** (null) - Response object (null in this case).

#### Response Example
```
{
  "success": true,
  "msg": "string",
  "obj": null
}
```
```

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

### GET /panel/api/server/fail2banStatus with cURL and 200 response

Source: https://docs.sanaei.dev/docs/reference/api/server

Checks whether per-client IP limits can be enforced on this host. The panel uses this endpoint to gate the "IP Limit" field, since enforcement depends on Fail2ban being installed. The response indicates whether Fail2ban is enabled, installed, usable, and whether the host is Windows.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/server/fail2banStatus" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "obj": {
    "enabled": true,
    "installed": true,
    "usable": true,
    "windows": false
  }
}
```

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

### View current settings with x-ui menu

Source: https://docs.sanaei.dev/docs/guide/first-login

Use the x-ui menu to view current settings (menu option 11) or the one-shot form. Useful if you missed the credential summary.

```bash
x-ui              # menu → 11 (View Current Settings)
x-ui settings     # or the one-shot form
```

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

### cURL request to GET /panel/api/server/descendants

Source: https://docs.sanaei.dev/docs/reference/api/server

Retrieves read-only summaries (guid, parentGuid, name, address, status, versions) of descendant nodes. Requires an API token sent as Authorization: Bearer <token>.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/server/descendants" \
  -H "Authorization: Bearer "
```

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

### List all subscription balancers - 200 response

Source: https://docs.sanaei.dev/docs/reference/api/subscription-balancers

Example 200 response for the GET /panel/api/sub-balancers endpoint, showing a balancer object with fields like createdAt, enabled, id, inboundIds, memberWeights, remark, sortOrder, strategy, and updatedAt.

```json
{
  "success": true,
  "obj": [
    {
      "createdAt": 1710000000000,
      "enabled": true,
      "id": 1,
      "inboundIds": [
        1,
        3
      ],
      "memberWeights": {},
      "remark": "auto-fastest",
      "sortOrder": 1,
      "strategy": "random",
      "updatedAt": 1710000000000
    }
  ]
}
```

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

### Response for fetching host group by group ID

Source: https://docs.sanaei.dev/docs/reference/api/hosts

Example 200 response body for the GET /panel/api/hosts/get/{groupId} endpoint. Shows the structure of a host group object with fields like allowInsecure, alpn, hosts, inboundIds, and security.

```json
{
  "success": true,
  "obj": {
    "allowInsecure": false,
    "alpn": [
      ""
    ],
    "echConfigList": "",
    "excludeFromSubTypes": [
      ""
    ],
    "finalMask": "",
    "fingerprint": "",
    "groupId": "",
    "hostHeader": "",
    "hosts": [
      ""
    ],
    "inboundIds": [
      0
    ],
    "isDisabled": false,
    "isHidden": false,
    "keepSniBlank": false,
    "mihomoIpVersion": "dual",
    "mihomoX25519": false,
    "muxParams": "",
    "nodeGuids": [
      ""
    ],
    "overrideSniFromAddress": false,
    "path": "",
    "pinnedPeerCertSha256": [
      ""
    ],
    "port": 0,
    "remark": "",
    "security": "same",
    "serverDescription": "",
    "shuffleHost": false,
    "sni": "",
    "sockoptParams": "",
    "sortOrder": 0,
    "tags": [
      ""
    ],
    "verifyPeerCertByName": "",
    "vlessRoute": ""
  }
}
```

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

### GET /panel/api/inbounds/allLinks - Export all inbound links

Source: https://docs.sanaei.dev/docs/reference/api/inbounds

Returns every protocol URL (vless://, vmess://, trojan://, ss://, hysteria://, mtproto) across all inbounds and clients. Links are rendered through the subscription engine, applying the configured remark template per client. Protocols without a URL form (socks, http, mixed, wireguard, dokodemo, tunnel) contribute nothing.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/inbounds/allLinks" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "obj": [
    "vless://uuid@host:443?security=reality&...#Germany-alice",
    "vmess://eyJ2IjoyLC..."
  ]
}
```

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

### POST /panel/api/setting/defaultSettings

Source: https://docs.sanaei.dev/docs/reference/api/settings

Returns the computed default settings based on the request host. Useful to preview what a fresh install would use.

```APIDOC
## POST /panel/api/setting/defaultSettings

### Description
Returns the computed default settings based on the request host. Useful to preview what a fresh install would use.

### Method
POST

### Endpoint
/panel/api/setting/defaultSettings

### Parameters
#### Authorization
- **bearerAuth** (header) - Required - API token from Settings → Security → API Token. Send as `Authorization: Bearer <token>`.

### Request Example
```
curl -X POST "https://docs.sanaei.dev/panel/api/setting/defaultSettings" \
  -H "Authorization: Bearer "
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **msg** (string) - Response message.
- **obj** (null) - Response object (null in this case).

#### Response Example
```
{
  "success": true,
  "msg": "string",
  "obj": null
}
```
```

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

### Run the x-ui interactive menu

Source: https://docs.sanaei.dev/docs/guide/update-uninstall

Run the x-ui command with no arguments to open the interactive management menu. This is the control center after a script install.

```bash
x-ui
```

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

### Client vless:// share link excerpt

Source: https://docs.sanaei.dev/docs/config/reality

Shows the client share link carrying public parameters: pbk (public key), sid, sni, fp, spx, and flow. The flow must be xtls-rprx-vision on both server and client.

```text
vless://<uuid>@<server>:443?security=reality&pbk=<public-key>&sid=<short-id>&sni=www.microsoft.com&fp=chrome&spx=%2F&flow=xtls-rprx-vision#my-reality
```

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

### GET /panel/api/xray/outbound-subs with cURL

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to list outbound subscriptions. The response is a JSON object with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/outbound-subs" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

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

### GET /panel/api/xray/geodata/files with cURL

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to list geo database files. The response is a JSON object with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/geodata/files" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```

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

### Create a subscription balancer (POST /panel/api/sub-balancers) - cURL

Source: https://docs.sanaei.dev/docs/reference/api/subscription-balancers

Sends a POST request to create a subscription balancer. Requires an API token and uses application/x-www-form-urlencoded content type. The request body must include remark and inboundIds (at least one). Optional fields include strategy (default "random"), memberWeights (leastLoad only), sortOrder (default 1), and enabled (default true on create).

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/sub-balancers" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'remark=string&inboundIds=0'
```

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

### GET /panel/api/xray/getDefaultJsonConfig - cURL request

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to retrieve the built-in default Xray config. Requires a bearer token in the Authorization header.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/getDefaultJsonConfig" \
  -H "Authorization: Bearer "
```

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

### cURL: Get Xray process output

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to /panel/api/xray/getXrayResult with bearer token authorization. Returns JSON with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/getXrayResult" \
  -H "Authorization: Bearer "
```

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

### cURL: Get outbound traffic statistics

Source: https://docs.sanaei.dev/docs/reference/api/xray-settings

Sends a GET request to /panel/api/xray/getOutboundsTraffic with bearer token authorization. Returns JSON with success, msg, and obj fields.

```bash
curl -X GET "https://docs.sanaei.dev/panel/api/xray/getOutboundsTraffic" \
  -H "Authorization: Bearer "
```

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

### Restart panel via POST /panel/api/setting/restartPanel

Source: https://docs.sanaei.dev/docs/reference/api/settings

Restarts the entire 3x-ui process after a 3-second grace period. The connection drops immediately; the panel comes back online ~5-10 seconds later.

```bash
curl -X POST "https://docs.sanaei.dev/panel/api/setting/restartPanel" \
  -H "Authorization: Bearer "
```

```json
{
  "success": true,
  "msg": "string",
  "obj": null
}
```
Tokens:
Raw