### Start V2Ray Server with `v2ray run`

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Loads configuration files and starts the V2Ray server. Supports single or multiple config files, directories, and format overrides. Environment variables can also be used for configuration paths.

```bash
# Single config file (JSON)
v2ray run -c /etc/v2ray/config.json
```

```bash
# Multiple config files merged at startup
v2ray run -c base.json -c routing.json -c outbounds.json
```

```bash
# Load an entire directory of config fragments
v2ray run -d /etc/v2ray/conf.d
```

```bash
# Load a directory recursively
v2ray run -d /etc/v2ray/conf.d -r
```

```bash
# Explicit format override
v2ray run -c config.toml -format toml
```

```bash
# Use environment variables instead of flags
export v2ray.location.config=/etc/v2ray/config.json
export v2ray.location.confdir=/etc/v2ray/conf.d
v2ray run
```

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

### Minimal JSON Config Structure

Source: https://context7.com/v2fly/v2ray-core/llms.txt

A minimal V2Ray JSON configuration example demonstrating inbound (SOCKS5), outbound (direct), and API server setup.

```APIDOC
## Minimal JSON Config Structure

A complete, minimal V2Ray JSON config showing inbound (SOCKS5 on port 1080), outbound (direct), and API server with multiple services enabled.

```json
{
  "log": {
    "loglevel": "warning"
  },
  "api": {
    "tag": "api",
    "services": ["HandlerService", "LoggerService", "StatsService", "RoutingService"]
  },
  "stats": {},
  "policy": {
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true,
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "port": 1080,
      "listen": "127.0.0.1",
      "protocol": "socks",
      "settings": { "auth": "noauth", "udp": true }
    },
    {
      "tag": "api",
      "listen": "127.0.0.1",
      "port": 8080,
      "protocol": "dokodemo-door",
      "settings": { "address": "127.0.0.1" }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "block",
      "protocol": "blackhole"
    }
  ],
  "routing": {
    "rules": [
      { "inboundTag": ["api"], "outboundTag": "api", "type": "field" }
    ]
  }
}
```
```

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

### Validate V2Ray Config with `v2ray test`

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Parses and validates configuration files without starting the V2Ray server. Exits with a non-zero status and prints errors if the configuration is invalid. Supports single files, directories, and format overrides.

```bash
# Test a single config
v2ray test -c config.json
# Output: Configuration OK.
```

```bash
# Test a directory of configs
v2ray test -d /etc/v2ray/conf.d
```

```bash
# Test a TOML config
v2ray test -c config.toml -format toml
```

```bash
# Test multiple files
v2ray test -c base.json -c extra.json
# Output on error: Test failed: ...
```

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

### Get Balancer Information with v2ray api bi

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Retrieves health, strategy, and current selection of load balancers from a running V2Ray instance. Requires RoutingService. Supports querying all balancers, specific balancers, and JSON output.

```bash
# Get info for all balancers
v2ray api bi --server 127.0.0.1:8080
```

```bash
# Get info for specific balancer(s)
v2ray api bi --server 127.0.0.1:8080 myBalancer
```

```bash
# JSON output
v2ray api bi --json --server 127.0.0.1:8080 myBalancer
# Output:
#   - Selects:
#     1   proxy-us-1
#     2   proxy-us-2
```

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

### Minimal V2Ray JSON Configuration

Source: https://context7.com/v2fly/v2ray-core/llms.txt

A basic V2Ray JSON configuration structure. It includes settings for logging, API services, policy, inbound (SOCKS5), outbound (direct), and routing rules. This serves as a starting point for custom configurations.

```json
{
  "log": {
    "loglevel": "warning"
  },
  "api": {
    "tag": "api",
    "services": ["HandlerService", "LoggerService", "StatsService", "RoutingService"]
  },
  "stats": {},
  "policy": {
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true,
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "port": 1080,
      "listen": "127.0.0.1",
      "protocol": "socks",
      "settings": { "auth": "noauth", "udp": true }
    },
    {
      "tag": "api",
      "listen": "127.0.0.1",
      "port": 8080,
      "protocol": "dokodemo-door",
      "settings": { "address": "127.0.0.1" }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "block",
      "protocol": "blackhole"
    }
  ],
  "routing": {
    "rules": [
      { "inboundTag": ["api"], "outboundTag": "api", "type": "field" }
    ]
  }
}
```

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

