macOS

Supported: macOS 10.15+ (Catalina or later), Apple Silicon and Intel.

Install

Quick install

1. Open Terminal.

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, and registers a launchd user agent that auto-starts on login.

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 — git-scm.com - make — included with Xcode Command Line Tools (xcode-select --install)

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 platform (Apple Silicon or Intel), runs make build-darwin-arm64 / make build-darwin-amd64, 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, and registers the launchd user agent.

   Optional flags:

   Flag	Description
   --no-service	Binary only — skip launchd agent 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.

Where things live

What	Path
Binary	/usr/local/bin/sotatek-proxy (or ~/.local/bin/sotatek-proxy)
Config	~/Library/Application Support/sotatek-proxy/config.yaml
Logs	~/Library/Logs/sotatek-proxy/sotatek-proxy.log
Service	~/Library/LaunchAgents/com.sotatek.proxy.plist

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 launchd agent

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. macOS defaults to zsh, so the path goes in ~/.zshrc.

Add it to the right shell rc, then reload:

case "$(basename "${SHELL:-zsh}")" in
  bash) RC="$HOME/.bash_profile" ;;
  *)    RC="$HOME/.zshrc" ;;
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

Another process holds 3817. Either free the port or change config:

lsof -i :3817            # find the holder
sotatek-proxy stop && sotatek-proxy start

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

Service won't start

sotatek-proxy logs
launchctl print gui/$UID/com.sotatek.proxy
sotatek-proxy daemon     # foreground for debugging

Connection refused on 127.0.0.1:3817

Confirm the agent is loaded:

launchctl list | grep com.sotatek.proxy
sotatek-proxy daemon     # foreground sanity check

Tip

The default install does not require admin privileges. The launchd agent runs as your user and is started automatically on login.

Uninstall

sotatek-proxy uninstall
rm /usr/local/bin/sotatek-proxy   # or ~/.local/bin/sotatek-proxy
rm -rf ~/Library/Application\ Support/sotatek-proxy
rm -rf ~/Library/Logs/sotatek-proxy