### YAML Configuration Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

A basic example of a GOST service configuration in YAML format.

```yaml
services:
- name: service-0
  addr: ":8080"
```

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

### JSON Configuration Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

A basic example of a GOST service configuration in JSON format.

```json
{
  "services": [
    {
      "name": "service-0",
      "addr": ":8080"
    }
  ]
}
```

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

### Select GOST Version for Installation

Source: https://github.com/go-gost/gost/blob/master/README.md

Allows selection of a specific version of GOST to install using the installation script. Run the script to be prompted for version selection.

```bash
bash <(curl -fsSL https://github.com/go-gost/gost/raw/master/install.sh)
```

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

### Start API Service

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Starts an API service on the specified address for dynamic configuration.

```bash
gost -api :18080
```

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

### Multi-Worker Mode Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Example demonstrating spawning three workers: an HTTP proxy, a SOCKS5 proxy, and a worker using a configuration file. If any worker exits with a non-zero code, all workers are terminated.

```bash
gost -L "http://:8080" -- -L "socks5://:1080" -- -C config.yaml
```

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

### Install GOST using install script

Source: https://github.com/go-gost/gost/blob/master/README_en.md

Installs the latest version of GOST from GitHub releases using a curl and bash command. Alternatively, running the script without arguments prompts for version selection.

```bash
bash <(curl -fsSL https://github.com/go-gost/gost/raw/master/install.sh) --install
```

```bash
bash <(curl -fsSL https://github.com/go-gost/gost/raw/master/install.sh)
```

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

### Inline Service Definition Examples

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Examples of how to define services using the inline format, including protocol, authentication, address, and parameters.

```text
http://:8080
```

```text
socks5://username:password@127.0.0.1:1080
```

```text
https://user:pass@example.com:8443?caFile=/path/to/ca.pem&secure=true
```

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

### Get Configuration cURL Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Use this cURL command to retrieve the current service configuration.

```bash
curl http://localhost:18080/config
```

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

### Inline Node Definition Examples

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Examples of how to define nodes using the inline format, specifying protocol, authentication, address, and parameters.

```text
socks5://:1080
```

```text
http://proxy.example.com:8080
```

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

### GOST Address Format Examples

Source: https://github.com/go-gost/gost/blob/master/_autodocs/types-and-protocols.md

Examples demonstrating the GOST address format, which includes protocol, authentication, host, port, and optional parameters.

```go
tcp://example.com:1080
```

```go
tls://proxy.example.com:443?serverName=proxy.example.com&secure=true
```

```go
http://user:pass@proxy.example.com:8080
```

```go
ws://127.0.0.1:8080?path=/ws
```

```go
socks5://proxy.example.com:1080
```

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

### Minimal Configuration File Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

A basic YAML configuration for a single HTTP service listening on TCP port 8080.

```yaml
services:
- name: http-proxy
  addr: ":8080"
  handler:
    type: http
  listener:
    type: tcp
```

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

### Install Latest GOST Version

Source: https://github.com/go-gost/gost/blob/master/README.md

Installs the latest version of GOST using the provided installation script. Ensure you have curl installed.

```bash
bash <(curl -fsSL https://github.com/go-gost/gost/raw/master/install.sh) --install
```

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

### Connector Configuration Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Defines the protocol and authentication for connecting to upstream proxies.

```yaml
connector:
  type: socks5 | http | ss | tunnel | relay | direct
  auth:
    username: string
    password: string
  metadata:
    key: value
```

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

### Start Metrics Service

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Starts a Prometheus metrics service on the specified address, exposing metrics at /metrics.

```bash
gost -metrics :9000
```

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

### Dialer Stacking Example with Specific Connectors/Dialers

Source: https://github.com/go-gost/gost/blob/master/_autodocs/execution-model.md

Provides a concrete example of a dialer stack, showing the sequence of Handler, Connector, and Dialers, and highlighting associated configurations like SNI and CA certificates.

```plaintext
HTTP Handler → SOCKS5 Connector → TLS Dialer → TCP Dialer → Network
                                        ↑
                                    SNI hostname, CA certificate
```

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

### Dialer Configuration Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Specifies how to establish the actual network connection, including transport type and TLS settings.

```yaml
dialer:
  type: tcp | tls | ws | kcp | quic | grpc | ssh | etc.
  auth:
    username: string
    password: string
  tls:
    caFile: string
    secure: bool
    serverName: string
    certFile: string
    keyFile: string
  metadata:
    key: value
```

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

