Install Qosway
Run the self-hosted Qosway LLM gateway as a systemd service or a container, behind your own TLS reverse proxy, after requesting access.
Qosway is a self-hosted gateway for Claude Code, Codex, and any OpenAI-compatible client. You run a single static Go executable, with the admin panel built in, and point your tools at it. There is no Node runtime, and no separately operated database server. SQLite lives in the data directory. Redis is optional.
This page covers installing Qosway as a systemd service or a container, first-run setup, client keys, health checks, and upgrades.
Requirements
- A host where you can run a static Go binary, as a systemd service or as a container.
- A license signed for one customer. The binary will not start without a valid one.
- Your own TLS reverse proxy, or a bind to loopback. Qosway does not terminate TLS.
- Redis is optional. You need it only if you want the exact cache and the rate limit. If you run Redis, give it a password or TLS on a private network; exact cache entries are not encrypted and hold full answers.
The operating systems and CPU architectures of the builds are provided with access.
Get the binary and license
Qosway is not offered as a public download. Request access at hello@qosway.com.
You receive a license key for one customer, and the binary. The operating systems and CPU architectures of the builds are provided with access: write to hello@qosway.com.
The license key is not baked into the binary and is not entered in the panel. You pass it when the process starts, either as a flag or as an environment variable:
qosway --license-key YOUR_LICENSE_KEY
# or, so the key does not show in `ps`:
QOSWAY_LICENSE_KEY=YOUR_LICENSE_KEY qosway
If both are set, the flag wins. At start the binary asks the license server (https://license.qosway.com by default; --license-server or QOSWAY_LICENSE_SERVER points it elsewhere). With no key, or with a license the server says is not active, the process exits with code 78. If the server cannot be reached and there is no saved answer less than 30 minutes old, it exits with code 1. Until the license is confirmed, proxy requests stay closed. After that, a license server outage does not stop the process, but the proxy refuses traffic once 30 minutes have passed since the last good check, and reopens when the server answers again.
Configuration
SQLite is the default store. It lives in the data directory on local disk. The data directory is mode 0700; the databases and the key file are mode 0600.
Provider keys, client keys, and the admin password hash are stored in SQLite settings, AES-GCM encrypted, with a key file kept beside the database. Store that key file separately from backups of the database.
Redis is optional. It is used for the exact cache and for rate limits. The semantic cache, when used, lives in SQLite (answers and embeddings, not prompt text). If Redis goes down, the exact cache and the rate limit switch off, and traffic keeps flowing to the providers.
The data directory is set with the QOSWAY_DATA_DIR environment variable. If it is not set, it is a data directory next to the binary. It holds the SQLite databases, secret.key, instance.id, and license.lease (the last signed license answer, mode 0600).
Redis is set in the panel, on the Connection page, as a Redis URL. The default is redis://127.0.0.1:6379/0. The URL must start with redis://, rediss:// (TLS) or unix://. Put the password in the URL:
redis://:<redis-password>@127.0.0.1:6379/0
rediss://:<redis-password>@redis.internal.example:6379/0
A change in the panel is applied to the next request, without a restart. If Redis cannot be reached, Qosway logs that the exact cache and the rate limit are off, and keeps serving.
The listen address is :8080 by default, which is every interface on port 8080. Change it in the panel, on the Connection page, as host:port, for example 127.0.0.1:8080. A change moves the socket without a restart. If a saved address cannot be bound at start, Qosway logs an error and falls back to :8080. The panel, the API, and the health and metrics endpoints all use this one address.
Controls in the panel (routing, cache, quotas, egress) can be changed without a redeploy. OpenAI, Anthropic, DeepSeek, and Grok are each one switch.
The upstream key for each provider is entered in the panel, on the Providers page (OpenAI, Claude, DeepSeek, Grok). It is stored in SQLite settings, AES-GCM encrypted, and takes effect on the next request. Leaving a key field blank keeps the saved key. On the same page you can change each provider's base URL; the defaults are the providers' own API addresses. Which providers are allowed is a switch per provider on the Routing page. A provider that is off refuses its models.
Run it (systemd / container)
Run the binary as a systemd service or as a container.
Flags:
| Flag | Meaning |
|---|---|
--license-key <key> |
License key for this install. Or set QOSWAY_LICENSE_KEY. |
--license-server <url> |
License server URL. Default https://license.qosway.com, or QOSWAY_LICENSE_SERVER. |
--version |
Print the version and exit. |
Environment variables read by the process: QOSWAY_LICENSE_KEY, QOSWAY_LICENSE_SERVER, QOSWAY_DATA_DIR. Everything else is set in the panel.
QOSWAY_DATA_DIR=/var/lib/qosway QOSWAY_LICENSE_KEY=YOUR_LICENSE_KEY /opt/qosway/qosway
The process logs JSON lines to standard output. SIGTERM or SIGINT stops it, draining open connections for up to 15 seconds.
Save this as /etc/systemd/system/qosway.service. It assumes the binary at /opt/qosway/qosway, the license key in /etc/qosway/qosway.env (mode 600, one line: QOSWAY_LICENSE_KEY=YOUR_LICENSE_KEY), and data in /var/lib/qosway. Create a dedicated user first:
useradd --system --home /var/lib/qosway --shell /usr/sbin/nologin qosway
[Unit]
Description=qosway LLM proxy
After=network-online.target redis-server.service
Wants=network-online.target
[Service]
User=qosway
Group=qosway
WorkingDirectory=/opt/qosway
Environment=QOSWAY_DATA_DIR=/var/lib/qosway
EnvironmentFile=/etc/qosway/qosway.env
ExecStart=/opt/qosway/qosway
Restart=on-failure
RestartSec=10
# Exit 78 = license missing or refused by the license server: do not loop.
# Exit 1 (license server unreachable, no usable saved answer) is retried every 10 s.
RestartPreventExitStatus=78
# Graceful drain of streaming responses on stop/restart.
TimeoutStopSec=30
KillSignal=SIGTERM
LimitNOFILE=65536
StateDirectory=qosway
StateDirectoryMode=0700
UMask=0077
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
LockPersonality=true
MemoryDenyWriteExecute=true
ReadWritePaths=/var/lib/qosway
[Install]
WantedBy=multi-user.target
Then systemctl daemon-reload and systemctl enable --now qosway. Read the one-time setup token from journalctl -u qosway.
The container runs the same binary as a non-root user, with the data directory at /data (a volume) and port 8080 exposed. Pass the license key as an environment variable. In this example qosway is the image name; use the name of the image you receive:
docker run -d -p 127.0.0.1:8080:8080 -v qosway-data:/data -e QOSWAY_LICENSE_KEY=YOUR_LICENSE_KEY qosway
Read the one-time setup token with docker logs. The image has a health check that calls /readyz (qosway -healthcheck [host:port], default 127.0.0.1:8080). With Redis in another container, set the Redis URL in the panel, for example redis://redis:6379/0.
The container image and a compose file are provided with access: write to hello@qosway.com.
Put it behind a reverse proxy
Qosway does not terminate TLS. Put it behind the TLS reverse proxy you already operate, or bind it to loopback.
The following is a generic example, not Qosway-specific. It only shows a Caddy reverse_proxy block pointing at port 8080, the default. Use the proxy you already run, and the address the process is actually bound to.
# Generic example (not Qosway-specific).
# Qosway does not terminate TLS; your reverse proxy should.
# Qosway listens on :8080 by default; change it in the panel.
example.com {
reverse_proxy 127.0.0.1:8080
}
First run
On first run, the admin password is set from the same machine, or with a one-time token printed in the log.
From the same machine means a direct connection to the loopback address, for example http://127.0.0.1:8080/admin from the host itself (or over an SSH tunnel to it). A request that carries a Forwarded, X-Forwarded-For, or X-Real-Ip header counts as remote, so a reverse proxy on the same host does not make the internet look local. Through a proxy you need the one-time setup token: it is printed in the log in the "admin password is not set" line as setup_token, and is forgotten once the password is set. If the process is started in a terminal, it asks for the admin password there instead. The password must be at least 8 characters.
The panel is at /admin on the same address and port as the proxy, for example https://example.com/admin behind your reverse proxy. Log in with the admin password. You can change the password later on the Connection page.
Repeated failed admin logins from one address are locked out. After 5 free tries the lockout starts at 30 seconds and doubles with each further failure, up to 15 minutes. The count is kept in memory and resets when the process restarts. When the connection comes from a loopback or private address (a reverse proxy), the address counted is the last X-Forwarded-For entry, the one your proxy added.
Create a client key
Qosway is closed by default. With no client key created, every request is rejected.
In the panel, open Client keys, type a label (for example the person or tool), and press create key. The key looks like pk_ followed by hex characters. The full secret is shown once; the list afterwards shows the label and the last characters only. Give one key to each person or tool. A key is deleted from the same page. Clients send it as Authorization: Bearer pk_..., or as x-api-key on the Anthropic-style endpoints.
In the panel, open Quotas. The default tokens per day and per month apply to every key that has no number of its own. Below that, a per-key table lets you set a daily and a monthly limit for one key, which replaces the default for that key. 0 means no cap.
Every client key has a ceiling, enforced before the provider is called: daily and monthly token caps, and a fixed-window rate limit (600 requests a minute by default, counted in Redis). Over the cap, the client gets HTTP 429 quota_exceeded before the upstream call. An invalid key is 401 invalid_api_key. A key over its rate limit is 429 rate_limit_error. Bodies above 10 MiB are refused with 413.
Pointing Claude Code and Codex at the gateway
Qosway speaks OpenAI chat completions, OpenAI Responses, and Anthropic Messages. Clients keep their own response shape. You point Claude Code, Codex, or any OpenAI-compatible client at the gateway.
Create a client key first (see above). Claude Code and Codex use that key in place of a provider key, and the base URL is the address Qosway is reachable at, for example https://example.com.
Claude Code calls POST /v1/messages (and /v1/messages/count_tokens) on the address you give it. Use a client key from the panel as its credential; Qosway accepts it as Authorization: Bearer pk_... or as x-api-key.
In Claude Code, set these environment variables (in your shell, or under env in a settings file):
export ANTHROPIC_BASE_URL="https://example.com"
export ANTHROPIC_AUTH_TOKEN="pk_..."
ANTHROPIC_BASE_URL points Claude Code at the gateway. ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer, which Qosway accepts. ANTHROPIC_API_KEY, sent as X-Api-Key, works as well. Source: Claude Code environment variables and Other LLM gateways.
Codex calls POST /v1/responses on the address you give it, with a client key from the panel as Authorization: Bearer pk_....
In Codex, define a custom provider in ~/.codex/config.toml and set the key in an environment variable:
model_provider = "qosway"
[model_providers.qosway]
name = "Qosway"
base_url = "https://example.com/v1"
env_key = "QOSWAY_CLIENT_KEY"
wire_api = "responses"
export QOSWAY_CLIENT_KEY="pk_..."
model_provider picks the provider, base_url is the gateway address, env_key names the environment variable that holds the key (sent as a bearer token), and wire_api = "responses" selects the Responses API, which Qosway serves. QOSWAY_CLIENT_KEY is a name you choose, not one Qosway reads. Source: Codex advanced configuration, custom model providers.
Send chat completions to POST /v1/chat/completions (also served at /chat/completions) on the gateway address, with Authorization: Bearer pk_... using a client key from the panel. GET /v1/models returns the list of model names Qosway knows.
Health and metrics
The binary exposes /healthz, /readyz, and a Prometheus /metrics endpoint. The admin panel, built into the binary, shows per-key usage, cost, cache results, and request history.
They share the one listen address with the proxy and the panel.
| Path | Purpose | Authentication |
|---|---|---|
GET /healthz |
The process is up. Returns {"ok":true}. |
None |
GET /readyz |
The database answers. {"ready":true}, or 503 {"ready":false}. |
None |
GET /metrics |
Prometheus text format. | An admin session, or Authorization: Bearer <client key>. Otherwise 401. |
For Prometheus, give the scrape job a client key as a bearer token.
| Metric | Type | Labels |
|---|---|---|
qosway_http_requests_total |
counter | class (status class, such as 2xx) |
qosway_http_request_seconds_total |
counter | class |
qosway_cache_results_total |
counter | result (MISS, HIT-EXACT, HIT-SEMANTIC) |
qosway_upstream_requests_total |
counter | provider, class |
qosway_prompt_tokens_total |
counter | none |
qosway_completion_tokens_total |
counter | none |
qosway_cost_usd_total |
counter | none |
qosway_saved_usd_total |
counter | none |
qosway_http_inflight |
gauge | none |
qosway_goroutines |
gauge | none |
qosway_heap_alloc_bytes |
gauge | none |
qosway_uptime_seconds |
gauge | none |
Data and backups
| Data | Where it lives | How it is handled |
|---|---|---|
| Provider keys, client keys, admin password hash | SQLite settings | AES-GCM encrypted with a key file kept beside the database. Store that file separately from backups of the database. |
| Usage, cost and quota records | SQLite | Reference a key id, never the key. Events kept 90 days, daily buckets 35 days, monthly buckets 14 months, then pruned. |
| Blocked requests | SQLite | Time, key id and rule name only. The matched secret is never stored. |
| Cached answers | Redis (exact), SQLite (semantic) | Not encrypted. Exact entries hold full answers, so give Redis a password or TLS on a private network. The semantic cache holds answers and embeddings, not prompt text. |
| Data directory | Local disk | Directory mode 0700; databases and key file 0600. |
Upgrading
The upgrade build is provided with access: write to hello@qosway.com.
A restart is required to run the new binary. Stop it with SIGTERM (systemctl restart qosway); open streams get a short drain. The data directory is read again at start: settings, client keys, secret.key, and instance.id stay where they are. The license key is not stored in the data directory, so it has to be supplied again at start, through the same flag or environment variable. Keep secret.key with the database; without it the saved settings cannot be read and Qosway refuses to start.
Run qosway --version. It prints qosway and the version the binary was built with. A binary built without a version prints dev.
What it does not do
- It does not read meaning. Egress rules are patterns, and routing is rules, not a model judging your prompts.
- It does not block personal data by default. In code tools that is mostly false alarms; add your own patterns if you need it.
- It does not terminate TLS. Put it behind a reverse proxy, or bind it to loopback.