Resin

English | 简体中文

Resin is a high-performance intelligent proxy pool gateway built for operating massive numbers of proxy nodes.

It helps shield your services from unstable underlying proxy nodes by aggregating distributed proxy resources into a unified proxy entrypoint with session stickiness (sticky routing).

Why Resin?

• Massive-scale management: Easily handles 100k+ proxy nodes with native high-concurrency performance.
• Smart scheduling and circuit breaking: Fully automated passive + active health checks, outbound IP probing, and latency analysis to remove bad nodes precisely. Uses P2C plus domain-aware latency-weighted scoring for optimal node selection.
• Business-friendly sticky proxying: Keeps the same business account bound to a stable outbound IP. If a node fails, Resin seamlessly switches to another node with the same IP.
• Multiple access modes: Supports HTTP forward proxy, SOCKS5 forward proxy, and URL-based reverse proxy for different clients and integration styles.
• Multiple inbound endpoints: Add hot-reloaded listening ports in the WebUI and independently control admin-console, HTTP forward, HTTP reverse, and SOCKS5 access on each port.
• Observability: Detailed metrics and logs, plus a visual Web UI. Includes complete structured request logs for querying and auditing by platform, account, target site, and more.
• Simple and powerful: Works out of the box with default settings, while still offering deep customization for enterprise-grade needs.
• Cross-subscription deduplication: Automatically merges identical nodes from different subscriptions and shares their health state.
• Hot reload: Update common settings without restart. Refresh subscriptions without dropping existing traffic.
• Persistent state: Keeps node health, latency stats, and lease bindings across restarts.
• Zero-intrusion sticky access: Can extract account identity from existing request headers (for example API keys), so clients often need no code changes.
• Incremental subscription refresh: Syncs subscription updates without interrupting current connections.
• Flexible node isolation: Use Platform rules (regex, region, etc.) to build independent proxy pools for different business scenarios.

[!TIP] You can feed this README and DESIGN.md to AI and ask it anything about the project.

Supported Protocols and Subscription Formats

Subscription sources

• Remote subscription URL: http:// or https://.
• Local subscription content: paste subscription content directly in the UI/API.

Subscription content formats

• sing-box JSON: {"outbounds":[...]} or raw outbound array [...].
• Clash JSON/YAML: {"proxies":[...]} or YAML proxies:.
• URI line format (one node per line): vmess://, vless://, trojan://, ss://, hysteria2://, http://, https://, socks5://, socks5h://. For http://, https://, socks5://, socks5h://, use scheme://[user:pass@]host:port (optional #tag; https also supports sni/servername/peer and allowInsecure/insecure query parameters).
• Plain HTTP proxy lines: IP:PORT or IP:PORT:USER:PASS (IPv4 and IPv6).
• Base64-wrapped text subscriptions (for URI lines/plain-text node lists).

Supported outbound node types

• For sing-box JSON/raw outbounds: socks, http, shadowsocks, vmess, trojan, wireguard, hysteria, vless, shadowtls, tuic, hysteria2, anytls, ssh.
• For Clash conversion: ss/shadowsocks, socks/socks4/socks4a/socks5, http, vmess, vless, trojan, wireguard/wg, hysteria, hysteria2/hy2, tuic, anytls, ssh.

Quick Start

In just three steps, you can turn your proxy subscriptions into a highly available proxy pool.

Step 1: Deploy and start

Docker Compose is the recommended quick-start path:

# docker-compose.yml
services:
  resin:
    image: ghcr.io/resinat/resin:latest
    container_name: resin
    restart: unless-stopped
    environment:
      RESIN_ADMIN_TOKEN: "admin123" # Change to your admin dashboard password
      RESIN_PROXY_TOKEN: "my-token" # Change to your proxy password
      RESIN_LISTEN_ADDRESS: 0.0.0.0
      RESIN_PORT: 2260
    ports:
      - "2260:2260"
    volumes:
      - ./data/cache:/var/cache/resin
      - ./data/state:/var/lib/resin
      - ./data/log:/var/log/resin

Run docker compose up -d to start the service.

Custom endpoint ports must also be reachable from outside the container. Docker cannot add published ports to an already-running container, so pre-publish the required port range in ports (for example "2300-2399:2300-2399") or use host networking where appropriate.