### Error Response Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

An example of an error response, indicating a service was not found.

```json
{
  "error": "service 'http-proxy' not found",
  "code": "NOT_FOUND"
}
```

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

### Inline Authentication Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Provides username and password directly within the configuration.

```yaml
auth:
  username: user1
  password: pass1
```

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

### List Services with Authentication cURL Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Use this cURL command to list services when authentication is enabled. Provide username and password using the -u flag.

```bash
curl -u "admin:password" http://localhost:18080/services
```

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

### Setup Transparent Proxy Prerequisites (Linux)

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Commands to enable IP forwarding and set up iptables rules for transparent proxying on Linux. Requires root privileges.

```bash
# Must run as root
# Enable IP forwarding
echo 1 > /proc/sys/net/ipv4/ip_forward

# Create iptables rules (example for traffic to 8.8.8.8:53)
sudo iptables -t nat -A OUTPUT -d 8.8.8.8/32 -p tcp --dport 53 -j REDIRECT --to-ports 12345
sudo iptables -t nat -A OUTPUT -d 8.8.8.8/32 -p udp --dport 53 -j REDIRECT --to-ports 12345
```

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

### Start SOCKS5 Proxy on Custom Port

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Launches a SOCKS5 proxy listening on port 1080.

```bash
gost -L "socks5://:1080"
```

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

### Start TLS-Secured Proxy

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Launches a TLS-secured proxy on port 8443, requiring certificate and key files for secure communication.

```bash
gost -L "https://:8443?certFile=/path/to/cert.pem&keyFile=/path/to/key.pem"
```

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

### Load Balancing with Configuration File

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Starts Gost using a configuration file for load balancing. The configuration file should define multiple nodes within a forwarder and specify a selector strategy.

```bash
gost -C config.yaml
# In config.yaml, define multiple nodes in a forwarder with selector strategy
```

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

### Create Service cURL Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Use this cURL command to create a new service. Ensure the Content-Type header is set to application/json and provide the service configuration in the request body.

```bash
curl -X POST http://localhost:18080/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "socks5-proxy",
    "addr": ":1080",
    "handler": {
      "type": "socks5"
    },
    "listener": {
      "type": "tcp"
    }
  }'
```

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

### Query DNS Proxy

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Examples of querying the configured DNS proxy using `nslookup` and `dig`.

```bash
# Query the proxy
nslookup google.com 127.0.0.1
dig @127.0.0.1 example.com
```

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

### Basic Authentication Usage

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Example of how to use basic authentication with curl. The username and password are provided in the URL.

```bash
curl -x http://alice:password123@127.0.0.1:8080 http://example.com
```

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

### Test SOCKS5 Server with Curl and Python

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Examples for testing the SOCKS5 server using curl with socks5h for DNS, and a Python script using the requests library.

```bash
# Test with curl (requires socks5h for DNS over proxy)
curl --socks5-hostname 127.0.0.1:1080 http://example.com

# Test with Python requests
python3 -c "
import requests
proxies = {'http': 'socks5://127.0.0.1:1080', 'https': 'socks5://127.0.0.1:1080'}
r = requests.get('http://httpbin.org/ip', proxies=proxies)
print(r.json())
"
```

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

### Example Invalid API Request

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

This example demonstrates an invalid API request to create a service with an incorrect handler type. It shows the curl command to send the request and the expected JSON error response.

```bash
curl -X POST http://localhost:18080/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invalid-service",
    "handler": {
      "type": "invalid-handler-type"
    }
  }'
```

```json
{
  "error": "invalid handler type: invalid-handler-type",
  "code": "VALIDATION_ERROR"
}
```

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

### Complete JSON Configuration for Gost

Source: https://github.com/go-gost/gost/blob/master/_autodocs/types-and-protocols.md

Provides a full JSON configuration example for Gost, covering services, chains, hops, nodes, and authenticators. This serves as a reference for structuring complex configurations.

```json
{
  "services": [
    {
      "name": "http-proxy",
      "addr": ":8080",
      "handler": {
        "type": "http"
      },
      "listener": {
        "type": "tcp"
      }
    }
  ],
  "chains": [
    {
      "name": "chain0",
      "hops": [
        {
          "name": "hop0",
          "nodes": [
            {
              "name": "node0",
              "addr": "proxy.example.com:1080",
              "connector": {
                "type": "socks5"
              },
              "dialer": {
                "type": "tcp"
              }
            }
          ]
        }
      ]
    }
  ],
  "authers": [
    {
      "name": "auth0",
      "auths": [
        {
          "username": "user1",
          "password": "pass1"
        }
      ]
    }
  ]
}
```

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

