Gost - Monk Docs

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)

Load templates

monk load MANIFEST

Run Gost with defaults

monk run gost/gost

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:

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:

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:

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:

gost -L=http://user:pass@:8080

SOCKS5 Proxy:

gost -L=socks5://user:pass@:1080

Port Forwarding:

# Forward local 8080 to remote 80
gost -L=tcp://:8080/remote-host:80

Reverse Proxy:

# Forward remote port to local
gost -L=rtcp://:8080/:8080 -F=relay://server:1234

Shadowsocks:

gost -L=ss://aes-256-cfb:password@:8338

Configuration File

Example JSON config (config.json):

{
  "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:

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:

# 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:

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

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

Troubleshooting

Test proxy connection:

# 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:

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.

​Overview

​What this template manages

​Quick start (run directly)

​Configuration

​Use by inheritance (recommended for apps)

​Ports and connectivity

​Persistence and configuration

​Features

​Proxy Modes

​Configuration File

​Proxy Chaining

​Client Configuration

​Use cases

​Related templates

​Troubleshooting