Importing

xrat imports proxy configurations from multiple sources and formats, automatically detecting the input type and normalizing all configs into a unified internal representation.

Input Sources

Subscription URL

Fetch configs from a remote HTTP endpoint:

xrat import https://example.com/subscription

xrat:

Fetches the URL content
Parses subscription-userinfo headers for metadata (upload, download, total, expire)
Detects format (base64, plain list, JSON)
Parses and normalizes each node
Persists to database with subscription tracking

Local File

Import from a file on disk:

xrat import ./nodes.txt

Supports the same format detection as URLs.

Raw Text

Import inline subscription text:

xrat import "vless://uuid@example.com:443?type=ws#Node"

Useful for quick imports or scripting.

Input Formats

A single proxy URI:

vless://uuid-123@example.com:443?type=ws&security=tls&sni=cdn.example.com&path=%2Fray#My%20Node

Supported schemes:

vless://
vmess://
ss://
trojan://
http:// / https://
socks5://
hysteria2:// / hy2://

Base64 Subscription

Standard v2rayN/Clash subscription format:

dmxlc3M6Ly91dWlkQGV4YW1wbGUuY29tOjQ0Mz90eXBlPXdzJnNlY3VyaXR5PXRscyNNeSBOb2RlCnZtZXNzOi8v...

xrat:

Base64-decodes the payload
Splits into lines
Parses each line as a share link

Plain Link List

Multiple share links, one per line:

vless://uuid-1@example.com:443?type=tcp#Node1
vmess://eyJhZGQiOiJleGFtcGxlLmNvbSIsInBvcnQiOiI0NDMifQ==#Node2
ss://YWVzLTI1Ni1nY206c2VjcmV0@example.com:8388#Node3

Lines starting with # are treated as comments and skipped.

SIP008 JSON

Shadowsocks SIP008 format:

{
  "version": 1,
  "servers": [
    {
      "server": "example.com",
      "server_port": 8388,
      "method": "aes-256-gcm",
      "password": "secret",
      "remarks": "My SS Node"
    }
  ]
}

Xray JSON

Full Xray configuration:

{
  "inbounds": [...],
  "outbounds": [
    {
      "protocol": "vless",
      "settings": {
        "vnext": [...]
      }
    }
  ]
}

xrat extracts outbound configs and converts them to internal nodes.

Format Detection

xrat automatically detects the input format using heuristics:

Condition	Detected Format
Starts with `{` and contains `"version"` or `"inbounds"`	Xray JSON
Starts with `{` and contains `"servers"`	SIP008 JSON
Single line starting with a protocol scheme	Single share link
Multiple lines, first line starts with protocol scheme	Plain link list
Otherwise	Base64 subscription

Normalization

After parsing, xrat normalizes each node:

Network defaults: Empty network → tcp
WebSocket defaults: Missing host → copy from sni, missing path → /
gRPC defaults: Missing path → /
TLS cleanup: Empty string tls → None

Deduplication

Before persisting, xrat generates a dedup key for each node and skips duplicates. See Deduplication for details.

Subscription Tracking

Each import creates or updates a subscriptions record:

Field	Description
`source_url`	Original URL or file path
`source_kind`	`url`, `file`, or `raw_text`
`name`	Optional name (from URL or user-provided)
`created_at`	First import timestamp
`updated_at`	Latest import timestamp

Configs are linked to their subscription via subscription_id foreign key.

Metadata Extraction

For subscription URLs, xrat extracts metadata from HTTP headers:

subscription-userinfo: upload=1024; download=2048; total=10240; expire=1234567890

Parsed fields:

upload — bytes uploaded
download — bytes downloaded
total — total quota
expire — expiration timestamp (Unix epoch)

Error Handling

xrat continues parsing even when individual lines fail:

Import Summary
─────────────────────────────────
Source:     https://example.com/sub.txt
Parsed:     45 nodes
Failed:     3 lines
Duplicates: 12 skipped
New:        33 configs added

Failed lines are logged with line numbers and error messages.

import CLI — command reference
Deduplication — how duplicates are detected
Protocols — supported protocol formats

Keyboard shortcuts