### Create Auther via API

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Use this command to create an 'auther' resource in GOST API, which defines authentication methods for services. This example sets up basic authentication with usernames and passwords.

```bash
# Create auther
curl -X POST http://localhost:18080/authers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "users",
    "auths": [
      {"username": "alice", "password": "pass123"},
      {"username": "bob", "password": "pass456"}
    ]
  }'
```

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

### Configure DNS Proxy with Custom Resolver

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Set up a DNS proxy that forwards queries to a specified resolver. This example uses UDP and TCP connections to a corporate DNS server.

```yaml
chains:
- name: dns-chain
  hops:
  - name: hop1
    nodes:
    - name: trusted-dns
      addr: "8.8.8.8:53"
      connector:
        type: direct
      dialer:
        type: udp

resolvers:
- name: corporate-dns
  nameservers:
  - addr: "udp://corp-dns.example.com:53"
  - addr: "tcp://corp-dns.example.com:53"

services:
- name: dns-proxy
  addr: ":53"
  handler:
    type: dns
    resolver: corporate-dns
  listener:
    type: udp
```

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

### Configure HTTP/3 Proxy with TLS

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Configure an HTTP/3 proxy service. This example specifies TLS certificates for secure communication.

```yaml
services:
- name: http3-proxy
  addr: ":8443"
  handler:
    type: http3
  listener:
    type: http3
    tls:
      certFile: "/path/to/cert.pem"
      keyFile: "/path/to/key.pem"
```

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

### Enable API and Metrics Endpoints

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Starts Gost with both the API enabled on port 18080 and Prometheus metrics exposed on port 9000, using a configuration file.

```bash
gost -C config.yaml -api :18080 -metrics :9000
```

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

### Get Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves the current configuration of the Gost service.

```APIDOC
## GET /config

### Description
Retrieves the current configuration of the Gost service.

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- **data** (object) - Contains the service configuration.

### Request Example
```json
{
  "example": ""
}
```

### Response Example
```json
{
  "data": "..."
}
```
```

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

### Basic Authentication Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Configure basic username and password authentication for all connections. This setup requires defining an 'auther' in the 'authers' section and referencing it in the 'services' section.

```yaml
authers:
- name: users
  auths:
  - username: alice
    password: password123
  - username: bob
    password: securepass456

services:
- name: protected-proxy
  addr: ":8080"
  handler:
    type: http
    auther: users
  listener:
    type: tcp
```

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

### Mutual TLS (Client Certificates) Usage

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Example usage for connecting to a mutual TLS proxy, providing client certificates.

```bash
curl -x https://127.0.0.1:8443 \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  https://example.com
```

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

### Self-Signed HTTPS Proxy Usage

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Example usage for connecting to a self-signed HTTPS proxy.

```bash
curl -k -x https://127.0.0.1:8443 https://example.com
```

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

### Network Layer: Dialer Stacking Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/execution-model.md

Visualizes the flow of network requests through a stacked dialer configuration, from the user application down to the actual TCP socket.

```plaintext
User app
    ↓
Listener (e.g., TCP on port 8080)
    ↓
Handler (e.g., HTTP CONNECT)
    ↓
Chain → Hop → Node
    ↓
Connector (e.g., SOCKS5)
    ↓
Dialer (e.g., TLS over TCP)
    ↓
Actual TCP socket
    ↓
Network
```

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

### Test HTTP Proxy with Curl

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Examples of testing the HTTP proxy using curl for both HTTP and HTTPS traffic.

```bash
# Test with curl
curl -x http://127.0.0.1:8080 http://example.com

# Test with HTTPS tunneling
curl -x http://127.0.0.1:8080 https://example.com
```

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

### Access HTTP/3 Proxy

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Example of accessing the HTTP/3 proxy using `curl`. Requires an HTTP/3-aware client.

```bash
# Requires HTTP/3-aware client
curl --http3 https://127.0.0.1:8443 https://example.com
```

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

### Set up a simple HTTP proxy

Source: https://github.com/go-gost/gost/blob/master/_autodocs/README.md

