Skip to content

Background service

The service installs Tegvia as a per-user background service (no administrator rights, no sudo). It starts the proxy when you log in, restarts it if it stops unexpectedly, and is driven by a single command on Linux, WSL, macOS and Windows. It is the default way to run Tegvia; to run it only while a window stays open, see the standalone launcher.

System Mechanism Definition
Linux, WSL systemd --user unit ~/.config/systemd/user/tegvia.service
macOS LaunchAgent ~/Library/LaunchAgents/io.tegvia.proxy.plist
Windows Task Scheduler task, trigger "at log on" task Tegvia of your account

While it runs, the service points ~/.claude/settings.json at the proxy (env.ANTHROPIC_BASE_URL) and removes that redirect again every time the proxy stops, so your previous value is always restored.

Received Tegvia as a zip file? See Installation from an archive.

Prerequisites

  • Python 3.11 or newer (see Installation). The dependencies are installed on the first install into a .deps/ folder inside the Tegvia folder (network access to PyPI needed).
  • Port 8736 (the default) free on 127.0.0.1, unless it is already the Tegvia service. If 8736 is taken, pick another port with --port.
  • Linux and WSL: a working systemd user manager (see WSL).
  • Windows: paths (Python and Tegvia folder) must not contain % or a double quote "; install refuses them. On all systems, install also refuses a relative Python or Tegvia folder path (rare).

Install

From the Tegvia folder (it works from any current folder):

System Command
Linux, WSL, macOS ./install.sh (or sh install.sh)
Windows install.cmd (double-click, or from cmd.exe)

