LynxProxy

A lightweight HTTP client proxy for personal use.

Quick start

LynxProxy reads profile configs whose schema follows Clash-style config naming. Profile files may be TOML, YAML, or JSON; the file format only changes serialization, not field names:

pnpm install
pnpm build
pnpm start

pnpm start runs the built CLI in foreground mode using the active profile. See CLI.md for the current command behavior and known CLI limitations.

Packaged CLI usage loads the active profile from ~/.config/lynx-proxy/user.json:

mkdir -p ~/.config/lynx-proxy/profile
cp config.example.toml ~/.config/lynx-proxy/profile/home.toml
printf '{\n  "profile": "home"\n}\n' > ~/.config/lynx-proxy/user.json
lynx

To load a config file as a profile, add it with lynx config add and then select it:

lynx config add home --file config.example.toml
lynx config use home
lynx

Example config shape:

port = 8080
"allow-lan" = false
"log-level" = "info"
"access-log" = true
"log-file" = "lynxproxy.log"

[[proxies]]
name = "trojan-main"
type = "trojan"
server = "proxy.example.com"
port = 443
password = "trojan-password"
sni = "proxy.example.com"
"skip-cert-verify" = false

[[proxy-groups]]
name = "🔰国外流量"
type = "select"
proxies = ["trojan-main", "DIRECT"]

rules = [
  "DOMAIN-SUFFIX,example.com,🔰国外流量",
  "MATCH,DIRECT",
]

[user]
"proxy-group" = "🔰国外流量"

[user."proxy-groups"]
"🔰国外流量" = "trojan-main"

log-level controls application logs such as startup, shutdown, warnings, and errors. access-log controls per-request access lines independently. log-file optionally appends the same enabled log lines to a file.

LynxProxy reads ~/.config/lynx-proxy/user.json and loads the selected profile from ~/.config/lynx-proxy/profile/. It also reads ~/.config/lynx-proxy/state.json when present and applies per-profile proxy-group selections. If the config directory or user config does not exist yet, LynxProxy creates them with default user config { "profile": "default" }; add a Clash-style profile such as ~/.config/lynx-proxy/profile/default.toml, default.yaml, or default.json (via lynx config add), or edit user.json to select another profile. The runtime user config is separate from the [user] table inside a profile; profile [user] can provide default proxy-group selections, while CLI changes are stored in state.json.

Config files under ~/.config/lynx-proxy/:

• user.json: selects the current profile.
• profile/<name>.toml|yaml|json: stores the Clash-style base profile.
• state.json: stores mutable per-profile state, keyed by resolved profile filename, such as selected proxy-group records.

Common CLI helpers:

lynx config path
lynx config add default --template
lynx config add home --file config.example.toml
lynx config add airport --url https://sub.example.com/link
lynx config update airport
lynx config info airport
lynx config use home
lynx config current
lynx groups select default DIRECT

Subscription profiles (Clash-style): lynx config add <name> --url <url> fetches a subscription over a direct connection (with a clash-like User-Agent, overridable via --user-agent), validates it, and saves it as a profile (default .yaml), recording the url, update time, and traffic info in state.json. lynx config update [name] re-fetches and overwrites the profile entirely — any local groups rule set edits are lost on update. If a groups select choice no longer exists in the refreshed config, the router degrades to the first resolvable group member at request time. lynx config info [name] shows the subscription url, last update time, traffic usage, and expiry. Updates require lynx proxy restart to take effect; automatic interval/cron updates are not implemented.

Proxy-group selections, the active group (groups use), and the runtime mode (groups mode) are written to state.json and resolved per request. When the daemon is running the active profile, these changes are applied live over a Unix domain socket control channel without a restart; otherwise they take effect on next start. Editing routing rules (groups rule set) still requires lynx proxy restart.

See CLI.md for the CLI command reference, and config.example.toml / DEVELOPMENT.md for the full supported schema.