Use this command to quickly establish a basic HTTP proxy. Refer to cli-reference.md and usage-patterns.md for more details.

```bash
gost -L "http://:8080"
```

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

### Check Gost configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/README.md

Validate your Gost configuration by outputting it in YAML format using the -O yaml flag and specifying the configuration file with -C. This helps in verifying setup.

```bash
gost -O yaml -C config.yaml
```

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

### Run Multiple Workers with Different Proxies

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Starts Gost with multiple worker processes, each configured to run a different type of proxy (HTTP and SOCKS5).

```bash
gost -L "http://:8080" -- -L "socks5://:1080"
```

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

### Load Configuration from File

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Launches GOST using a configuration file located at /etc/gost/config.yaml.

```bash
gost -C /etc/gost/config.yaml
```

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

### Build GOST from source

Source: https://github.com/go-gost/gost/blob/master/README_en.md

Clones the GOST repository, navigates to the command directory, and builds the executable using Go.

```bash
git clone https://github.com/go-gost/gost.git
cd gost/cmd/gost
go build
```

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

### Get Service API Endpoint

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieve details for a specific service by its name using the GET /services/{name} endpoint. Requires a valid service name and authentication.

```http
GET /services/{name}
```

```json
{
  "data": {
    "name": "http-proxy",
    "addr": ":8080",
    "handler": {
      "type": "http"
    },
    "listener": {
      "type": "tcp"
    }
  }
}
```

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

### Get Current Configuration API Endpoint

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieve the entire current GOST configuration, including services, chains, authers, logging, and API settings, using the GET /config endpoint. Requires authentication.

```http
GET /config
```

```json
{
  "data": {
    "services": [...],
    "chains": [...],
    "authers": [...],
    "log": {...},
    "api": {...}
  }
}
```

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

### Get Auther

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves details for a specific authenticator by its name.

```APIDOC
## GET /authers/{name}

### Description
Retrieves details for a specific authenticator by its name.

### Method
GET

### Endpoint
/authers/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the authenticator to retrieve.
```

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

### Get Chain

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves details for a specific chain by its name.

```APIDOC
## GET /chains/{name}

### Description
Retrieves details for a specific chain by its name.

### Method
GET

### Endpoint
/chains/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the chain to retrieve.
```

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

### Print Version

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Prints the GOST version and Go version information, then exits.

```bash
gost -V
```

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

### Get Resolver

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves details for a specific DNS resolver by its name.

```APIDOC
## GET /resolvers/{name}

### Description
Retrieves details for a specific DNS resolver by its name.

### Method
GET

### Endpoint
/resolvers/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the DNS resolver to retrieve.
```

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

### Get Admission

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves details for a specific admission rule by its name.

```APIDOC
## GET /admissions/{name}

### Description
Retrieves details for a specific admission rule by its name.

### Method
GET

### Endpoint
/admissions/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the admission rule to retrieve.
```

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

### Get Bypass

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves details for a specific bypass rule by its name.

```APIDOC
## GET /bypasses/{name}

### Description
Retrieves details for a specific bypass rule by its name.

### Method
GET

### Endpoint
/bypasses/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the bypass rule to retrieve.
```

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

### Check All Services

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Use this command to retrieve a list of all configured services and their current status. It pipes the output to jq for formatted display.

```bash
curl http://localhost:18080/services | jq '.data[] | {name, status}'
```

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

### Get Service Status

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves the status and health metrics for a specific service.

```APIDOC
## GET /services/{name}/status

### Description
Retrieves the status and health metrics for a specific service.

### Method
GET

### Endpoint
/services/{name}/status

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the service to get the status for.

### Response
#### Success Response (200)
- **data** (object) - Service status information.
  - **name** (string) - The name of the service.
  - **status** (string) - Running status (running, stopped, error).
  - **connections** (integer) - Active connection count.
  - **bytesIn** (integer) - Total bytes received.
  - **bytesOut** (integer) - Total bytes transmitted.
  - **errors** (integer) - Error count.
  - **uptime** (integer) - Seconds since service start.

### Response Example
```json
{
  "data": {
    "name": "http-proxy",
    "status": "running",
    "connections": 42,
    "bytesIn": 1024000,
    "bytesOut": 2048000,
    "errors": 0,
    "uptime": 3600
  }
}
```
```

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

### Profiling Server Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Go pprof profiling server configuration to listen on a specified address for CPU/memory profiling.

