threexui-rs

An async Rust SDK for the 3x-ui panel API. Covers all API endpoints across inbounds, server management, settings, Xray configuration, and custom geo resources.

Version compatibility

2.9.4 is live-tested against both panel versions. The only behavioral difference: inbounds.copy_clients does not exist in v2.9.2 and returns Error::EndpointNotFound — match on it to fall back gracefully.

Installation

[dependencies]
threexui-rs = "2.9.5"
tokio = { version = "1", features = ["full"] }

Quick start

use threexui_rs::{Client, ClientConfig};

#[tokio::main]
async fn main() -> threexui_rs::Result<()> {
    let config = ClientConfig::builder()
        .host("192.168.1.1")
        .port(2053)
        .build()?;

    let client = Client::new(config);
    client.login("admin", "admin123").await?;

    let inbounds = client.inbounds().list().await?;
    println!("Found {} inbounds", inbounds.len());

    let status = client.server().status().await?;
    println!("Server CPU: {:.1}%  Xray: {}", status.cpu, status.xray.state);

    client.logout().await?;
    Ok(())
}

Configuration

let config = ClientConfig::builder()
    .host("example.com")
    .port(443)
    .base_path("/panel/")       // optional subpath prefix
    .tls(true)                  // use HTTPS
    .accept_invalid_certs(true) // for self-signed certs
    .timeout_secs(30)
    .build()?;

Outbound proxy (optional)

Route every request through an HTTP, HTTPS, or SOCKS5 proxy:

let config = ClientConfig::builder()
    .host("panel.example.com").port(2053)
    .proxy("socks5h://127.0.0.1:1080")   // also: http://, https://, socks5://
    .proxy_auth("username", "password")  // optional basic-auth
    .build()?;

• socks5:// resolves DNS locally, socks5h:// resolves it through the proxy.
• Bad proxy URLs surface as Error::Config at build() time.
• Use .no_proxy() on the builder to clear a previously set proxy.

Authentication

Standard login:

client.login("admin", "password").await?;

With two-factor authentication:

client.login_2fa("admin", "password", "123456").await?;

Check if 2FA is enabled on the panel:

let enabled = client.is_two_factor_enabled().await?;

API reference

All methods are async and return threexui_rs::Result<T>. The client is cheap to clone (Arc-backed) and safe to share across tasks.

Inbounds — client.inbounds()

Server — client.server()

Settings — client.settings()

Xray — client.xray()

Custom Geo — client.custom_geo()

Error handling

All fallible operations return threexui_rs::Result<T>, which is Result<T, threexui_rs::Error>:

use threexui_rs::Error;

match client.inbounds().list().await {
    Ok(inbounds) => { /* ... */ }
    Err(Error::NotAuthenticated) => eprintln!("call login() first"),
    Err(Error::Auth(msg)) => eprintln!("login failed: {}", msg),
    Err(Error::Api(msg)) => eprintln!("panel returned error: {}", msg),
    Err(Error::EndpointNotFound(path)) => eprintln!("endpoint missing on this panel: {}", path),
    Err(Error::Http(e)) => eprintln!("http error: {}", e),
    Err(e) => eprintln!("other error: {}", e),
}

Error::EndpointNotFound is returned when the panel responds with HTTP 404. This typically means the panel is older than the lib (e.g. calling inbounds.copy_clients on a v2.9.2 panel). Match on it to fall back.

Examples

See the examples/ directory:

• list_inbounds.rs — list all inbounds and print server status.
• add_client.rs — generate a UUID and add a new VLESS client.
• live_test.rs — full smoke test of every public API method.
• scenarios.rs — 16 production scenarios (multi-protocol create, renew, disable/enable, reset-uuid, data-limit, traffic resets, concurrent reads, special characters, negative paths…).
• proxy_test.rs — end-to-end verification of HTTP / SOCKS5 proxy support.

Run an example (requires a live panel):

cargo run --example list_inbounds
cargo run --example scenarios -- 127.0.0.1 2053 admin admin
cargo run --example proxy_test -- panel.example.com 2053 admin pw "socks5h://127.0.0.1:1080"

License

MIT — see LICENSE