### Print V2Ray Build Information with `v2ray version`

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Displays the build version, Go runtime version, OS/architecture, and other build-time metadata for the V2Ray executable.

```bash
v2ray version
# Example output:
# V2Ray 5.x.x (V2Fly, a community-driven edition of V2Ray.) custom (go1.21 linux/amd64)
# A unified platform for anti-censorship.
# ...
```

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

### Go API: core.New / server.Start / server.Close

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Embed V2Ray in Go Applications using the core package for programmatic control. Load configuration, create a server instance, and manage its lifecycle.

```APIDOC
## Go API: `core.New` / `server.Start` / `server.Close` — Embed V2Ray in Go Applications

The `core` package provides programmatic control. `core.LoadConfig` parses a config from a reader, `core.New` creates a server instance, and `server.Start`/`server.Close` manage its lifecycle.

### Example Usage

```go
package main

import (
    "os"

    core "github.com/v2fly/v2ray-core/v5"
    _ "github.com/v2fly/v2ray-core/v5/main/distro/all" // register all protocols
)

func main() {
    f, err := os.Open("config.json")
    if err != nil {
        panic(err)
    }
    defer f.Close()

    // Load and parse config (format "auto" detects JSON/TOML/YAML)
    config, err := core.LoadConfig("auto", f)
    if err != nil {
        panic("failed to load config: " + err.Error())
    }

    // Create server instance
    server, err := core.New(config)
    if err != nil {
        panic("failed to create server: " + err.Error())
    }

    // Start all features
    if err := server.Start(); err != nil {
        panic("failed to start: " + err.Error())
    }
    defer server.Close()

    // Server runs until Close() is called
    select {}
}
```
```

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

### Convert Config to Raw Protobuf with v2ray engineering convertpb

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Loads a config file and serializes it to raw protobuf binary format (stdout). Useful for embedding configs in binary pipelines or debugging serialization.

```bash
v2ray engineering convertpb
```

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

### CLI: v2ray engineering convertpb

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Converts configuration files from JSON format to binary protobuf format, or from a directory of configuration files.

```APIDOC
## CLI: `v2ray engineering convertpb`

Converts configuration files from JSON format to binary protobuf format, or from a directory of configuration files.

### Usage

```bash
# Convert a single config.json file to binary protobuf
v2ray engineering convertpb -c config.json > config.pb

# Convert all config files from a directory to binary protobuf
v2ray engineering convertpb -d /etc/v2ray/conf.d > config.pb
```
```

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

### Convert JSON config to binary protobuf

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Converts a JSON configuration file into a binary protobuf format. This is useful for optimizing configuration loading or for specific deployment scenarios.

```bash
v2ray engineering convertpb -c config.json > config.pb
```

```bash
v2ray engineering convertpb -d /etc/v2ray/conf.d > config.pb
```

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

### Embed V2Ray in Go Applications

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Demonstrates how to embed V2Ray Core into a Go application using the core API. Requires loading a configuration and managing the server lifecycle programmatically. Ensure all necessary protocols and transports are registered.

```go
package main

import (
    "os"

    core "github.com/v2fly/v2ray-core/v5"
    _ "github.com/v2fly/v2ray-core/v5/main/distro/all" // register all protocols
)

func main() {
    f, err := os.Open("config.json")
    if err != nil {
        panic(err)
    }
    defer f.Close()

    // Load and parse config (format "auto" detects JSON/TOML/YAML)
    config, err := core.LoadConfig("auto", f)
    if err != nil {
        panic("failed to load config: " + err.Error())
    }

    // Create server instance
    server, err := core.New(config)
    if err != nil {
        panic("failed to create server: " + err.Error())
    }

    // Start all features
    if err := server.Start(); err != nil {
        panic("failed to start: " + err.Error())
    }
    defer server.Close()

    // Server runs until Close() is called
    select {}
}
```

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

### Convert Config Formats with `v2ray convert`

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Merges one or more configuration files (local or remote) and converts the result to a different format (JSON, TOML, YAML, protobuf).

```bash
# Convert JSON config to YAML
v2ray convert -o yaml config.json
```