```yaml
profiling:
  addr: ":6060"                      # Listen on this address
```

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

### Enable API via CLI

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Enable the GOST API service by specifying the address and port using the -api flag in the command line.

```bash
gost -C config.yaml -api :18080
```

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

### Delete Service cURL Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Use this cURL command to delete a service. Specify the service name in the URL.

```bash
curl -X DELETE http://localhost:18080/services/http-proxy
```

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

### Enable API via Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Configure the GOST API service by setting the address, path prefix, access log, and authentication details within the configuration file.

```yaml
api:
  addr: ":18080"
  pathPrefix: "/api"
  accesslog: true
  auth:
    username: admin
    password: password
```

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

### Configure TLS Settings

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Set up TLS for listeners and dialers. Specify certificate and key files, CA file for verification, and whether to enforce secure connections or allow self-signed certificates. Configure server name for SNI.

```yaml
tls:
  certFile: /path/to/cert.pem        # Server certificate (for listeners)
  keyFile: /path/to/key.pem          # Server private key (for listeners)
  caFile: /path/to/ca.pem            # CA certificate (for client verification)
  secure: false                      # true = verify server cert, false = allow self-signed
  serverName: example.com            # SNI hostname (for dialers)
```

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

### Get Auther API Request

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Fetch details for a specific auther by its name. The `name` parameter is a path parameter.

```http
GET /authers/{name}
```

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

### QUIC Listener Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure a raw QUIC listener without HTTP encapsulation for custom QUIC applications. Provide certificate and key files.

```yaml
listener:
  type: quic
  tls:
    certFile: /path/to/cert.pem
    keyFile: /path/to/key.pem
  metadata: {}
```

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

### Get Chain API Request

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieve details for a specific chain by its name. The `name` parameter is a path parameter.

```http
GET /chains/{name}
```

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

### Environment Variable Substitution in Gost Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/types-and-protocols.md

Demonstrates how to use environment variables with default values in Gost configuration files. This allows for dynamic configuration based on the environment.

```yaml
# Using environment variable
addr: "${LISTEN_ADDR:-:8080}"  # Falls back to :8080 if LISTEN_ADDR not set
```

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

### Get Service

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves the details of a specific service by its name. Use this to inspect the configuration and status of an individual service.

```APIDOC
## GET /services/{name}

### Description
Retrieves the details of a specific service by its name.

### Method
GET

### Endpoint
/services/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the service to retrieve.

### Response
#### Success Response (200)
- **data** (object) - The service definition object.

### Request Example
None

### Response Example
```json
{
  "data": {
    "name": "http-proxy",
    "addr": ":8080",
    "handler": {
      "type": "http"
    },
    "listener": {
      "type": "tcp"
    }
  }
}
```
```

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

### Create Service

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Creates a new service with the specified configuration.

