> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gost

> Ready-to-run Gost container template you can run directly or inherit to integrate a tunnel/proxy server into your stack.

## Overview

This template provides a production‑ready Gost instance as a Monk runnable. You can:

* Run it directly to get a managed tunnel/proxy server with sensible defaults
* Inherit it in your own runnable to seamlessly add secure tunneling and forwarding to your stack

Gost (GO Simple Tunnel) is a simple security tunnel written in Golang. It supports multiple protocols (SOCKS5, HTTP/HTTPS, SS, SSR, SNI, TLS, KCP, Quic) and can work as a local/remote port forwarder, SOCKS/HTTP proxy, and more.

## What this template manages

* Gost container (`ginuerzh/gost` image, configurable tag)
* Network service on configured port (default 8080 or 1080)
* Persistent volumes for configuration
* Optional authentication and encryption
* Support for proxy chaining and multiple protocols

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Gost with defaults

```bash theme={null}
monk run gost/gost
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `gost/gost.yaml`, then `monk load MANIFEST` and run.

Once started, Gost will listen on configured ports for proxy connections. Connect to `localhost:8080` (or the runnable hostname inside Monk networks) using the configured protocol and credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  gost-image-tag: "latest"            # container image tag
  listen-port: "8080"                 # main listening port
  proxy-mode: "http"                  # protocol: http, socks5, ss, relay, etc.
  auth-user: "user"                   # authentication username
  auth-password: "..."                # authentication password
  gost-config: "..."                  # optional Gost JSON configuration
```

Configuration is persisted under `${monk-volume-path}/gost` on the host. Custom Gost config files are mounted from `${monk-volume-path}/gost/config:/etc/gost`.

## Use by inheritance (recommended for apps)

Inherit the Gost runnable in your application for secure tunneling. Example:

```yaml theme={null}
namespace: myapp
proxy:
  defines: runnable
  inherits: gost/gost
  variables:
    proxy-mode: "socks5"
    listen-port: "1080"
    auth-user: <- secret("gost-user")
    auth-password: <- secret("gost-password")
backend:
  defines: runnable
  containers:
    app:
      image: myorg/app
  connections:
    tunnel:
      runnable: proxy
      service: gost
  variables:
    proxy-host:
      value: <- connection-hostname("tunnel")
    proxy-port:
      value: "1080"
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g gost-user="proxyuser"
monk secrets add -g gost-password="STRONG_PASSWORD"
monk run myapp/backend
```

## Ports and connectivity

* Service: `gost` on TCP port as configured (default `8080` for HTTP, `1080` for SOCKS5)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the proxy host.

## Persistence and configuration

* Config path: `${monk-volume-path}/gost/config:/etc/gost`
* You can drop additional JSON config files into the config path to configure Gost.

## Features

* **Multiple Protocols**: SOCKS4/5, HTTP/HTTPS, SS, SSR, SNI, TLS, KCP, Quic
* **Port Forwarding**: Local and remote port forwarding
* **Proxy Chain**: Chain multiple proxies together
* **Authentication**: Username/password auth
* **Encryption**: TLS/SSL, Shadowsocks encryption
* **Load Balancing**: Round-robin, random, least-connections
* **Traffic Routing**: Rule-based routing
* **UDP Support**: UDP over TCP tunneling

## Proxy Modes

**HTTP Proxy**:

```bash theme={null}
gost -L=http://user:pass@:8080
```

**SOCKS5 Proxy**:

```bash theme={null}
gost -L=socks5://user:pass@:1080
```

**Port Forwarding**:

```bash theme={null}
# Forward local 8080 to remote 80
gost -L=tcp://:8080/remote-host:80
```

**Reverse Proxy**:

```bash theme={null}
# Forward remote port to local
gost -L=rtcp://:8080/:8080 -F=relay://server:1234
```

**Shadowsocks**:

```bash theme={null}
gost -L=ss://aes-256-cfb:password@:8338
```

## Configuration File

Example JSON config (`config.json`):

```json theme={null}
{
  "Debug": true,
  "ServeNodes": [
    "http://user:pass@:8080",
    "socks5://user:pass@:1080"
  ],
  "ChainNodes": [
    "http://upstream-proxy:8080"
  ]
}
```

## Proxy Chaining

Chain multiple proxies for enhanced security or routing:

```bash theme={null}
gost -L=:8080 -F=http://proxy1:8080 -F=socks5://proxy2:1080
```

Request flow: Client → Gost → proxy1 → proxy2 → Destination

## Client Configuration

Configure clients to use Gost:

**Browser (SOCKS5)**:

* Proxy: `localhost`
* Port: `1080`
* SOCKS v5

**curl**:

```bash theme={null}
# HTTP proxy
curl -x http://user:pass@localhost:8080 https://example.com

# SOCKS5 proxy
curl -x socks5://user:pass@localhost:1080 https://example.com
```

**SSH through proxy**:

```bash theme={null}
ssh -o ProxyCommand="nc -X 5 -x localhost:1080 %h %p" user@remote-host
```

## Use cases

Gost excels at:

* Secure HTTP/SOCKS proxy for applications
* Port forwarding and tunneling
* Bypassing network restrictions
* Secure remote access
* Load balancing across multiple proxies
* Traffic routing and redirection
* Development and testing proxies

## Related templates

* High-availability proxy cluster: see other templates in this repository for clustered setups.
* Combine with monitoring tools for observability.

## Troubleshooting

* Test proxy connection:

```bash theme={null}
# HTTP proxy
curl -x http://user:pass@localhost:8080 https://ifconfig.me

# SOCKS5 proxy
curl -x socks5://user:pass@localhost:1080 https://ifconfig.me
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f gost/gost
```

* Enable debug mode in config for verbose logging.
* For connection issues:
  * Verify firewall allows the proxy port
  * Check authentication credentials match
  * Test without proxy chain first
  * Ensure the container is running and listening
* For performance issues, try different protocols (KCP for UDP, Quic for modern encryption).
* Monitor bandwidth usage for proxy traffic to detect issues.