Linux

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

One daemon per machine

On Linux, sotatek-proxy installs as a machine-wide systemd service running as a dedicated sotatek-proxy system user. A single daemon on 127.0.0.1:3817 serves every user account on the box — so switching users no longer conflicts over the port. Install and service commands require sudo.

Install

Quick install

1. Open a shell.

2. Run the installer:

   curl -sSL https://proxy.sotatek.works/releases/download/latest/install.sh | bash
   export PATH="$HOME/.local/bin:$PATH" && hash -r

   The script downloads the matching binary, verifies the SHA256 checksum, places it under /usr/local/bin/sotatek-proxy, and registers the machine-wide systemd service (it will ask for sudo at that step). The service starts immediately and on boot.

3. Verify the daemon is up:

   sudo 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, and registers the machine-wide systemd service (asks for sudo).

   Optional flags:

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

3. Verify the daemon is up:

   sudo 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.

Upgrading from an older per-user install

Older versions registered a per-user systemd --user unit. The installer removes your old unit automatically. If another user on the machine still has one running, it holds port 3817 and the install is blocked with a message naming that user. Stop theirs first:

sudo -u <user> systemctl --user disable --now sotatek-proxy
sudo sotatek-proxy install

User linger (loginctl enable-linger) is no longer needed — the system service starts at boot.

How attribution works

The daemon identifies the process that made each request, reads its working directory, and runs git remote -v dropped to that user’s own uid — so it reads each user’s repository with that user’s permissions, never with elevated privileges. The result is sent upstream as X-Git-Remote.

To make this possible the service holds CAP_SYS_PTRACE, CAP_SETUID and CAP_SETGID, and runs sandboxed (NoNewPrivileges, ProtectSystem=strict, ProtectHome=read-only) as a non-root system user.

Where things live

What	Path
Binary	/usr/local/bin/sotatek-proxy
Config	/etc/sotatek-proxy/config.yaml (optional)
Logs	/var/log/sotatek-proxy/sotatek-proxy.log
Unit	/etc/systemd/system/sotatek-proxy.service
Runs as	system user sotatek-proxy (nologin)

Service commands

sudo sotatek-proxy status      # running / stopped
sudo sotatek-proxy start       # start now
sudo sotatek-proxy stop        # stop now (stays stopped across reboot)
sotatek-proxy logs             # tail last 100 lines
sudo sotatek-proxy uninstall   # remove service, system user, config and logs

You can also use systemd directly:

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

Without systemd (containers, WSL, Alpine)

Where systemd or useradd is unavailable, service installation is not supported. Run the proxy in the foreground instead — it falls back to per-user paths (~/.config/sotatek-proxy/config.yaml, ~/.local/state/sotatek-proxy/) and needs no root:

sotatek-proxy daemon

Troubleshooting

command not found

If sotatek-proxy status returns command not found, /usr/local/bin 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="/usr/local/bin:$PATH"'
grep -qxF "$LINE" "$RC" 2>/dev/null || echo "$LINE" >> "$RC"
source "$RC"

Port already in use

Another process — usually an old per-user sotatek-proxy belonging to a different user — holds 3817. Find the owner:

sudo ss -tlnp 'sport = 3817'

Stop that user’s old unit, then start the system service:

sudo -u <user> systemctl --user disable --now sotatek-proxy
sudo sotatek-proxy start

The daemon does not crash-loop on a busy port: it logs the owning user and exits, so journalctl -u sotatek-proxy shows exactly who holds it.

Service won't start

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

X-Git-Remote missing

If requests reach the upstream without repository attribution, the service’s capabilities are likely not effective (hardened kernel, container without the caps, MAC policy). The daemon logs this at startup:

journalctl -u sotatek-proxy | grep -i "capability self-test"

Requests still work — only the attribution header is dropped.

Uninstall

Caution

uninstall is destructive on Linux: it removes the service, the sotatek-proxy system user, and both /etc/sotatek-proxy and /var/log/sotatek-proxy (including log history). Copy any logs you want to keep first.

sudo sotatek-proxy uninstall
sudo rm /usr/local/bin/sotatek-proxy