```bash
# Convert TOML to JSON (default output)
v2ray convert config.toml
```

```bash
# Merge two JSON configs and output as protobuf binary
v2ray convert -output protobuf c1.json c2.json > config.pb
```

```bash
# Merge all configs in a directory and output as YAML
v2ray convert -output yaml /etc/v2ray/conf.d
```

```bash
# Merge local and remote configs
v2ray convert c1.json https://example.com/extra.json
```

```bash
# Convert to jsonpb (protobuf JSON) format
v2ray convert -output jsonpb config.json
```

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

### Verify Binary Signature with `v2ray verify`

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Verifies that a V2Ray binary was officially signed by the V2Fly project using the VSign signature scheme. An exit code of 0 indicates a verified signature.

```bash
# Verify a downloaded binary against its .sig file
v2ray verify --sig v2ray.sig v2ray

# Exit code 0 = verified, non-zero = not officially signed
```

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

### CLI: v2ray engineering subscriptionEntriesExtract

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Parses a subscription file (e.g., a base64-encoded list of server links) and extracts each server entry into a ZIP archive written to stdout. Each entry is hashed for deduplication.

```APIDOC
## CLI: `v2ray engineering subscriptionEntriesExtract` — Extract Subscription Entries

Parses a subscription file (e.g., a base64-encoded list of server links) and extracts each server entry into a ZIP archive written to stdout. Each entry is hashed for deduplication.

### Usage

```bash
# Extract entries from a subscription file
v2ray engineering subscriptionEntriesExtract --input subscription.txt > entries.zip

# Or pipe from stdin
cat subscription.b64 | v2ray engineering subscriptionEntriesExtract > entries.zip

# Inspect the archive
unzip -l entries.zip
# Output:
# Archive:  entries.zip
#   Length      Date    Time    Name
# ---------  ---------- -----   ----
#        87  2024-01-01 00:00   meta.json
#       256  2024-01-01 00:00   entry_0_a1b2c3d4e5f6g7h8
#       ...
```
```

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

### Extract Subscription Entries

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Extracts individual server entries from a subscription file (e.g., base64-encoded links) into a ZIP archive. Each entry is hashed for deduplication. Can read from a file or stdin.

```bash
v2ray engineering subscriptionEntriesExtract --input subscription.txt > entries.zip
```

```bash
cat subscription.b64 | v2ray engineering subscriptionEntriesExtract > entries.zip
```

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

### Dynamically Add Inbounds/Outbounds with v2ray api adi/ado

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Dynamically adds inbound or outbound proxy handlers to a running V2Ray server without restart. Accepts configuration from JSON, TOML, or YAML files, or from a directory. Requires HandlerService.

```bash
# Add an inbound from a JSON config file
v2ray api adi --server 127.0.0.1:8080 new-inbound.json
# Output: adding: my-socks-inbound
```

```bash
# Add an outbound from a YAML config file
v2ray api ado --server 127.0.0.1:8080 new-outbound.yaml
# Output: adding: proxy-sg-1
```

```bash
# Add multiple handlers from a directory
v2ray api adi --server 127.0.0.1:8080 -r /etc/v2ray/inbounds.d
```

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

### Manage Runtime Logs with v2ray api log

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Streams live log messages from a running V2Ray instance via gRPC or restarts the logger. Requires LoggerService. Supports real-time streaming, filtering with grep, and restarting the logger.

```bash
# Follow logs in real time (pipe-friendly)
v2ray api log --server 127.0.0.1:8080
```

```bash
# Filter logs with grep
v2ray api log | grep "error"
```

```bash
# Restart the logger (e.g., after log rotation)
v2ray api log --restart --server 127.0.0.1:8080
```

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

### Query Runtime Statistics with v2ray api stats

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Queries traffic counters and system runtime statistics from a running V2Ray instance over gRPC. Requires StatsService to be enabled. Supports pattern matching, regex, resetting counters, and JSON output.

```bash
# Query all stats counters
v2ray api stats --server 127.0.0.1:8080
```

```bash
# Query by pattern (substring match)
v2ray api stats --server 127.0.0.1:8080 node1
```

```bash
# Query with regexp
v2ray api stats --regexp --server 127.0.0.1:8080 'node1.+downlink'
```

