scproxy — A command-line HTTP reverse proxy with intelligent caching
Forked from Madh93/prxy with enhanced features
scproxy stands for Sieve Cache Proxy — filtering and caching HTTP responses efficiently.

Features •
Installation •
Quick Start •
Configuration •
Caching •
License
简体中文
Overview
scproxy(Sieve Cache Proxy) is a lightweight HTTP reverse proxy written in Go that helps you forward HTTP requests through an outbound proxy with intelligent response caching. It's designed for scenarios where you need to:
- Route multiple services through different local ports
- Forward traffic via an external HTTP proxy (e.g., corporate proxies, wireproxy, Squid)
- Cache HTTP responses to reduce bandwidth and improve latency
Features
Core
- Batch proxy mode — Run multiple routes simultaneously on different ports
- Outbound proxy chaining — Forward all traffic through an external HTTP proxy
- Automatic Host header rewriting — Ensures requests reach the correct backend
- Graceful shutdown — Clean handling of SIGTERM/SIGINT signals
Caching
- Path-based storage — Cache files mirror URL paths for easy inspection
- Streaming support — Efficient handling of large files
- HTTP Range requests — Full support for partial content delivery
- Configurable policies — Size limits, extension exclusions, auth handling
- LRU eviction — Automatic cache cleanup when size limit is reached
- Cache statistics — Track hits, misses, and storage usage
Configuration
- Multiple sources — CLI flags, config files, and defaults
- Dynamic routes — Add routes via CLI without editing config
- Auto-save — CLI settings persist to config file
Installation
Binary (Recommended)
curl -L https://github.com/peng-mj/scproxy/releases/latest/download/scproxy_$(uname -s)_$(uname -m).tar.gz | tar -xz -O scproxy > /usr/local/bin/scproxy
chmod +x /usr/local/bin/scproxy
From Source
go install github.com/peng-mj/scproxy@latest
Quick Start
Single Route
Forward one target through an outbound proxy:
scproxy --target https://example.com --proxy http://proxy:8080 --port 8080
Batch Mode (Multiple Routes)
Create a config at ./cache/scproxy.json:
{
"host": "0.0.0.0",
"proxy": "http://proxy:8080",
"routes": [
{"target": "https://github.com", "port": 8081},
{"target": "https://gitlab.com", "port": 8082},
{"target": "https://api.example.com", "port": 8083}
],
"cache": {
"enabled": true,
"directory": "./cache"
}
}
Then run:
scproxy
Add Temporary Route
scproxy --target https://httpbin.org --port 9999
Configuration
Config File
Created automatically at ./config.json on first run. All persistent state
(config file, cache data + databases, certificates) lives under one data
directory (--data-dir, default: current directory):
<data-dir>/
├── config.json # configuration
├── cache/ # cached data, cache_index.db, stats.db
└── certs/ # generated TLS certificates
{
"host": "0.0.0.0",
"proxy": "",
"routes": [],
"cache": {
"enabled": true,
"directory": "./cache",
"excludeLastPfx": ["index.html"]
},
"logging": {
"level": "info",
"format": "text",
"output": "stdout"
}
}
Priority
- CLI flags (highest)
- Config file
- Defaults (lowest)
CLI Options
| Flag |
Description |
Default |
--target, -t |
Target service URL |
— |
--port, -P |
Listen port |
— |
--proxy, -x |
Outbound proxy URL |
Direct |
--host, -H |
Listen host |
0.0.0.0 |
--config, -c |
Config file path |
./config.json |
--data-dir |
Unified data directory (config.json, cache/, certs/) |
. |
--cache |
Enable caching |
true |
--clear-cache |
Clear cache and exit |
— |
--yes |
Skip confirmation |
— |
--summary, -s |
Show cache stats |
— |
--version, -v |
Show version |
— |
--log-level, -l |
Log level |
info |
--log-output, -o |
Log output |
stdout |
Caching
Cache Control
| Setting |
Description |
enabled |
Enable/disable caching |
directory |
Storage path (default <data-dir>/cache) |
excludeLastPfx |
URL path suffix patterns to skip |
Path Exclusion
excludeLastPfx patterns are matched against the end of the URL path (suffix, case-insensitive):
| Pattern |
Matches |
index.html |
/aa/bb/cc/index.html |
.html |
Any path ending with .html |
cc/index.html |
Any path ending with cc/index.html |
/etc/resolv.conf |
Only this exact path (full-path suffix) |
/ubuntu/dists/ |
Paths ending with /ubuntu/dists/ |
Rules:
- All patterns are suffix matches, case-insensitive
- Directory paths are resolved to their index document before matching:
/foo/ is treated as /foo/index.html (per HTTP conventions). Directory patterns like /ubuntu/dists/ are normalized the same way, so they keep matching directory requests
- As a result,
/foo/ and /foo/index.html share the same cache key: caching either one makes the other a cache hit (when not excluded)
- Deprecated
excludeExtensions/excludePaths entries are converted automatically at startup (with a warning) when excludeLastPfx is not set
Example:
{
"cache": {
"excludeLastPfx": [
"/ubuntu/dists/",
"/etc/resolv.conf",
"index.html"
]
}
}
Management
View stats:
scproxy --summary
Clear cache:
scproxy --clear-cache # Interactive
scproxy --clear-cache --yes # Skip confirmation
Response headers indicate cache status:
X-Cache: HIT — Served from cache
X-Cache: MISS — Fetched from target
X-Cache: BYPASS — Not cached (excluded by policy)
Storage Structure
cache/
├── scproxy.json # Config file
└── data/
├── github.com/
│ └── releases/
│ └── file.tar.gz
└── api.example.com/
└── endpoint.json
Development
make build # Build for current platform
make build-all # Build for all platforms
make test # Run tests
make lint # Run linters
License
MIT