Linux

Supported: kernel 4.4+, glibc-based distros. Tested on Ubuntu 22.04+, Debian 12, Fedora 39+, Alpine 3.19+. Architectures: amd64, arm64.

Install

Quick install

1. Open a shell.

2. Run the installer:

   curl -sSL https://proxy.sotatek.works/releases/download/latest/install.sh | bash

   The script downloads the matching binary, verifies the SHA256 checksum, places it under /usr/local/bin/sotatek-proxy (or ~/.local/bin/sotatek-proxy if /usr/local/bin is not writable), seeds a default config under ~/.config/sotatek-proxy/, and registers a systemd --user unit that auto-starts on session.

3. Verify the daemon is up:

   sotatek-proxy status
   curl http://127.0.0.1:3817/_proxy/healthz

Build from source

Prerequisites

• Go 1.23+ — go.dev/dl - Git — available via your distro’s package manager (apt install git, dnf install git, etc.) - make — apt install make / dnf install make

1. Clone the repository:

   git clone https://github.com/sotatek-dev/sotatek-proxy.git
   cd sotatek-proxy

2. Build and install:

   bash scripts/install-from-source.sh

   The script detects your architecture (amd64 or arm64), runs make build-linux-amd64 / make build-linux-arm64, copies the binary to /usr/local/bin/sotatek-proxy (or ~/.local/bin/sotatek-proxy if /usr/local/bin is not writable), seeds a default config under ~/.config/sotatek-proxy/, and registers a systemd --user unit.

   Optional flags:

   Flag	Description
   --no-service	Binary only — skip systemd unit registration
   --prefix DIR	Override install directory

3. Verify the daemon is up:

   sotatek-proxy status
   curl http://127.0.0.1:3817/_proxy/healthz

Tip

To build without installing, run make build from the repo root. The binary is placed at ./dist/sotatek-proxy.

Auto-start on boot

By default, systemd --user services only start when you log in. To start on boot (e.g. headless server), enable user linger:

loginctl enable-linger $USER

Where things live

What	Path
Binary	/usr/local/bin/sotatek-proxy (or ~/.local/bin/sotatek-proxy)
Config	~/.config/sotatek-proxy/config.yaml ($XDG_CONFIG_HOME respected)
Logs	~/.local/state/sotatek-proxy/sotatek-proxy.log
Unit	~/.config/systemd/user/sotatek-proxy.service

Service commands

sotatek-proxy status      # running / stopped
sotatek-proxy start       # start now
sotatek-proxy stop        # stop now
sotatek-proxy logs        # tail last 100 lines
sotatek-proxy uninstall   # remove systemd unit

You can also use systemd directly:

systemctl --user status sotatek-proxy
journalctl --user -u sotatek-proxy -f

Troubleshooting

command not found

If sotatek-proxy status returns command not found, the binary was installed to ~/.local/bin (because /usr/local/bin was not writable) and that directory is not on your PATH.

Add it to the right shell rc, then reload:

case "$(basename "${SHELL:-bash}")" in
  zsh) RC="$HOME/.zshrc" ;;
  *)   RC="$HOME/.bashrc" ;;
esac
LINE='export PATH="$HOME/.local/bin:$PATH"'
grep -qxF "$LINE" "$RC" 2>/dev/null || echo "$LINE" >> "$RC"
source "$RC"

Or fix just the current shell (no new session needed):

export PATH="$HOME/.local/bin:$PATH"
sotatek-proxy status

Port already in use

ss -tlnp 'sport = 3817'
sotatek-proxy stop && sotatek-proxy start

Or set port: 3818 in config.yaml and restart.

Service won't start

sotatek-proxy logs
systemctl --user status sotatek-proxy
journalctl --user -u sotatek-proxy --since "10 min ago"
sotatek-proxy daemon      # foreground for debugging

Service stops on logout

Enable linger:

loginctl enable-linger $USER
loginctl show-user $USER | grep Linger

Uninstall

sotatek-proxy uninstall
rm /usr/local/bin/sotatek-proxy   # or ~/.local/bin/sotatek-proxy
rm -rf ~/.config/sotatek-proxy
rm -rf ~/.local/state/sotatek-proxy