Standalone deployment¶
Tegvia can run standalone: you start it with a launcher, it redirects Claude Code while it runs, and it removes the redirect when it stops.
The default way to run Tegvia is the background service: it
starts at login and restarts the proxy if it stops (with a short restart
window during which new sessions go straight to the API). The launchers below
are for a proxy tied to a terminal window: use them if you want a proxy that
lives and dies with that window. Do not run both at once: the launcher
refuses to start while the port is in use (see Refusals), so stop
the service first (stop).
Received Tegvia as a zip file? See Installation from an archive.
Prerequisites¶
- Python 3.11 or newer on the
PATH(see Installation). No virtual environment is needed: the dependencies are installed on the first launch into a.deps/folder inside the Tegvia folder (network access to PyPI required for that first launch). - Port 8736 free on
127.0.0.1.
Launching¶
| System | Launcher | How |
|---|---|---|
| Linux, WSL | launch/tegvia.sh |
sh launch/tegvia.sh in a terminal |
| macOS | launch/tegvia.command |
double-click in the Finder, or sh launch/tegvia.command |
| Windows | launch\tegvia.cmd |
double-click, or run it from cmd.exe |
On macOS, if the system blocks the double-click, see Gatekeeper.
The launcher finds a suitable Python on its own (virtual-environment Pythons
are ignored), installs the dependencies if needed, redirects Claude Code to
the proxy by setting env.ANTHROPIC_BASE_URL in ~/.claude/settings.json,
and runs the proxy in the same window. Restart Claude Code so that it
reads the new setting. Keep the window open: the proxy runs in it.
--background option¶
launch/tegvia.sh --background (same for tegvia.command and tegvia.cmd)
sends the proxy output to proxy.stdout.log and proxy.stderr.log in the
Tegvia data folder (~/.tegvia)
instead of the window. --background does not detach anything: the
launcher window must stay open, and closing it stops the proxy.
Any other argument is refused on Linux and macOS (usage: standalone.py
[--background], exit code 2). On Windows, tegvia.cmd ignores any argument
other than --background.
Stopping¶
Stop the launcher with Ctrl-C, a termination signal (SIGTERM), or by closing the terminal window. The launcher then:
- gives the proxy up to 10 seconds to shut down cleanly (about 3 seconds when a Windows window is closed, or when you log off or shut down Windows), then kills it;
- removes the redirect from
settings.json: the previous value ofenv.ANTHROPIC_BASE_URL, saved inANTHROPIC_BASE_URL_TEGVIA_BACKUP, is restored, or the key is removed if there was none. A value you changed yourself in the meantime is left alone; - prints one of these messages:
Tegvia: redirection removed (settings restored).Tegvia: nothing to clean up.(no redirect, or you changed it)Tegvia: nothing to clean up (...).orTegvia: cleanup failed: ...(on the error output, whensettings.jsoncannot be read or written).
If instead the proxy crashes or is killed on its own, there is no grace period: the cleanup is immediate, within about a second (2 seconds at most).
On Windows, closing the console window, logging off or shutting down gives Tegvia about 5 seconds in total (Windows' own limit), so cleanup happens within that time.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | You asked it to stop (Ctrl-C, termination, window close), on Linux, macOS and Windows. |
| the proxy's code | The proxy stopped by itself. |
| 137 | Linux and macOS only: the proxy was killed (kill -9), including when a requested stop ended with a kill after the grace period (not 0). On Windows a killed proxy gives its own code, usually 1. |
| 2 | Refusal (see below) or wrong argument (Linux and macOS). |
| 1 | The dependency install failed, or the proxy itself exited with 1 (for example a broken config.py). |
To tell the two meanings of code 1 apart, read the message printed in the
window, or the log proxy.stderr.log in the data folder: an install failure
prints a dependency message before the proxy ever starts.
On Windows, the window pauses when the exit code is not 0, so that you can read the message.
Refusals¶
The launcher refuses to start, with exit code 2 and without touching
settings.json, when:
- The port is in use:
Tegvia: port 8736 is already in use, probably by a Tegvia proxy still running from an earlier launch or by the service (stop it with kill <pid>, Task Manager on Windows, or tegvia-service stop), then relaunch.To find<pid>, see Repair after an abrupt stop. settings.jsonis not valid JSON:Tegvia: refusing to start, ... Fix or remove the file and relaunch.
Repair after an abrupt stop¶
If the launcher itself is killed brutally (kill -9 on the launcher,
taskkill /F without /T), it cannot clean up. The proxy keeps running
and Claude Code still goes through it, but nothing will ever remove the
redirect. Relaunching is refused with the port-in-use message (see
Refusals). To recover:
- Stop the leftover proxy. Find its
<pid>withlsof -nP -iTCP:8736 -sTCP:LISTENon Linux and macOS (PIDcolumn), ornetstat -ano | findstr 8736on Windows (last column of the line markedLISTENING). Take only the process that listens on the port: the other lines are client connections, Claude Code's among them.- Linux and macOS:
kill <pid>(a plain termination signal, which also removes the redirect). - Windows: Task Manager (End task) or
taskkill /F /PID <pid>(the proxy has no window, so/Fis required). This forced stop does not remove the redirect: the relaunch in step 2 does.
- Linux and macOS:
- Relaunch the launcher. Once the port is free, it removes the redirect
left behind, prints
Tegvia: previous redirection left by an abrupt stop removed., then starts normally. A redirect you changed to another URL is not touched.
If the power was cut instead, the proxy is gone too, settings.json points
at a proxy that no longer runs and Claude Code sessions fail: simply
relaunch the launcher, which repairs the redirect automatically.
You can also repair by hand in ~/.claude/settings.json: delete
env.ANTHROPIC_BASE_URL, or, if ANTHROPIC_BASE_URL_TEGVIA_BACKUP exists,
put its value back in ANTHROPIC_BASE_URL and delete the backup key (only
once the proxy is stopped).
Before (after a crash, with a previous value saved):
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8736",
"ANTHROPIC_BASE_URL_TEGVIA_BACKUP": "https://my-gateway.example.com"
}
}
After:
{
"env": {
"ANTHROPIC_BASE_URL": "https://my-gateway.example.com"
}
}
If there was no backup key, simply remove the ANTHROPIC_BASE_URL line.
When protection is off¶
If protection was turned off from the console, that state is kept across restarts. The launcher then starts the proxy as a pure relay:
- the proxy does not point
settings.jsonat itself, and removes a redirect that is already there (the previous value is restored). The launcher never points it again while protection is off; - the proxy prints an announcement in the window, such as
tegvia: protection disabled since … ; settings.json is not pointed at the proxy (pure relay). Re-enable it at http://127.0.0.1:8736/tegvia/ui/#/settings, with the address of the console page where you can turn protection back on; - Claude Code then goes straight to the API, without inspection. The console stays available;
- when you stop the launcher there is no cleanup error: there is nothing
left to remove, and the launcher says
Tegvia: nothing to clean up.
When you restart the launcher with protection off, it may print Tegvia:
previous redirection left by an abrupt stop removed. This means the launcher
removed a leftover redirect (for example after an abrupt stop) before starting
the proxy. It is harmless: it is the same cleanup, and settings.json ends up
untouched by Tegvia.
Turning protection back on from the console points settings.json at the
proxy again. Restart Claude
Code, or open a new session, for it to go through Tegvia again. Turning
protection off while the launcher is running restores settings.json the
same way.
Service or launcher¶
| Background service | Standalone launcher | |
|---|---|---|
| Start | at login, automatically | by you, with the launcher |
| Stop | stop, uninstall |
Ctrl-C, window close, crash |
settings.json redirect |
removed at every proxy stop, put back at start | removed at every stop |
| Restart after a crash | yes | no |
The two modes cannot run together. The mode in use is reported by the
deployment field of /tegvia/status (service under the background
service, standalone, or manual for a proxy started by hand).
Web console in standalone mode¶
The web console (http://127.0.0.1:8736/tegvia/ui/) works the same way: the
status card shows "Protection active" or "No recent traffic" when Claude Code
goes through the proxy. If the redirect is missing ("Not configured"), the
"How to fix" advice is to relaunch the launcher.
Limits¶
If all your sessions fail, see Troubleshooting.