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

Each release of threexui-rs targets the matching 3x-ui panel version. Use the same version number as your panel.

threexui-rs	3x-ui panel
2.9.3	v2.9.3

Installation

[dependencies]
threexui-rs = "2.9.3"
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()?;

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()`

Method	Description
`list()`	List all inbounds
`get(id)`	Get a single inbound by ID
`add(inbound)`	Create a new inbound
`update(id, inbound)`	Update an existing inbound
`delete(id)`	Delete an inbound
`import(inbound)`	Import an inbound from another panel
`add_client(inbound_id, clients)`	Add clients to an inbound
`update_client(client_id, inbound_id, client)`	Update a client
`delete_client(inbound_id, client_id)`	Delete a client by ID
`delete_client_by_email(inbound_id, email)`	Delete a client by email
`copy_clients(target_id, source_id, emails, flow)`	Copy clients between inbounds
`client_ips(email)`	Get IP list for a client
`clear_client_ips(email)`	Clear recorded IPs for a client
`client_traffics_by_email(email)`	Get traffic stats by email
`client_traffics_by_id(id)`	Get traffic stats by client ID
`reset_client_traffic(inbound_id, email)`	Reset traffic for a client
`reset_all_traffics()`	Reset traffic for all inbounds
`reset_all_client_traffics(inbound_id)`	Reset all client traffic in an inbound
`delete_depleted_clients(inbound_id)`	Remove clients that have exhausted their quota
`online_clients()`	List currently online client emails
`last_online()`	Map of email → last-seen timestamp
`update_client_traffic(email, upload, download)`	Manually adjust client traffic counters

Server — `client.server()`

Method	Description
`status()`	CPU, memory, disk, Xray state, network stats
`cpu_history(bucket)`	Historical CPU usage
`xray_versions()`	Available Xray versions to install
`config_json()`	Current Xray config as JSON
`download_db()`	Download the panel database as bytes
`import_db(data)`	Restore a panel database
`new_uuid()`	Generate a new UUID
`new_x25519_cert()`	Generate an X25519 keypair
`new_mldsa65()`	Generate ML-DSA-65 keys
`new_mlkem768()`	Generate ML-KEM-768 keys
`new_ech_cert(sni)`	Generate an ECH certificate
`new_vless_enc()`	Generate VLESS encryption keys
`stop_xray()`	Stop the Xray service
`restart_xray()`	Restart the Xray service
`install_xray(version)`	Install a specific Xray version
`update_geofile(filename)`	Update geo data files
`logs(count, level, syslog)`	Retrieve panel log lines
`xray_logs(count, filter, ...)`	Retrieve Xray log lines

Settings — `client.settings()`

Method	Description
`get_all()`	Get all panel settings
`get_defaults()`	Get default settings values
`update(settings)`	Save updated settings
`update_user(old_user, old_pass, new_user, new_pass)`	Change admin credentials
`restart_panel()`	Restart the panel process
`default_xray_config()`	Get the default Xray JSON config

Xray — `client.xray()`

Method	Description
`get_setting()`	Get current Xray settings
`update_setting(config, test_url)`	Update Xray settings
`default_config()`	Get default Xray config
`outbounds_traffic()`	Get per-outbound traffic stats
`reset_outbound_traffic(tag)`	Reset traffic counter for an outbound
`test_outbound(outbound, all_outbounds)`	Test an outbound configuration
`xray_result()`	Get latest Xray test result
`warp(action)`	Manage Cloudflare WARP integration
`nord(action)`	Manage NordVPN integration

Custom Geo — `client.custom_geo()`

Method	Description
`list()`	List all custom geo resources
`aliases()`	List resource aliases
`add(geo)`	Add a new geo resource
`update(id, geo)`	Update an existing geo resource
`delete(id)`	Delete a geo resource
`download(id)`	Trigger download for a geo resource
`update_all()`	Update all geo resources

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::Http(e)) => eprintln!("http error: {}", e),
    Err(e) => eprintln!("other error: {}", e),
}

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

Run an example (requires a live panel):

cargo run --example list_inbounds

License

MIT — see LICENSE

threexui-rs 2.9.3