(If you don't want Docker, jump to Other Deployment Options.)

Step 2: Import proxy nodes

1. Open http://127.0.0.1:2260 in your browser (replace with your server IP if needed).
2. Log in with the RESIN_ADMIN_TOKEN you set.
3. Go to Subscriptions in the left menu and add your node subscription.
4. Wait briefly for the node pool to refresh.

Step 3: Start sending proxy requests

See the following sections for client access modes. In common scenarios, you can choose HTTP forward proxy, SOCKS5 forward proxy, or reverse proxy based on what your client supports.

Basic Usage (Non-sticky Proxy)

Connect as a standard proxy

If you just need a high-performance, large-capacity proxy pool with automatic health management, Resin works out of the box.

Once Resin is running, you can choose HTTP forward proxy, SOCKS5 forward proxy, or reverse proxy based on what your client supports. If you do not want a proxy password, explicitly set RESIN_PROXY_TOKEN="" (the variable must still be defined). Then HTTP forward proxy is available at http://127.0.0.1:2260, and SOCKS5 forward proxy is available at socks5://127.0.0.1:2260. For binary/source runs, Resin also loads a .env file from the current working directory before reading configuration. Environment variables already set by the OS or shell take precedence over .env values.

HTTP forward proxy example:

curl -x http://127.0.0.1:2260 \
  -U ":my-token" \
  https://api.ipify.org

SOCKS5 forward proxy example:

curl --proxy socks5h://127.0.0.1:2260 \
  -U "Default:my-token" \
  https://api.ipify.org

When RESIN_PROXY_TOKEN="", SOCKS5 also allows unauthenticated access.

If your client supports overriding BASE_URL, you can also use reverse-proxy mode. URL format: /token/Platform(optional).Account(optional)/protocol/target. Example request to https://api.ipify.org:

curl http://127.0.0.1:2260/my-token/./https/api.ipify.org

Choosing forward vs reverse proxy: when possible, reverse proxy is recommended for better observability. If your client cannot change BaseURL, or requires scenarios better served by forward proxy (such as uTLS or non-WebAPI traffic), use forward proxy.

Filter nodes

If your service needs specific nodes (for example by region, subscription source, or name regex), use Resin's Platform feature.

Open http://127.0.0.1:2260/ui/platforms and create a Platform. For example, to use only US and HK nodes, create MyPlatform and set region filters to:

us
hk

Node tag rules match <SubscriptionName>/<NodeTag>, with one regular expression per line. Plain rules are ORed, a leading * marks a required rule, and a leading ! excludes a node on any match. For example, this selects dedicated Hong Kong or Japan nodes while excluding expired and invalid nodes:

Hong Kong
Japan
*Dedicated
!Expired
!Invalid

Only the first character is interpreted as a rule prefix; the rest remains a Go regular expression. Escape a literal leading ! as \!.

For forward proxy (HTTP / SOCKS5), include Platform in the auth info. Examples:

curl -x http://127.0.0.1:2260 \
  -U "MyPlatform:my-token" \
  https://api.ipify.org

curl --proxy socks5h://127.0.0.1:2260 \
  -U "MyPlatform:my-token" \
  https://api.ipify.org

For reverse proxy, include Platform in the URL prefix:

curl http://127.0.0.1:2260/my-token/MyPlatform/https/api.ipify.org

Advanced Usage: Sticky Session Proxy

When your business depends on IP continuity or long-lived interactions, use Resin's core feature: sticky proxying.

First, understand two core concepts:

Core Concepts: Platform and Account

• Platform: An isolated node pool. You can build it with filters (for example, only US nodes). Resin provides a default Default platform containing all available nodes.
• Account: A unique business identity (for example Tom or user_1). For requests carrying an Account, Resin anchors traffic to a dedicated high-quality outbound node. If that node fails, Resin retries seamlessly and switches to another node with the same IP.

Sticky proxy access formats

Method 1: Forward proxy (HTTP Proxy / SOCKS5)

HTTP forward proxy and SOCKS5 forward proxy share the same identity format: Platform.Account:RESIN_PROXY_TOKEN.

Just put the identity in proxy authentication:

# HTTP forward proxy: bind business account user_tom to a stable dedicated outbound IP
curl -x http://127.0.0.1:2260 \
  -U "Default.user_tom:my-token" \
  https://api.ipify.org

# SOCKS5 forward proxy: uses the same identity format as HTTP forward proxy
curl --proxy socks5h://127.0.0.1:2260 \
  -U "Default.user_tom:my-token" \
  https://api.ipify.org

Method 2: Reverse proxy (URL Account, quick/manual debug)

By replacing your service BaseURL with Resin reverse-proxy URL, traffic goes through Resin directly. Advanced URL format: http://host:2260/token/platform.account/protocol/target:

# Example: user_tom accesses api.ipify.org over https
curl "http://127.0.0.1:2260/my-token/Default.user_tom/https/api.ipify.org"

The URL Account segment is designed for quick use and manual debugging. For long-running production integrations, prefer passing Account by header (X-Resin-Account).

Method 3: Reverse proxy + X-Resin-Account header (recommended production integration)

If your client/SDK supports custom request headers, pass Account explicitly with X-Resin-Account. This is the recommended and most stable method.

Account source priority: X-Resin-Account header > Account in reverse-proxy URL > header extraction rules.

Example:

curl "http://127.0.0.1:2260/my-token/MyPlatform/https/api.example.com/v1/orders" \
  -H "X-Resin-Account: user_tom"

Method 4: Reverse proxy + header rules (zero/low-intrusion integration)

If your client cannot set X-Resin-Account, Resin can still extract Account from existing business headers (for example API Key, Token, Cookie) via header rules.

Assume your requests already include an Authorization header:

1. In Platform Configuration, set Reverse-proxy empty-account behavior to Extract specified request headers as Account.
2. Set Headers used to extract Account to Authorization.

Then even if Account is omitted in URL, Resin can still parse it from headers:

curl "http://127.0.0.1:2260/my-token/MyPlatform/https/api.example.com/v1/orders" \
  -H "Authorization: sk-abc123"

In this example, Resin uses sk-abc123 as Account. Future requests with the same key are intended to stay bound to the same outbound IP whenever routing conditions allow.

[!TIP] Beyond Platform header confi