English | فارسی | العربية | 中文 | Español | Русский | Türkçe

Terraform Provider for 3x-ui

Manage 3x-ui inbounds, clients, panel settings, and Xray configuration as code — backup, migrate, and scale your VPN/proxy fleet without clicking through the panel.

Why use it

Running 3x-ui in production means dozens of inbounds, hundreds of clients, and Xray configuration that is easy to break. With this provider you can:

• Treat configuration as code — your inbound list lives in git, every change is reviewed and versioned.
• Migrate between servers safely — restore the panel database to preserve IDs and secrets, then verify it with Terraform.
• Back up Terraform state — terraform state pull exports only Terraform-managed objects; pair it with a panel database backup for disaster recovery.
• Scale onboarding — add 100 clients in a single PR instead of 100 panel clicks.
• Plan before prod — terraform plan shows exactly what will change before anything ships.

Without vs with the provider

Quick Start

terraform {
  required_providers {
    threexui = {
      source = "batonogov/threexui"
    }
  }
}

provider "threexui" {
  endpoint = "http://localhost:2053"
  username = "admin"
  password = "admin"
}

resource "threexui_inbound" "vless" {
  remark   = "VLESS Reality"
  port     = 443
  protocol = "vless"

  vless_settings {
    decryption = "none"
  }

  stream_settings {
    network  = "tcp"
    security = "reality"
    reality_settings {
      target       = "www.amazon.com:443"
      server_names = ["www.amazon.com"]
    }
  }

  sniffing {
    enabled       = true
    dest_override = ["http", "tls", "quic", "fakedns"]
  }
}

resource "threexui_inbound_client" "client_a" {
  inbound_id = threexui_inbound.vless.id
  email      = "client-a@example.com"
  enable     = true
  flow       = "xtls-rprx-vision"
}

OpenTofu users: use the full registry address:

source = "registry.terraform.io/batonogov/threexui"

The provider is not available in the OpenTofu Registry (why).

Compatibility

Support policy: the provider officially supports every released patch across all supported 3x-ui minor lines — see the compatibility table below. The acceptance matrix exercises each version on every push to main and every pull request.

Newer protocol features are guarded with requireMinVersion and skip automatically on older versions, so the provider runs cleanly across the matrix without per-version forks.

Examples

Guides

In-repo walkthroughs for common operational scenarios:

• Backup-as-code — combine reviewed Terraform configuration with state and panel database backups.
• Migrating 3x-ui between servers — restore the panel database on a new VPS, then verify it with Terraform.
• Onboarding many clients at once — for_each patterns and CSV-driven onboarding.

Documentation

Full documentation is available on the Terraform Registry.

Resources

Data Sources

Security

The provider handles secrets the panel issues automatically (Reality privateKey, WireGuard secretKey, client UUIDs, Telegram bot tokens, LDAP passwords). All such fields are marked Sensitive and never logged in plaintext. See SECURITY.md for the full list and for guidance on protecting your Terraform state.

Development

Requirements

• Go (version pinned in go.mod)
• Task — task runner
• golangci-lint — linter
• pre-commit — git hooks framework
• Docker — for the local 3x-ui environment

Commands

task build        # Build the provider
task fmt          # Format code (gofmt)
task vet          # Run go vet
task lint         # Run golangci-lint
task pre-commit   # Run all checks manually (fmt, vet, lint, build)
task test:unit    # Run unit tests (no Docker / Terraform needed)
task test:acc     # Run acceptance tests (starts docker compose)
task test         # Run unit + acceptance tests

Local environment

# Start 3x-ui on localhost:2053
docker compose up -d

# Login: admin / admin

# Stop
docker compose down

Contributing

See CONTRIBUTING.md for local setup, testing, and submission guidelines. Bug reports, feature requests, and pull requests are all welcome — and so are notes about which 3x-ui versions you run in production.

Changelog

Releases follow Conventional Commits and are published automatically. See CHANGELOG.md for the full version history.

License

MIT