```APIDOC
## POST /services

### Description
Creates a new service with the specified configuration.

### Method
POST

### Endpoint
/services

### Parameters
#### Request Body
- **name** (string) - Required - The name of the service.
- **addr** (string) - Required - The address the service will listen on.
- **handler** (object) - Required - The service handler configuration.
  - **type** (string) - Required - The type of handler (e.g., "socks5").
- **listener** (object) - Required - The service listener configuration.
  - **type** (string) - Required - The type of listener (e.g., "tcp").

### Request Example
```json
{
  "name": "socks5-proxy",
  "addr": ":1080",
  "handler": {
    "type": "socks5"
  },
  "listener": {
    "type": "tcp"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created service details.

### Response Example
```json
{
  "data": "..."
}
```
```

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

### Build GOST Binary

Source: https://github.com/go-gost/gost/blob/master/CLAUDE.md

Builds the gost CLI binary. Use cross-compilation flags for different operating systems and architectures. The `make all` command builds for all platforms.

```bash
cd gost && go build ./cmd/gost/...

```

```bash
# Cross-compile
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" ./cmd/gost/...

```

```bash
# Build all platforms
make all

```

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

### Configure Chained Proxies

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Sets up an HTTP proxy on port 8080 that forwards traffic through a SOCKS5 proxy.

```bash
gost -L "http://:8080" -F "socks5://proxy.example.com:1080"
```

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

### Get Resolver API Request

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Fetch details for a specific DNS resolver by its name. The `name` parameter is a path parameter.

```http
GET /resolvers/{name}
```

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

### Get Admission API Request

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Fetch details for a specific admission rule by its name. The `name` parameter is a path parameter.

```http
GET /admissions/{name}
```

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

### Get Bypass API Request

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Fetch details for a specific bypass rule by its name. The `name` parameter is a path parameter.

```http
GET /bypasses/{name}
```

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

### TCP Port Forwarding (Client Initiates)

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Forward a local port to a remote service. Connect to the local port to reach the remote service.

```yaml
services:
- name: mysql-forward
  addr: ":3306"
  handler:
    type: forward/local
  listener:
    type: tcp
  forwarder:
    nodes:
    - name: mysql-server
      addr: "internal-mysql.example.com:3306"
```

```bash
# Connect to local port, transparently forwarded to remote
mysql -h 127.0.0.1 -u user -p
```

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

### Get Current Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Retrieves the entire current configuration of the GOST service, including services, chains, and API settings.

```APIDOC
## GET /config

### Description
Retrieves the entire current configuration of the GOST service.

### Method
GET

### Endpoint
/config

### Parameters
None

### Response
#### Success Response (200)
- **data** (object) - The current configuration object.

### Request Example
None

### Response Example
```json
{
  "data": {
    "services": [...],
    "chains": [...],
    "authers": [...],
    "log": {...},
    "api": {...}
  }
}
```
```

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

### List Services API Endpoint

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Use the GET /services endpoint to retrieve a list of all currently configured services. Requires authentication if configured.

```http
GET /services
```

```json
{
  "data": [
    {
      "name": "http-proxy",
      "addr": ":8080",
      "handler": {
        "type": "http"
      },
      "listener": {
        "type": "tcp"
      }
    }
  ]
}
```

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

### UDP Listener Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure a UDP-based listener. Specify buffer size for UDP protocols like Shadowsocks or DNS.

```yaml
listener:
  type: udp
  metadata:
    bufferSize: 65535
```

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

### Listener and Handler Authentication Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Set up different authentication methods for distinct listeners. This allows for granular control over access based on the connection point.

```yaml
authers:
- name: trusted-users
  auths:
  - username: alice
    password: pass1
- name: untrusted-users
  auths:
  - username: guest
    password: guest

services:
- name: trusted-proxy
  addr: ":8080"
  listener:
    type: tls
    tls:
      certFile: "/path/to/cert.pem"
      keyFile: "/path/to/key.pem"
    auther: trusted-users
  handler:
    type: http

- name: guest-proxy
  addr: ":8081"
  listener:
    type: tcp
    auther: untrusted-users
  handler:
    type: http
```

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

### Get Service Status API Request

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Check the operational status of a specific service. The `name` parameter is a path parameter indicating the service to query.

```http
GET /services/{name}/status
```

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

### Configure Redirect/UDP Handler

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure a transparent UDP redirect handler with an optional DNS resolver.

```yaml
handler:
  type: redirect/udp
  resolver: resolver-name         # Optional: DNS resolver
  metadata: {}
```

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

### Enable Trace Logging

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Enables trace logging for maximum verbosity.

```bash
gost -DD
```

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

### File Handler Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure a static file server handler. Specify the root path and the index file to serve.

```yaml
handler:
  type: file
  metadata:
    path: /path/to/root
    index: "index.html"
```

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

### Configure SOCKS5 Server (YAML)

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

This YAML configuration sets up a SOCKS5 server listening on port 1080.

```yaml
services:
- name: socks5-server
  addr: ":1080"
  handler:
    type: socks5
  listener:
    type: tcp
```

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

### Fast TCP Listener Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure an optimized TCP listener for performance.

```yaml
listener:
  type: ftcp
  metadata: {}
```

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

### Create a forwarding chain in Gost configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/README.md

Define a forwarding chain named 'upstream' in the Gost configuration. This example specifies a SOCKS5 connector and a TCP dialer for the hop.

```yaml
chains:
- name: upstream
  hops:
  - nodes:
    - addr: "proxy.example.com:1080"
      connector:
        type: socks5
      dialer:
        type: tcp
```

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

### Update Service cURL Example

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Use this cURL command to update an existing service. Specify the service name in the URL and provide the fields to update in the JSON request body.

```bash
curl -X PUT http://localhost:18080/services/http-proxy \
  -H "Content-Type: application/json" \
  -d '{
    "addr": ":8081"
  }'
```

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

### SOCKS5 Proxy with Authentication

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Set up a SOCKS5 proxy service that requires username and password authentication.

```yaml
authers:
- name: auth0
  auths:
  - username: user1
    password: pass1

services:
- name: socks5-server
  addr: ":1080"
  handler:
    type: socks5
    auther: auth0
  listener:
    type: tcp
```

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

### HTTP/3 Listener Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure an HTTP/3 (QUIC) listener for encrypted connections. Provide certificate and key files.

```yaml
listener:
  type: http3
  tls:
    certFile: /path/to/cert.pem
    keyFile: /path/to/key.pem
  metadata: {}
```

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

### Set Memory Limit using cgroups

Source: https://github.com/go-gost/gost/blob/master/_autodocs/execution-model.md

Configure memory limits for a GoST process on Linux by writing to the cgroup memory control file. This example sets the limit to 1GB.

```bash
echo 1G > /sys/fs/cgroup/memory/gost/memory.limit_in_bytes
```

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

### Run GOST Service

Source: https://github.com/go-gost/gost/blob/master/CLAUDE.md

Launches the gost service using inline definitions for listener and forwarder, or by specifying a configuration file. Debug and trace logging can be enabled with -D or -DD.

```bash
./gost -L "http://:8080" -F "socks5://:1080"

```

```bash
./gost -C gost.yml

```

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

### Run E2E Tests with Pre-built Gost Binary

Source: https://github.com/go-gost/gost/blob/master/tests/e2e/README.md

Execute end-to-end tests using a pre-compiled gost binary, skipping the compilation step. This is beneficial for faster local iteration when developing tests or the gost binary itself.

```bash
go test ./tests/e2e/ -v -gost-bin /path/to/gost
```

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

### DNS Listener Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure a DNS protocol listener. Specify the buffer size for DNS queries.

```yaml
listener:
  type: dns
  metadata:
    bufferSize: 1024
```

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

### Run GOST CLI

Source: https://github.com/go-gost/gost/blob/master/_autodocs/cli-reference.md

Basic invocation of the GOST command-line tool.

```bash
gost [flags]
```

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

### Polling Script for Real-time Updates

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

This bash script demonstrates how to poll the GOST API for real-time updates by repeatedly fetching service data and checking its length. It requires `curl` and `jq` to be installed.

```bash
#!/bin/bash
while true; do
  curl -s http://localhost:18080/services | jq '.data | length'
  sleep 5
done
```

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

### Set File Descriptor Limit for GoST

Source: https://github.com/go-gost/gost/blob/master/_autodocs/execution-model.md

Increase the maximum number of open file descriptors using the ulimit command before starting GoST. This is crucial as each listener and connection consumes file descriptors.

```bash
ulimit -n 65536
gost -C config.yaml
```

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

### SOCKS5 Handler Behavior

Source: https://github.com/go-gost/gost/blob/master/_autodocs/execution-model.md

Outlines the steps involved in processing SOCKS5 connections, including authentication and request command handling.

```text
Connection from client
    ↓
Version identifier (0x05)
    ↓
Negotiation: auth methods
    └── None or username/password
    ↓
Authentication (if configured)
    ├── Verify username/password
    └── Fail if invalid
    ↓
Request command:
    ├── CONNECT: Establish target connection
    ├── BIND: Server-binding mode
    └── UDP ASSOCIATE: UDP relay mode
    ↓
Establish connection (CONNECT):
    ├── Extract target address (IPv4, IPv6, or domain)
    ├── If chain configured: through chain
    └── Else: direct connection
    ↓
Reply to client with bind address/port
    ↓
Bidirectional proxy
```

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

### Create Service

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Creates a new service with the provided configuration. This allows for dynamic addition of services to the running GOST instance.

```APIDOC
## POST /services

### Description
Creates a new service with the provided configuration.

### Method
POST

### Endpoint
/services

### Parameters
None

### Request Body
- **name** (string) - Required - The name of the new service.
- **addr** (string) - Required - The address the service will listen on.
- **handler** (object) - Required - The handler configuration for the service.
  - **type** (string) - Required - The type of handler.
- **listener** (object) - Required - The listener configuration for the service.
  - **type** (string) - Required - The type of listener.

### Request Example
```json
{
  "name": "new-service",
  "addr": ":8081",
  "handler": {
    "type": "socks5"
  },
  "listener": {
    "type": "tcp"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The created service definition object.

### Response Example
```json
{
  "data": {
    "name": "new-service",
    "addr": ":8081",
    "handler": {
      "type": "socks5"
    },
    "listener": {
      "type": "tcp"
    }
  }
}
```
```

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

### Interact with Gost REST API to list services

Source: https://github.com/go-gost/gost/blob/master/_autodocs/README.md

Use curl to send a GET request to the Gost REST API to retrieve a list of configured services. This is part of the API service interaction.

```bash
curl http://localhost:18080/services
```

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

### Single Upstream SOCKS5 Proxy Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Configure GOST to forward all traffic through a single upstream SOCKS5 proxy. This setup is useful for simple proxy chaining where a single intermediate hop is sufficient.

```yaml
chains:
- name: upstream
  hops:
  - name: hop1
    nodes:
    - name: upstream-proxy
      addr: "proxy.example.com:1080"
      connector:
        type: socks5
      dialer:
        type: tcp

services:
- name: http-proxy
  addr: ":8080"
  handler:
    type: http
    chain: upstream
  listener:
    type: tcp
```

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

### Create Auther

Source: https://github.com/go-gost/gost/blob/master/_autodocs/api-service.md

Creates a new authenticator with the specified name and authentication credentials.

```APIDOC
## POST /authers

### Description
Creates a new authenticator with the specified name and authentication credentials.

### Method
POST

### Endpoint
/authers

### Parameters
#### Request Body
- **name** (string) - Required - The name for the new authenticator.
- **auths** (array) - Required - A list of authentication credentials.
  - **username** (string) - Required - The username.
  - **password** (string) - Required - The password.

### Request Example
```json
{
  "name": "auth-new",
  "auths": [
    {
      "username": "user1",
      "password": "pass1"
    }
  ]
}
```
```

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

### Chain Resolution and Node Selection Logic

Source: https://github.com/go-gost/gost/blob/master/_autodocs/execution-model.md

Illustrates the step-by-step process of how a service handler forwards through a chain, including node selection strategies and connection establishment.

```plaintext
1. Handler retrieves configured chain
2. Chain has ordered hops (first → last)
3. For each hop:
   a. Selector chooses a node from hop's node list
      ├── Strategy: round-robin cycles through nodes
      ├── Strategy: random selects random node
      └── Considers node health (failed count, timeout)
   b. Node defines connector (protocol to upstream) and dialer (network layer)
   c. Connector and dialer are applied to establish connection
4. If node fails, selector marks it and may retry other nodes
5. Once all hops traversed, final connection reaches target
```

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

### WebSocket Listener Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure a WebSocket listener over HTTP/1.1. Specify the path, ping interval, and pong wait time.

```yaml
listener:
  type: ws
  metadata:
    path: "/ws"
    pingInterval: 30s
    pongWait: 60s
```

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

### Connect to WebSocket Tunnel

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Instructions for connecting to the WebSocket tunnel. Requires a WebSocket-aware client.

```bash
# WebSocket URL: ws://127.0.0.1:8080/tunnel
# Use with websocket-aware client
```

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

### KCP Listener Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/configuration.md

Configure a KCP listener for reliable UDP tunneling. Specify mode, MTU, and window sizes.

```yaml
listener:
  type: kcp
  metadata:
    mode: "fast"
    mtu: 1350
    sndwnd: 4096
    rcvwnd: 4096
```

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

### Attach GoST Profiler

Source: https://github.com/go-gost/gost/blob/master/_autodocs/execution-model.md

Use the Go pprof tool to attach to GoST's heap or CPU profiling endpoints. Specify the target URL, including the profiling type and optional duration for CPU profiles.

```bash
go tool pprof http://localhost:6060/debug/pprof/heap
```

```bash
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
```

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

### API-Based Dynamic Configuration

Source: https://github.com/go-gost/gost/blob/master/_autodocs/usage-patterns.md

Enable the Gost API to dynamically manage services. Configure the API address, access logging, and authentication credentials.

```yaml
api:
  addr: ":18080"
  accesslog: true
  auth:
    username: admin
    password: secure123

services:
- name: http-proxy
  addr: ":8080"
  handler:
    type: http
  listener:
    type: tcp
```

```bash
curl -X POST http://admin:secure123@127.0.0.1:18080/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-proxy",
    "addr": ":8081",
    "handler": {"type": "socks5"},
    "listener": {"type": "tcp"}
  }'
```