Getting Started on Android

Chute Android runs the same engine as the other editions, ported to Kotlin, and reads the same configuration file. This page walks through the first run; Getting Started has the equivalent for iOS, macOS and tvOS, and the minimal configuration shown there works on Android unchanged.

1. Get a configuration

On the first launch with no configurations, Chute opens a setup wizard ("Let's set up your first proxy configuration") with three paths: a subscription URL from your provider, a QR code, or your own server details followed by the sites to proxy and a DNS choice. Its last step, Create and Connect, saves the configuration, selects it and starts the tunnel. Skip closes the wizard; as long as there is still no configuration, it opens again the next time Chute is launched, but not when the screen rotates or you return to the app. Show Onboarding in Settings opens the wizard again.

The subscription URL has to be an https:// address. A native profile the wizard downloads — from that URL, or from an address a QR code carries — is kept as a managed configuration refreshed every 86400 seconds, the default of Add Subscription below. A Clash or sing-box profile, whether it comes from the subscription or from a QR code, is converted into a static snapshot that is not refreshed, as on the Configurations page. The QR code is read as that page reads one: a chute://download link (or import, install-config, subscribe) is the address to download, a code may carry a whole configuration, and a chute://tv or chute://remote code opens the main screen's remote repository dialog.

To add a configuration later, tap the Config bar on the main screen to open Configurations, then Add Configuration From...:

• Blank Configuration — saves a template as Untitled.conf without opening the editor; open it with Edit Structured or Edit Text from the row's ⋮ menu.
• Add Subscription — downloads a provider URL and keeps it as a managed configuration, refreshed at the interval you type in the dialog (86400 seconds by default). A Clash or sing-box subscription is converted on the way in and stored as a static snapshot with no update header, so it does not refresh itself.
• Import from Local File — imports a Chute (.conf), sing-box (.json) or Clash/mihomo (.yaml) file; non-native formats are converted.
• Download From URL, Download From QR Code, Upload File Via Wi-Fi — additional transports for the same thing. The Wi-Fi upload page lists the addresses to open in a browser on the same network, protected by a PIN.
• Remote Server — loads a configuration from a remote configuration repository.

A chute://download?url=... link opened from outside the app — tapped, or scanned with the camera — downloads the file too, and a Clash or sing-box profile is converted into a static snapshot as on the Configurations page, but the link adds no subscription: chute://subscribe?url=... is only an alias of download. The app never refreshes a native profile such a link saves, although a running engine re-fetches its URL every 24 hours and applies the new content in memory — see URL Scheme. Scanned in the setup wizard instead, the same link to a native profile gives a managed configuration that the app refreshes every 86400 seconds.

Without a license Chute keeps a single local configuration; adding a second one through any channel is a Chute Pro feature — see License and Activation.

2. Select it

On the Configurations page, tap a configuration so it is marked Pending, then tap Done: that is the configuration Chute runs. One you have just added there comes back already marked Pending, and so does one that a chute:// link opened from outside the app added: Chute opens this page with it marked, and nothing changes until you tap Done — such a link never switches the configuration Chute is running. The selected configuration can be switched while Chute is running, licensed or not; the new one is applied by restarting the tunnel.

3. Start and authorize

Tap the switch (Tap to start VPN). On the first start Android asks you to allow the VPN connection request — the system consent every VPN app needs; declining it leaves Chute stopped. Two settings decide what the tunnel carries:

• Service Mode — VPN (default) captures the device's traffic through a system VPN; Local Proxy runs only the HTTP and SOCKS5 listeners for other apps or devices to point at, with no tunnel.
• Application Proxy Mode — Global routes every app, Proxy only the selected apps, Blacklist every app except the selected ones.

Related switches in Settings: Start on Boot (needs the VPN consent granted once), Restrict to Wi-Fi (VPN mode only: pauses the tunnel when the underlying network is metered and resumes when it is not — that is what Android reports, not the transport, so a metered Wi-Fi also pauses and an unmetered cellular plan does not), and Always-on VPN, which opens Android's VPN list, since the always-on page itself is not a public destination; turn Always-on VPN on for Chute from there. From outside the app, the Start, Stop and Toggle home-screen shortcuts, broadcast intents and a Tasker/Locale plugin start and stop the tunnel, and so does the Quick Settings tile — unless Quick Actions in Settings switches it from VPN to Mode (cycle the outbound mode) or Group (cycle the policy group chosen under Widget Group, which lists no group marked hidden=true other than the one already chosen). A home-screen widget shows whether the tunnel runs and that group's policy; tapping it moves the group to its next policy.

