HTTP Control API and Web Console
[General]
external-http-controller = 127.0.0.1:9090
external-http-secret = your-secret-token
external-http-ui = true
external-http-cors = false
Chute provides an embedded HTTP Control API and Web Console, similar to Clash and Surge dashboards. The API exposes engine status, traffic, connections, DNS, policy controls, and configuration management through REST endpoints.
Surge's http-api = <secret>@<host>:<port> is read as external-http-controller plus external-http-secret. A profile may also spell the parts separately: http-api-secret, http-api-ui and http-api-cors are read as external-http-secret, external-http-ui and external-http-cors, and http-api-web-dashboard also as external-http-ui; the configuration is saved with the external-http-* keys. http-api-tls is not supported — the controller speaks plain HTTP — and only produces a notice.
external-http-controller (Default: disabled)
external-http-controller = 127.0.0.1:9090
The requests the console keeps resident while serving are capped at 4 MB on macOS and 1 MB on iOS, tvOS and Android.
The address and port for the HTTP control server. Use 127.0.0.1 for local-only access. Binding to any non-loopback address (for example 192.168.1.5:9090) requires an explicit external-http-secret — without one the server refuses to start and logs what is missing.
A wildcard address (0.0.0.0, ::, *) counts as non-loopback for this check, because it listens on every interface — the opposite of local-only. Accepted spellings are 0.0.0.0:9090, *:9090 (the same thing) and, for IPv6, [::]:9090 — a bare :::9090 is bracketed for you; an address that cannot be parsed is reported as a configuration error instead of silently leaving the controller off. The whole of 127.0.0.0/8 counts as loopback, not just 127.0.0.1.
external-http-secret (Default: a generated token)
external-http-secret = your-secret-token
The Bearer token used for API authentication. Requests must include the header Authorization: Bearer <secret> — the token is accepted only in this header, never as a query parameter, and is compared in constant time. Authentication failures return 401 with {"ok": false, "error": {"code": "unauthorized", "message": "missing or invalid token"}}. Every data route is guarded: the /api/* paths, the Clash-compatible aliases, and the older routes that only Chute Android still serves (/status, /policies, /dns, /records and the like), which accept the token only in this header as well. Chute Android's own Remote Dashboard now uses the /api/* paths only. The Web Console's page and static assets (/, /assets/…, and on Chute Android also /ui) need no token (with external-http-ui = false they are gone altogether — the page is a 404).
When the key is absent, Chute generates a token instead of serving without authentication. The generated token is written to a control-token file in Chute's share folder — not beside the configuration: the app-group container on iOS and tvOS, the app's private data directory on Android — with owner-only permissions, is reused across restarts, and the apps show it to you — see the console entry points. The control API can hand out the connection database, whose records carry every URL, header and process name the run has seen, so an open controller is not a reasonable default.
To serve without authentication anyway, say so in the configuration:
external-http-secret = none
That is accepted only on a loopback bind. Off loopback, neither none nor an absent key is enough: the controller refuses to start and says what it wants.
Upgrading: if you relied on an absent
external-http-secretmeaning "no authentication", local scripts start receiving401. Either read the generated token out of the app, or writeexternal-http-secret = noneto keep the old behaviour deliberately.
external-http-ui (Default: true)
external-http-ui = true
When enabled, Chute serves an embedded Web Console at the controller address. The Web Console provides an overview, connection management, DNS inspection, traffic monitoring, policy controls, and configuration editing. Set to false to keep the API enabled while disabling the UI.
Opening the web console
The console is served at the controller's address, and each app can hand you the address and the token — including the generated one, which you would otherwise have no way to read:
- Chute Mac: menu bar → Open Web Console, and Copy Web Console Token. A connection's detail window also has Requests & History, which opens the console — its home page, not that connection.
- Chute iOS: Control Panel → the Web Console row → Open, Copy Address, or Copy Access Token.
- Chute tvOS: the control panel has a separate Web Console Address row, showing host and port. Selecting it shows a QR code when the listener is reachable from other devices — the sign-in token travels inside the code, not on the screen — and, when the controller is bound to loopback, an explanation instead, because a loopback console cannot be opened from a phone.
- Chute Android: Control Panel → Web Console Address → Open or Copy Address, and a Generated access token row that copies on tap. Neither row appears when the token is a secret you configured yourself, which is never displayed.
The address these produce carries the token as a query parameter. The page consumes it on load and removes it from the address bar, so opening the link is a complete sign-in and nobody has to transcribe 32 hex characters.
external-http-cors (Default: false)
external-http-cors = true
Enable CORS (Cross-Origin Resource Sharing) headers on API responses. Useful when the Web Console or third-party tools need to access the API from a different origin.
API Endpoints:
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/status |
Runtime status, ports, uptime |
GET |
/api/traffic |
Global and per-policy traffic counters |
GET |
/api/connections |
Current active connections |
DELETE |
/api/connections/:id |
Close a connection |
GET |
/api/connections/history |
Historical connection records |
GET |
/api/connections/processes |
Per-process connection statistics |
GET |
/api/connections/:id/request |
Captured request data for a connection |
GET |
/api/connections/:id/response |
Captured response data for a connection |
GET |
/api/dns |
DNS cache records |
DELETE |
/api/dns/cache |
Purge DNS cache |
DELETE |
/api/dns/records/:domain |
Remove a single DNS record |
GET |
/api/config |
Current configuration |
PUT |
/api/config |
Reload configuration |
POST |
/api/config/validate |
Parse a configuration and report its errors, without loading it |
GET |
/api/policies |
Policy groups and current selection; every entry carries hidden, which is true for a group marked hidden=true |
PUT |
/api/policies/:group |
Change policy group selection |
PUT |
/api/mode |
Set outbound mode |
GET |
/api/features |
Feature switch states |
PUT |
/api/features/mitm |
Toggle MitM |
PUT |
/api/features/record-traffic |
Toggle traffic recording |
GET |
/api/rules |
The rule table the matcher walks, where each rule came from, and which rewrite rules have fired |
POST |
/api/rules/match |
Where a request would be routed, without making it |
GET |
/api/rules/user |
Rules added at run time, matched ahead of the modules and the configuration |
PUT |
/api/rules/user |
Replace the run-time rules |
POST |
/api/rules/user |
Add rules behind the run-time rules |
DELETE |
/api/rules/user |
Remove every run-time rule |
GET |
/api/logs |
Recent log entries |
GET |
/api/loglevel |
Current log level, and the sections being written |
PUT |
/api/loglevel |
Change the log level or sections without restarting |
GET |
/api/health |
Engine health: refusals, generations, footprint, previous exit |
GET |
/api/events |
Notable moments of this run |
GET |
/api/tailscale |
Live Tailscale engine state |
GET |
/api/scripts |
The generic scripts that can be run on demand |
POST |
/api/scripts/run |
Run one generic script by name |
POST |
/api/diagnostics/ping |
ICMP or TCP reachability probe |
POST |
/api/diagnostics/dns-query |
Resolve a domain through the running resolver |
POST |
/api/diagnostics/egress-probe |
Check the address: this device's own on the Apple engines; on Android, the device's public address on its physical network, not a proxy's exit |
POST |
/api/diagnostics/internet-test |
The direct Internet test: fetch internet-test-url without a proxy |
POST |
/api/diagnostics/url-test/:policy |
Run a policy's latency test |
POST |
/api/diagnostics/bundle |
Build a redacted diagnostic archive |
GET |
/api/connections/export |
Export connections as HAR 1.2 |
GET |
/api/rewrites |
Every rewrite/Mock Response family, plus the MitM host list |
GET |
/api/rewrites/:family |
One family's rules |
POST |
/api/rewrites/:family |
Add a rule |
DELETE |
/api/rewrites/:family/:id |
Remove a rule |
DELETE |
/api/rewrites/:family |
Clear a family |
GET |
/api/mitm/hosts |
Hosts currently decrypted |
POST |
/api/mitm/hosts |
Add a host |
DELETE |
/api/mitm/hosts/:host |
Remove a host |
DELETE |
/api/mitm/hosts |
Clear the list |
GET |
/api/rules/providers |
Rule providers and rule sets, with the status of each — including why one did not load |
Endpoint notes:
GET /api/featuresreports each switch as it is set —record_traffic,mitm,mitm_h2,mitm_auto_quic_block,rewrite— andlicensed.effectivesays what actually runs, for five items only:record_traffic,mitm,rewrite,scriptsandlan_proxy. On the free edition all five are false, so a switch can read on while itseffectiveentry is false.inactiveis an object naming what the running configuration asks for that does not run in this edition: the countsscripts,scriptRules,dnsScripts,rewritesandmapLocals, and the flagsmitm,bodyCapture,lanProxyandexitNode(Tailscale advertising, which only Chute Mac does). With a license, or while the engine is stopped, every count is 0 and every flag false.GET /api/connectionsacceptslimit(positive integer, default and maximum 1000) andcursor(returns only connections withidgreater than the cursor). The responsedatacarriesconnections,total,page_size,has_more,server_time, and — when more pages exist —next_cursor.since(seconds, theserver_timeof an earlier answer) returns only the connections that changed after that moment, and addsactive_ids, the ids of every connection open now: one that an earlier answer had and that is missing from them has closed. Asincelater thanserver_timeis taken as0, so every connection is returned.GET /api/connections/historyacceptslimit(default 100, maximum 1000) andcursor/before(synonyms; passing both is rejected).GET /api/connections/:id/requestand.../responsereturn{"connection_id": <id>, "data": "<base64>"}. Captures larger than 2 MiB return413. Without Chute Pro both return403, withrequest data is not availableorresponse data is not available, for bodies recorded during an earlier licensed run as well.GET /api/configreturns the running configuration as written, credentials included —http-auth,external-http-secret,ca-p12,ca-passphrase, WireGuard keys and every proxy's password — so access to the control API is access to all of them. Only a diagnostic bundle replaces credentials with<redacted>, and that copy cannot be loaded back: a configuration sent toPUT /api/configthat still says<redacted>anywhere is refused with400and a message naming the first such line. Submit the original configuration instead.GETandPUT /api/configare also reachable as/api/configs, and as the Clash alias/configs.PUT /api/configaccepts either JSON{"configuration": "<full text>"}or the raw configuration text as the request body (1 MB limit). On success the engine reloads — or starts, if it was not running.PUT /api/policies/:grouptakes the selection from the first of the body keyspolicy,name,selected,select; the value may be a policy name or a numeric index as a string. The special group nameGLOBALsets the global selected policy.- In
GET /api/policies, every policy, group and group member carriesendpoint, the policy it leads to now — followed through groups, and through the built-inPROXYto the policy selected for Global mode — andendpoint_ping, that policy's latency. A group's ownpingis0, not measured, soendpoint_pingis the figure to read for a group or forPROXY. PUT /api/moderequires a JSON number:{"mode": 0}—0rule,1direct,2proxy.PUT /api/features/mitmandPUT /api/features/record-traffictake{"enabled": true}.GET /api/logsacceptssince(Unix seconds); the in-memory buffer keeps the most recent 1000 entries, each{timestamp, wall_time, level, section, message}—timestampandwall_timecarry the same Unix-seconds value, nudged forward when the clock does not advance so entries stay strictly ordered.GET /api/healthreports what the engine is holding and why it last refused something, plus how the previous run ended (clean,unclean, orsuspected_memory— see Troubleshooting).addressFamilysays how Chute judges the IPv6 way out —ipv6ishealthy,confirmingordegraded— with counts of what it has done about it; on the Apple enginesselfLoopreports the self-loop guard. Neither carries an address.GET /api/eventsserves the in-memory ring;?persisted=1reads this run's stored history instead, and answersavailable: falsewhen record keeping is off.GET /api/tailscaleanswersstate: "idle"when no[Tailscale]section is configured — that is a normal answer, not an error.- The
POST /api/diagnostics/*probes take their arguments from the query string or a JSON body, are bounded to ten seconds, and answer exactly once.url-test/:policyrejects a policy name that is not defined rather than measuringREJECT. GET /api/scriptslists the enabled generic scripts as{name, type};POST /api/scripts/runtakesnamefrom the body or the query string, is bounded like the diagnostics probes, and answers{name, timedOut, result}—timedOuttells a script that never called$doneapart from one that ran to completion. A name that is not an enabled generic script is a404. Without Chute Pro it answers403,script is not available.POST /api/rules/matchanswers where a request would go, without opening a connection. It takeshost(or aurlto take the host and port from; aURL-REGEXrule is tested against thaturlexactly as written, although in real traffic it only ever sees plainhttp://requests),port(default 443), and optionalip,protocol,process,process_path,src_ip,src_port,in_port,in_type,in_user,in_name,network,ssid,bssid,from_tun,user_agent— an unknown field is refused with the accepted list rather than ignored. The reply carries thematchedrule (its line, type, the policy it names and theresolved_policya group currently points at), thepolicy,need_resolve, and therule_countandmatch_generationthe answer was computed against. Because a domain is matched twice — once on the name and again once an address is known —passesholds one entry per pass; without aniponly the pre-resolution pass exists and the reply says so innote. Addexplain=truefor the candidate rules that could also have matched, up to 50, with a count of the rule sets that were not expanded.POST /api/config/validateparses a configuration and throws it away: the running engine adopts nothing. Send it as{"configuration": "<full text>"}or as the raw text. The reply isvalid,error_count,advisory_count,rule_count,policy_countand anerrorslist of{line, severity, content, error}—severityseparates a line that was refused from one accepted with a caveat, andcontentis the offending line as written — credentials included, since a bad[Proxy]line is often bad in the very field that holds its password — cut at 4096 characters. Use it beforePUT /api/config, which restarts the run you are debugging.GET /api/loglevelreports the currentlevel, thenslog_level, thesectionsbeing written to file, and theavailable_levels/available_sectionsyou may set.PUT(orPATCH) takeslevel,sections, or both:sectionsis an array of section names or the string"all", and an empty array is refused — to stop logging uselevelnone. Changing the level this way does not restart the run, which is the point:loglevel = verbosein the file needs a reload, and a reload loses the thing you were trying to see.GET /api/rulesalso reportsrewrite_hits— every rewrite or Mock Response rule that has fired this run, with a count. A rule that does not appear there has never matched, which is the usual explanation for a rewrite that seems to do nothing. The table tracks up to 512 distinct rules and reportsrewrite_hit_dropped_rulesfor any beyond that.ruleslists every rule the matcher walks, in order: the automatic Tailscale rules, then the rules added through/api/rules/user, then module rules, then the configuration's[Rule]section, ending withFINAL;rule_regionsnames each line's origin, index for index (front,user,module,configuration)./api/rules/userholds rules added while the engine runs, without a reload and without touching the configuration file. They are matched after the automatic Tailscale rules and ahead of module rules and the configuration's[Rule]section, in the order given.GETlists them;PUTreplaces them andPOSTadds behind the ones there, both taking{"rules": ["<rule line>", ...]}or a single{"rule": "<rule line>"}, written as in the file;DELETEremoves them all. A write is all or nothing: a line that does not parse, or aFINAL, is refused with400and the rules stay as they were. A rule whose policy the running configuration does not define is taken — it fails closed withREJECT— and named inwarnings.close_rerouted,trueby default, closes the connections the changed rules route elsewhere, and only those;falseleaves every connection open — onDELETEpass it as?close_rerouted=false. Every method answers with the currentrules. The rules are kept through a reload and are gone when the engine stops.PATCHis not accepted on this path.POST /api/rewrites/:familytakes{"rule": "<configuration line>"}— the same text you would write in the file. A line that does not parse is refused with400rather than stored as a rule that can never match.:familyis one ofurl-rewrite,header-rewrite,body-rewrite,mock. Rules added this way live in the running engine and are not written back to the configuration file.GET /api/connections/export?format=harreturns a HAR 1.2 document, andPOST /api/diagnostics/bundlereturns a zip — both are files, so unlike every other endpoint they are not wrapped in the{"ok": ..., "data": ...}envelope.exportacceptssource(current, the default, orhistory),limit(default 100, maximum 300),ids, andbodies=1to include the captured payloads. Each entry carries a_klobject with what HAR has no field for: the chosen policy, the matched rule, and the rewrites that fired.- A chained connection's record in
GET /api/connectionsandGET /api/connections/historycarrieschainPath, the path from this device to the exit, as inAirport/HK-01 → Landing; it is empty for a connection that used a single policy, and the HAR export carries it as_kl.chain. In the per-policy counters ofGET /api/traffic, an upstream also counts the bytes it carried for chained connections; the global totals count them once.
Example — read the status, then switch a policy group:
curl -H "Authorization: Bearer your-secret-token" http://127.0.0.1:9090/api/status
{"ok":true,"data":{"running":true,"outbound_mode":0,"mitm":false, ...}}
curl -X PUT -H "Authorization: Bearer your-secret-token" \
-d '{"policy": "ProxyB"}' http://127.0.0.1:9090/api/policies/MainGroup
{"ok":true,"data":{"outbound_mode":0,"selectable_groups":[...], ...}}
Example — ask where a request would go, before making it:
curl -X POST -H "Authorization: Bearer your-secret-token" \
-d '{"url": "https://api.example.com/v1/orders", "explain": true}' \
http://127.0.0.1:9090/api/rules/match
{"ok":true,"data":{"policy":"MainGroup","matched":{"rule":"DOMAIN-SUFFIX,example.com,MainGroup", ...}, ...}}
Narrow the log to one subsystem while reproducing, without restarting the run:
curl -X PUT -H "Authorization: Bearer your-secret-token" \
-d '{"level": "verbose", "sections": ["MitM", "DNS"]}' \
http://127.0.0.1:9090/api/loglevel
Note: This feature is disabled by default. Every response uses the envelope
{"ok": true, "data": {...}}on success and{"ok": false, "error": {"code": "...", "message": "..."}}on errors; request bodies are limited to 1 MB.
PUTendpoints also acceptPATCH. Clash-compatible alias paths are available for third-party dashboards:/version,/traffic,/connections,/configs,/proxies,/rules— the paths are reachable, but responses use Chute's envelope and field names rather than Clash's schema (/versionreturns{"name", "run_id", "egress_probe"}, whereegress_probeisnetwork_addresson the Apple engines andegress_ipon Android), so Clash dashboards will not work out of the box.