install asks no question. It checks Python and the port, installs the dependencies if needed, writes the service definition, starts the service and waits up to 15 seconds for the proxy to answer. It then prints the web console URL (http://127.0.0.1:<port>/tegvia/ui/, 8736 unless you chose another port) and the log locations. If the proxy does not answer in time, it prints the end of proxy.stderr.log and exits with a non-zero code. On Linux, WSL and macOS, install (and restart) only report success if the proxy answers and the service manager reports the service as running.

Add --dry-run to see what would be written without changing anything: ./install.sh --dry-run (the port that would be used is shown too).

Choosing the port

By default the service listens on port 8736. To use another port, add --port N (a whole number from 1024 to 65535):

./install.sh --port 9123
install.cmd --port 9123

install picks the port in this order, and prints a Port: line with the value and where it came from:

  1. --port N;
  2. the TEGVIA_PORT environment variable, if it holds a valid port;
  3. the port of the previous install (so a plain install run again keeps your port);
  4. the default, 8736.

  5. A --port outside 1024-65535, or not a number, is refused with a usage message and exit code 2.

  6. If you give --port and a different TEGVIA_PORT, install refuses (exit code 3) with a message naming both values. Remove one or make them equal.
  7. A TEGVIA_PORT that is not a valid port is ignored, with a one-line notice, and the choice falls to the next rule.

Changing the port later: run install --port N again. The service is restarted on the new port, ~/.claude/settings.json is updated to point at it and the redirect to the old port is removed. Restart Claude Code afterwards. Installing again with --port 8736 brings the service back to the default port. status shows the installed port (a Port: line, port in the JSON), and the other commands (start, stop, restart, uninstall) always act on the port of the installed service.

install also sets up the tray icon (autostart entry at login, and the icon is started right away). Add --no-tray to install the service only: ./install.sh --no-tray (install.cmd --no-tray). A problem with the icon (unsupported system, GNOME without the AppIndicator extension, WSL...) is printed but never changes the exit code, and the service is installed regardless.

When you change the port with --no-tray, the icon's autostart entry keeps the old port (it is not updated). Reinstall without --no-tray to bring the icon to the new port.

What you see at the end, and install.log

install and uninstall end with one summary line:

  • Tegvia installed.
  • Tegvia installed, but the tray icon reported a problem (see above). (the service is installed; only the icon failed)
  • Installation failed (see above).
  • Dry run finished; nothing was changed. (with --dry-run)
  • Tegvia removed., Tegvia removed, but the tray icon reported a problem (see above). or Uninstall failed (see above). (for uninstall)

Everything printed by the command is also recorded in install.log, and the summary line ends with Install log: <path>. The file is in the state folder of the data folder: ~/.tegvia/state/install.log on Linux, WSL and macOS, %USERPROFILE%\.tegvia\state\install.log on Windows (under TEGVIA_HOME if you set it). Each run adds a block starting with a header line (date, command, system, Python, Tegvia folder, version) and ending with a line === exit <code>: ... ===. The file holds no secrets (only what was displayed, plus the header), is readable by you only on Linux, WSL and macOS, and is kept small (when it exceeds about 1 MiB the oldest part is dropped; one run records at most 256 KiB). If the log cannot be written, a warning is printed and the installation goes on unaffected.

On Windows, install.cmd and uninstall.cmd keep the window open after the summary: it shows Press Enter to close this window. so you can read the result when you started it by double-click.

Running install twice just updates the definition: nothing is duplicated. Tegvia never overwrites a definition it did not generate (a file or task with the same name but without Tegvia's marker): it refuses and tells you.

Restart Claude Code after the first install so that new sessions read the redirect.

If you set TEGVIA_HOME (an absolute path) before install, the service records it. On Windows, the task does not see a variable set only in your shell: run setx TEGVIA_HOME "C:\your\folder" first, open a new window (or double-click install.cmd) so the variable is visible, then run install.cmd; otherwise install refuses and prints that command.

Daily commands

The full command is launch/tegvia-service.sh (Linux, WSL, macOS) or launch\tegvia-service.cmd (Windows), followed by:

Subcommand Effect
install [--dry-run] [--no-tray] [--port N] Install and start (see above), with the tray icon unless --no-tray; --port chooses the port.
uninstall Stop, remove the redirect, delete the definition, remove the tray icon autostart and close the icon.
start Start the service (does nothing if it already runs).
stop Stop it and restore settings.json. No automatic restart.
restart Stop and start again. It waits for the proxy to answer and shows the error log if it does not.
status [--json] Report the state.
sh launch/tegvia-service.sh status
sh launch/tegvia-service.sh restart

Every subcommand is idempotent. Without a subcommand, or with an unknown one, the help is printed and the exit code is non-zero.

status shows whether the service is installed and active, its process id, the last exit code (Linux, WSL and macOS only; on Windows "active" means the proxy answers on its port as the service, and no process id or exit code is shown), the deployment reported by the proxy (service when all is well), whether settings.json is redirected, the console URL, the log paths and, when nothing listens on the port, the end of proxy.stderr.log. It needs no dependency and works even if your config.py is broken. --json prints the same information as JSON for scripts. If the Python or the Tegvia folder recorded in the definition no longer exists (moved or deleted), status says so and advises running install again. It also prints an Icon: line (tray in the JSON): running, installed (autostart set up, not running right now), unavailable with the reason, or absent.

Update

After updating the Tegvia folder (for example git pull), run restart so the service loads the new version. restart is enough even when the dependencies changed: Tegvia installs the new set into its own folder under .deps, then switches to it. If that installation fails (for example you are offline), it keeps using the previous set and tells you so (see Troubleshooting); run restart again once online. Old sets are removed automatically after a successful install. Files left loose at the root of .deps by older versions are no longer used: you may delete them by hand.

Uninstall

System Command
Linux, WSL, macOS ./uninstall.sh
Windows uninstall.cmd

It stops the service, checks that settings.json is back to its original state (and fixes it if not), and removes the definition. It also removes the tray icon's autostart entry (only if Tegvia created it) and closes the icon, even if the service itself was not installed. Your data folder (~/.tegvia), the log database and your config.py are never deleted; the command says so. Running it on a service that is not installed succeeds with a message.

Expired evaluation version

On an expired evaluation version, install, start and restart are refused with exit code 78 and a message giving the date and hello@tegvia.tech; install --dry-run is refused too and changes nothing. uninstall, stop and status keep working; status shows the end date (Evaluation: expires ... or expired on ...).

Logs

  • proxy.stdout.log and proxy.stderr.log in the data folder (~/.tegvia); status prints their paths.
  • state/install.log in the data folder: what install and uninstall printed, run after run (see above).
  • The service manager's own journal: journalctl --user -u tegvia on Linux and WSL; Task Scheduler's task history on Windows.

Start at boot instead of at login (Linux)

By default a systemd user service starts when you log in and stops when your last session ends. To have it start at machine boot, run once, yourself:

loginctl enable-linger $USER

install prints this command but never runs it: it changes the machine's state, so it needs your explicit agreement (and may require administrator rights depending on the system). Effect: your user services start at boot without any login and keep running after you log out.

WSL

On WSL the service needs systemd enabled in the distribution. If it is not, install writes nothing and tells you what to do: add

[boot]
systemd=true

to /etc/wsl.conf in the distribution, then run wsl --shutdown from Windows and reopen the distribution.

A WSL distribution only starts at the first wsl call (opening a WSL terminal, running a wsl command). Until then the service is not running, even with enable-linger. Claude Code run from Windows therefore only goes through a WSL service once a wsl command has started the distribution.

Restarts and the restart window

Each time the proxy stops (stop, crash, restart), the redirect in settings.json is removed; at the next start the proxy puts it back. During the few seconds of a restart, new Claude Code sessions go directly to the Anthropic API, without Tegvia. This is intentional: a dead proxy never breaks a session. Sessions already open keep their address and fail until the proxy is back.

Automatic restart policy:

System Policy
Linux, WSL restart after a failure, 3 s later, at most 5 times per minute
macOS restart on a non-zero exit, at least 5 s apart
Windows configured for up to 3 attempts, 1 minute apart (not guaranteed, see below)

On Windows, automatic restart after a crash is not guaranteed. If the service stays stopped after a crash, run launch\tegvia-service.cmd start (or restart).

A requested stop (stop, systemctl --user stop, ending the task from the service manager except as noted below) is never followed by a restart.

Port already in use

If another process already uses the chosen port (8736 by default), install refuses (unless it is the Tegvia service itself); pick another one with install --port N. If this happens when the service starts (for example at login), it is a configuration error and is not retried in a loop; the message is in proxy.stderr.log (and, on Linux and WSL, in journalctl --user -u tegvia):

  • Linux, WSL: the service stops and is not restarted.
  • macOS: the service exits cleanly and is not restarted.
  • Windows: Task Scheduler is configured to retry up to 3 times, 1 minute apart, then stops; if it stays stopped, run launch\tegvia-service.cmd start.

In that case the service also removes any leftover redirect from settings.json before stopping, so new Claude Code sessions go directly to the API and never to the program holding the port.

Free the port (see Troubleshooting) and run start, or move the service to another port with install --port N.

When protection is off

If protection was turned off from the console, a service restart keeps it off: the proxy relays without inspecting and settings.json stays untouched. Turn it back on from the console.

Limitations

  • Restart window: see above.
  • Windows, stop from Task Scheduler: ending the task from the Task Scheduler window leaves the redirect in settings.json until the next start. Use stop, restart or uninstall, which clean up properly.
  • Windows, logoff or shutdown: logging off or shutting down Windows can likewise leave the redirect in place until the next start of the service.
  • Supervisor killed (macOS): if the process that supervises the proxy is itself killed with a forced kill, the proxy may keep running orphaned and holds the port; kill it (see Standalone deployment), then start.
  • WSL starts only at the first wsl call; linger is only shown by install, never run.
  • Windows refuses paths containing % or ", and a TEGVIA_HOME needs setx.
  • Windows, waiting for Enter: install.cmd and uninstall.cmd wait for Enter whenever they have a console to read from, including when run from a script in a console window. They do not wait when there is no console (a scheduled task) or when input is redirected; add < nul to avoid the wait (install.cmd < nul).
  • The tray icon is not restarted automatically and is not available on WSL (run it on Windows): see System tray icon. Launching the icon starts the service if it is installed and stopped (once, with no retry), and Quit Tegvia in its menu stops the service, after confirmation.

See also Troubleshooting.