Install stellar-helper from the command line

The desktop app already bundles stellar-helper inside it. This page is for the standalone stellar-helper binary — useful on servers, in dev environments, on Linux desktops without a GUI, or whenever you'd rather operate everything from a terminal.

All commands below assume stellar-helper is on your $PATH. Pick the install line that matches your platform, then jump to Login.

macOS

curl -L -o stellar-helper.tar.gz \
  https://apps.stellar.international/stellar-helper-8.3.1-darwin-universal.tar.gz
tar xzf stellar-helper.tar.gz
sudo install -m 0755 stellar-helper /usr/local/bin/stellar-helper
# Gatekeeper-strip (the binary is not notarized):
sudo xattr -dr com.apple.quarantine /usr/local/bin/stellar-helper

Linux

# Pick arm64 or amd64 to match your host.
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -L -o stellar-helper.tar.gz \
  "https://apps.stellar.international/stellar-helper-8.3.1-linux-${ARCH}.tar.gz"
tar xzf stellar-helper.tar.gz
sudo install -m 0755 stellar-helper /usr/local/bin/stellar-helper

Windows (PowerShell)

Invoke-WebRequest `
  https://apps.stellar.international/stellar-helper-8.3.1-windows-amd64.zip `
  -OutFile stellar-helper.zip
Expand-Archive stellar-helper.zip -DestinationPath C:\Stellar
$env:Path += ';C:\Stellar'

You'll want to add C:\Stellar to your system Path via System Properties for it to stick across sessions.

First run

1. Login

stellar-helper login

You'll be prompted for your account credentials (same as the desktop app). The token is cached so you only do this once per machine.

2. Pick a line

List the lines available on your plan:

stellar-helper lines
Available lines:
  0: 香港-广州-1
  1: 台北-GIA
  2: 上海-首尔
  ...

Pick one by index (no need to know its technical name):

sudo stellar-helper connect --lineIndex 0 --computerMode off -p allowlist

Or omit --lineIndex to be prompted interactively:

sudo stellar-helper connect --computerMode off -p allowlist
Available lines:
  0: 香港-广州-1
  1: 台北-GIA
  ...
Enter the line index:

The process stays in the foreground; it prints export commands so you can route a shell session through it:

export http_proxy=http://127.0.0.1:8668
export https_proxy=http://127.0.0.1:8668
# or, for socks-aware tools:
export http_proxy=socks5://127.0.0.1:1080

--computerMode off keeps things at the user-space proxy level (HTTP on :8668, SOCKS5 on :1080). Set --computerMode global or allowlist to route the whole machine via the TUN device.

3. Inspect the running tunnel

Once stellar-helper connect is up, open a second terminal and talk to it over its Unix socket:

stellar-helper ctl ping              # → pong
stellar-helper ctl state             # human-readable status
stellar-helper ctl state --json      # pipe to jq
stellar-helper ctl set-timeout 0     # disable the 5-minute auto-stop

4. Disconnect

Just Ctrl-C the foreground connect — that releases the routes and shuts the listeners. If you want it gone without TTY access:

sudo pkill stellar-helper

Tips

  • Run with --log verbose if anything misbehaves and inspect the output.
  • The system-wide proxy modes (--computerMode global/allowlist) need sudo because they manage routes and TUN devices.
  • The pure HTTP/SOCKS modes (--no-routes) only need user-space ports and don't touch system routing — handy on shared machines.
  • stellar-helper ctl --help lists every read/write the daemon exposes — handy as a kubectl-style operator interface for the local tunnel.