<div align="center"> <img src="webui/public/vite.svg" width="48" alt="Resin Logo" /> <h1>Resin</h1> <p><strong>Turn massive proxy subscriptions into a stable, smart, and observable network with sticky sessions.</strong></p> </div> <p align="center"> <a href="https://github.com/Resinat/Resin/releases"><img src="https://img.shields.io/github/v/release/Resinat/Resin?style=flat-square&label=release&sort=semver" alt="Release" /></a> <a href="https://github.com/Resinat/Resin/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/Resinat/Resin/release.yml?style=flat-square&label=release%20pipeline" alt="Release Pipeline" /></a> <a href="https://github.com/Resinat/Resin/pkgs/container/resin"><img src="https://img.shields.io/badge/ghcr-ghcr.io%2Fresinat%2Fresin-2496ED?style=flat-square&logo=docker&logoColor=white" alt="GHCR Image" /></a> <a href="https://github.com/Resinat/Resin/blob/master/LICENSE"><img src="https://img.shields.io/github/license/Resinat/Resin?style=flat-square" alt="License" /></a> <a href="https://github.com/Resinat/Resin/blob/master/go.mod"><img src="https://img.shields.io/github/go-mod/go-version/Resinat/Resin?style=flat-square" alt="Go Version" /></a> <a href="https://github.com/Resinat/Resin/releases"><img src="https://img.shields.io/badge/support-linux%20%7C%20macOS%20%7C%20windows%20%C2%B7%20amd64%20%7C%20arm64-0A7EA4?style=flat-square" alt="Support Matrix" /></a> <a href="DESIGN.md"><img src="https://img.shields.io/badge/docs-DESIGN.md-1F6FEB?style=flat-square" alt="Design Docs" /></a> </p>

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

It helps shield your services from unstable upstream proxies and aggregates them into a single HTTP gateway 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.
Dual access modes: Supports both standard forward proxy (HTTP Proxy) and URL-based reverse proxy.
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_AUTH_VERSION: "V1" # Required: LEGACY_V0 or V1
      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.

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

Step 2: Import proxy nodes

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

Step 3: Start sending proxy requests

Use one of the client access modes in the following sections.

🟢 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, point your app to http://127.0.0.1:2260. If you do not want a proxy password, explicitly set RESIN_PROXY_TOKEN="" (the variable must still be defined). Then connect directly to http://127.0.0.1:2260.

Example with curl:

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

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

For forward proxy, put Platform in proxy auth info:

curl -x http://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)

With RESIN_AUTH_VERSION=V1, the identity format is: Platform.Account:RESIN_PROXY_TOKEN.

To keep the legacy V0 format, set RESIN_AUTH_VERSION=LEGACY_V0 and continue using RESIN_PROXY_TOKEN:Platform:Account.

Write identity directly in proxy auth username:

# V1 format: -U "platform.account:token"
# 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

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/SD

Resin

Install / Use

README