post4 minaria2tailscaleself-hosting
Getting Aria2c Mobile Anywhere: Settings, Tailscale & RPC Reverse Proxy
Controlling your home server or NAS download queue from a phone on cellular data should be seamless. Yet setting up mobile clients for aria2c (like Aria2App on Android, Aria2 Remote on iOS, or browser-based AriaNg) frequently hits baffling brick walls.
Here is a practical guide on the architecture, the hidden traps, and the exact settings to get aria2c RPC working reliably from anywhere.
The Architecture: Why Raw 6800 is a Trap#
Standard aria2 tutorials tell you to enable --enable-rpc and forward port 6800. In a hardened server setup, this is usually wrong for two reasons:
- Binding & Collisions: Binding raw aria2c to 0.0.0.0 on port 6800 exposes unencrypted JSON-RPC to your entire subnet (or worse, the WAN). Many modern configurations bind aria2c strictly to loopback:
rpc-listen-host = 127.0.0.1
rpc-listen-port = 6800
rpc-listen-all = false
-
Reverse Proxy Layer: Instead of exposing raw aria2c, production systems run a reverse proxy (like Nginx or Caddy) on port 6801 (or under a dedicated vhost). The proxy serves both the static web UI (AriaNg) and proxies
/jsonrpccalls down to loopback. -
Secure Overlay Network: By placing your home server on a mesh VPN (such as Tailscale or WireGuard), you never need to expose ports through NAT or port-forwarding on your home router.
Why Your Mobile Setup Fails: 4 Common Traps#
Trap 1: The Port 443 / Home Assistant Hijack#
When you type your server’s MagicDNS domain (e.g. myserver.ts.net) into a mobile app or browser without specifying a port, mobile devices automatically default to HTTPS on port 443.
If your web server hosts SSL virtual hosts (such as Home Assistant, Vaultwarden, or Jellyfin) and receives an HTTPS request for an unmatched domain, Nginx falls back to its default SSL virtual host. You think you are connecting to aria2, but you land on Home Assistant!
Trap 2: Port 6800 is Closed / Localhost Only#
If your app defaults to port 6800, connections will either hang or immediately get Connection Refused. The daemon is listening on 127.0.0.1 and your host firewall drops inbound traffic to 6800.
Trap 3: Plain HTTP vs SSL Toggles#
Many aria2 mobile apps have an “SSL” toggle turned ON by default. If your reverse proxy exposes port 6801 over plain HTTP, the app will try an SSL handshake on a non-TLS port and fail silently.
Trap 4: Missing the RPC Path and Token#
Aria2 does not serve RPC at the root /. The endpoint is strictly /jsonrpc. Furthermore, modern aria2 daemons require an authentication token (--rpc-secret). Without this secret token in the JSON-RPC payload, the server returns:
{"id":"q","jsonrpc":"2.0","error":{"code":1,"message":"Unauthorized"}}
The Exact Mobile Client Configuration Matrix#
To connect your mobile app (e.g., Aria2App on Android or Aria2 Remote):
- Host / IP: Your server’s Tailscale MagicDNS name or Tailscale IP (e.g.
100.x.y.z) - Port: 6801 (or your proxy’s listening port)
- SSL / HTTPS: OFF / Disabled (Unless you explicitly terminated TLS on that port)
- RPC Path: /jsonrpc
- Authentication Method: Token / Secret
- Token:
Quick Verification with cURL#
Before troubleshooting your mobile app, test the endpoint directly from any device on your Tailnet:
A healthy server responds with:
HTTP/1.1 200 OK
{"id":"test","jsonrpc":"2.0","result":{"enabledFeatures":[...],"version":"1.37.0"}}
The Zero-Config Alternative: Mobile Browser AriaNg#
If you don’t want to install a native app, point your mobile browser directly to:
http://<tailscale-ip>:6801/
With an automated bootstrap config (config.js) rendered into the AriaNg static directory, your browser loads the full AriaNg desktop/mobile UI with the RPC host, port, and base64-encoded token already populated in localStorage. No typing tokens on a virtual keyboard required.
What the daemon actually does#
The above is the shape, and this is the implementation, because a guide without
one is a guess. The daemon is a NixOS module: services.aria2-daemon declares
rpc-listen-all = false, so aria2 only ever listens on loopback, and the RPC
port is an option rather than a constant. nginx owns the public port and serves
two things from it: the AriaNg static UI, and a /jsonrpc location proxied to
the loopback port.
The secret is rendered twice — once for aria2, once readable by the nginx user —
so the proxy can inject the token into the RPC path. That is why the browser UI
needs no per-device secret entry: the AriaNg bootstrap config is rendered with
the host, port and jsonrpc path already filled in, and the token never has to
be typed on a phone keyboard. The mobile app route still works, and still needs
the secret typed once.
Two consequences worth stating plainly:
-
Exposing port 6800 is not a shortcut, it is an exposure. If the proxy is down, the client should fail, not find an unauthenticated JSON-RPC endpoint.
-
The token lives in a sops-rendered file, not in the post, which is why every example here writes
<secret>.