```bash
# Reset counters after reading
v2ray api stats --reset node1
```

```bash
# Get runtime system stats (goroutines, memory, GC)
v2ray api stats --runtime
# Output:
# Item                  Value
# 1   Up time               1h23m45s
# 2   Memory obtained       128.00 MiB
# 3   Number of goroutines  42
# ...
```

```bash
# JSON output
v2ray api stats --json node1
# Output: {"stat": [{"name": "outbound>>>node1>>>traffic>>>downlink", "value": "1048576"}]}
```

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

### Generate TLS Certificates with `v2ray tls cert`

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Generates self-signed TLS certificates, optionally as a Certificate Authority (CA). Output can be PEM files or a JSON object suitable for V2Ray configuration.

```bash
# Generate a certificate for a domain (JSON output by default)
v2ray tls cert --domain example.com
# Output:
# {
#   "certificate": ["-----BEGIN CERTIFICATE-----", ...],
#   "key": ["-----BEGIN RSA PRIVATE KEY-----", ...]
# }
```

```bash
# Generate a CA certificate
v2ray tls cert --ca --domain myca.internal --expire 3650
```

```bash
# Save PEM files to disk
v2ray tls cert --domain example.com --file /etc/v2ray/tls/server
# Creates: /etc/v2ray/tls/server_cert.pem and server_key.pem
```

```bash
# Multiple SANs
v2ray tls cert --domain example.com --domain www.example.com --org "My Org"
```

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

### Override Balancer Selection with v2ray api bo

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Forces a load balancer to always select a specific outbound tag, overriding its normal strategy. Useful for manual failover or maintenance routing. Requires RoutingService. Can also remove overrides.

```bash
# Override balancer "lb1" to always use "proxy-backup"
v2ray api bo --server 127.0.0.1:8080 -b lb1 proxy-backup
```

```bash
# Remove the override (restore normal strategy)
v2ray api bo --server 127.0.0.1:8080 -b lb1 --remove
```

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

### Compute Certificate Chain Hash with v2ray tls certChainHash

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Computes the SHA-256 hash of a PEM certificate chain, which is used for V2Ray TLS pinning configuration. It can read from a specified PEM file or use the default cert.pem in the current directory.

```bash
# Compute hash from a PEM file
v2ray tls certChainHash --cert /etc/ssl/certs/server_cert.pem
# Output: <base64-encoded SHA-256 hash>
```

```bash
# Use with default cert.pem in current directory
v2ray tls certChainHash
```

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

### Generate UUID with `v2ray uuid`

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Generates a new random UUID, suitable for use as a user ID in protocols like VMess and VLESS.

```bash
v2ray uuid
# Output: 2d9a4d21-7a3b-4e56-9e5d-1c3e3b2f1234
```

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

### Test TLS Handshake with v2ray tls ping

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Performs a TLS handshake against a domain to diagnose TLS configurations and SNI routing. It can resolve IPs automatically or use a manually specified IP. The output shows allowed DNS names from the peer certificate.

```bash
# Ping a domain (resolves IP automatically)
v2ray tls ping example.com
# Output:
# Tls ping:  example.com
# Using IP:  93.184.216.34
# -------------------
# Pinging without SNI
# Handshake succeeded
# Allowed domains: [example.com www.example.com]
# -------------------
# Pinging with SNI
# handshake succeeded
# Allowed domains: [example.com www.example.com]
```

```bash
# Specify IP manually (bypass DNS)
v2ray tls ping -ip 93.184.216.34 example.com
```

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

### Dynamically Remove Inbounds/Outbounds with v2ray api rmi/rmo

Source: https://context7.com/v2fly/v2ray-core/llms.txt

Dynamically removes inbound or outbound proxy handlers from a running V2Ray server. Can remove by config file or directly by tag name. Requires HandlerService.

```bash
# Remove inbound(s) described by a config file
v2ray api rmi --server 127.0.0.1:8080 old-inbound.json
```

```bash
# Remove inbound(s) by tag directly
v2ray api rmi --server 127.0.0.1:8080 --tags socks-inbound http-inbound
```

```bash
# Remove outbound by tag
v2ray api rmo --server 127.0.0.1:8080 --tags proxy-old-1
# Output: removing: proxy-old-1
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.