With Always-on VPN on, Android starts the tunnel itself — when the setting is turned on, at boot and after Chute is updated — with the selected configuration, and always as a VPN, even when Service Mode is Local Proxy. Apart from that, if Android kills Chute's process while the VPN runs, the tunnel comes back by itself on the selected configuration, unless you had stopped it, disconnected it in Android's VPN settings or given the VPN permission to another app. The same holds in Local Proxy mode: listeners that were running come back, unless you had stopped them — although Android 12 and later may refuse to restart them while Chute is in the background, and the start is then reported as failed.

4. Verify

Leave the outbound mode on Rule (the Direct / Global modes bypass or force the proxy wholesale), then open a website. Dashboard on the main screen shows live traffic in its Statistics, Tunnels, DNS, UDP and Logs tabs; a tunnel opens into its request and response detail. Control Panel holds the runtime switches — the local HTTP and SOCKS5 listeners, the HTTP Control API and Web Console, MitM, Traffic Capture, Protocol Sniffing, Optimus DNS — plus Purge DNS Cache and the Runtime Diagnostic Bundle.

Platform differences

• Process rules match package names. PROCESS-NAME compares against the package name of the app that opened the connection, for example PROCESS-NAME,com.android.chrome,Proxy; Chute asks Android which app owns each TCP connection the VPN interface carries. Connections that reach the listeners instead — all of them in Local Proxy mode, and those of apps using the System HTTP Proxy — have no package name, so the rule never matches them.
• HTTPS decryption needs your own CA. There is no certificate generator: on the editor's Configure CA page, under MitM, Import P12 writes a PKCS#12 into the configuration's ca-p12, base64-encoded as Chute writes it on Apple devices, so the configuration carries its CA to any device; once the passphrase is filled in, Install CA opens Android's certificate installer for its CA certificate. The editor page is not licensed, but the engine is: without Chute Pro nothing is decrypted, whatever a profile's [MITM] enable = true asks for, and the MitM runtime toggle in the Control Panel and on the Dashboard is gated as well.
• SSID-based features work — ssid policy groups, SUBNET rules and [SSID Setting] — given the location (Android 12 and earlier) or nearby Wi-Fi devices (Android 13 and later) permission the system requires to read the network name. Chute asks for that permission when you start with the main switch and the configuration has an ssid or subnet policy group, a SUBNET,SSID: or SUBNET,BSSID: rule, or an [SSID Setting] / [SSID Suspend] section. A start that cannot show the request — the Quick Settings tile, a shortcut, Start on Boot, a broadcast, Always-on VPN — posts an SSID Permission Needed notification instead, once per configuration, and tapping it asks. The engine reads the network again every minute, so a grant takes effect within a minute, without a restart. SUBNET rules inside an external rule set are not seen: if that is where they are, grant the permission from the system settings. In VPN mode the suspend entry of SSID Suspend takes the VPN interface down while the device is on a matching network; Local Proxy mode ignores it.
• Tailscale is available; the editor has a Tailscale page for it.
• Platform directives — #!IOS-ONLY, #!MACOS-ONLY and #!TVOS-ONLY lines are comments here, so none of them apply on Android.
• Trojan lines from older versions. A Trojan policy needs an explicit tls=true on every platform. Older versions of Chute Android assumed TLS for Trojan, and their editor did not write the option by default, so the first launch after the update adds tls=true to each Trojan policy that names no tls option in your local configurations, and records every change in the app's service log. A managed configuration is left alone — its source replaces it — and so is a line that says tls=false.
• Two logs. The engine's log stays in memory: read it on the Web Console's Logs page or with GET /api/logs, take it away in the Runtime Diagnostic Bundle (Control Panel, while the tunnel runs), or follow it with adb logcat. The app writes only its own service log to disk — starts and stops, suspensions, network changes, the notifications it posts — in logs/runtime.log in its private storage, with a per-run copy under sessions/<run id>/. The Dashboard's Logs tab shows the last 80 lines of that file and a session's Log tab shows its run's copy; Save Offline Diagnostic Bundle under Settings → DIAGNOSE carries the file, and Clean Local Logs in Settings deletes it but not the per-run copies — see Troubleshooting.
• Chute Dashboard on a Mac connects to the phone over USB through adb, or over the network — see Chute Dashboard.
• Notifications cover the same engine events as the other apps (Settings → Notifications); Network Not Carrying Traffic follows the Mass Connection Failure switch. They are posted in VPN mode only: Local Proxy mode raises no engine-event notification.
• Not on Android: the Mac-only Enhanced Mode and VIF, iCloud sync, and the chute://start / stop / toggle URL actions — see URL Scheme for the broadcast intents that replace them. A broadcast cannot raise the VPN consent dialog, so START_VPN is dropped in silence until consent has been granted once; TOGGLE_VPN opens the app instead, where tapping the switch raises it, and Local Proxy mode needs no consent at all.