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
installinto 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";installrefuses them. On all systems,installalso 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:
--port N;- the
TEGVIA_PORTenvironment variable, if it holds a valid port; - the port of the previous install (so a plain
installrun again keeps your port); -
the default, 8736.
-
A
--portoutside 1024-65535, or not a number, is refused with a usage message and exit code 2. - If you give
--portand a differentTEGVIA_PORT,installrefuses (exit code 3) with a message naming both values. Remove one or make them equal. - A
TEGVIA_PORTthat 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).orUninstall failed (see above).(foruninstall)
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.logandproxy.stderr.login the data folder (~/.tegvia);statusprints their paths.state/install.login the data folder: whatinstallanduninstallprinted, run after run (see above).- The service manager's own journal:
journalctl --user -u tegviaon 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.jsonuntil the next start. Usestop,restartoruninstall, 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
wslcall; linger is only shown byinstall, never run. - Windows refuses paths containing
%or", and aTEGVIA_HOMEneedssetx. - Windows, waiting for Enter:
install.cmdanduninstall.cmdwait 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< nulto 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.