Skip to content

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:

  1. 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;
  2. removes the redirect from settings.json: the previous value of env.ANTHROPIC_BASE_URL, saved in ANTHROPIC_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;
  3. 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 (...). or Tegvia: cleanup failed: ... (on the error output, when settings.json cannot 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.json is 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:

  1. Stop the leftover proxy. Find its <pid> with lsof -nP -iTCP:8736 -sTCP:LISTEN on Linux and macOS (PID column), or netstat -ano | findstr 8736 on Windows (last column of the line marked LISTENING). 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 /F is required). This forced stop does not remove the redirect: the relaunch in step 2 does.
  2. 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.json at 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.