This page gets you from a fresh clone to a running hub built from source, a live-reloading web panel, and a tagged release. Read CONTRIBUTING.md for the rules a change has to follow.
- Go 1.26 or later (the exact version is in
go.mod). - Bun 1.4.3 for the web panel (pinned in
web/package.json). - Optional:
shellcheckformake lint, Docker formake docker.
| Path | Contents |
|---|---|
cmd/server/ |
The t3code-proxy entrypoint, including the doctor and discover commands. |
cmd/fetch_*, cmd/validate_codex_models/ |
Utilities that refresh and check the embedded model catalogs. |
internal/api/ |
Gin HTTP server: proxy routes, middleware and the management API. |
internal/runtime/executor/ |
One executor per provider, including Codex over WebSockets. |
internal/translator/ |
Protocol translators between the OpenAI, Claude, Gemini and Codex formats. |
internal/thinking/ |
The reasoning-effort pipeline shared by all providers. |
internal/auth/ |
OAuth login and refresh for each provider. |
internal/doctor/ |
The t3code-proxy doctor checks. |
internal/quotahistory/ |
The quota-history recorder and its store. |
internal/managementasset/ |
Serves the web panel: embedded copy, optional download, placeholder. |
internal/registry/ |
Model registry and the remote catalog updater. |
internal/watcher/ |
Config and auth-directory hot reload. |
sdk/cliproxy/ |
Embeddable service, auth manager and selectors, including soonest-reset-first. |
web/ |
The React web panel. See web/README.md. |
deploy/ |
systemd unit, launchd agent and Windows Scheduled Task script. |
scripts/ |
Build, web, release and install scripts. |
test/ |
Cross-package tests, including the T3 Code contract test. |
examples/ |
SDK and plugin examples. |
Run make or make help for the list:
| Target | What it does |
|---|---|
make build |
Build bin/t3code-proxy for this machine. Embeds the panel if one is staged. |
make web |
Build the web panel and stage it for embedding. |
make test |
Run the Go tests. |
make test-web |
Run the panel's tests, lint and build (bun run verify). |
make lint |
Check gofmt, run go vet, and run shellcheck on the scripts. |
make fmt |
Format the Go code with gofmt. |
make verify |
Everything CI runs: lint, test, build, test-web. |
make run |
Run the server from source with CONFIG (default config.yaml). |
make release |
Cross-build archives and checksums.txt into dist/. |
make docker |
Build the container image ghcr.io/rune-oai/t3code-proxy:dev. |
make clean |
Remove build outputs. |
A typical loop:
cp config.example.yaml config.yaml # edit the keys first
make web
make build
./bin/t3code-proxy -config config.yamlThe panel is a Vite app in web/. The production build is a single web/dist/index.html.
make web copies it to internal/managementasset/embedded/management.html, which the Go build
embeds. That file is not committed; a binary built without it serves a placeholder page at
/management.html.
For panel work, run the Vite dev server:
cd web
bun install --frozen-lockfile
bun run devOpen http://localhost:5173/?fixture=quota-history#/quota for a logged-in dev session backed by
sample data, with no hub running. The fixture works on the other routes too, such as
#/auth-files, #/routing, #/ai-providers and #/config. It is compiled out of production
builds.
To work against a real hub, open http://localhost:5173/, enter the hub's URL under Hub
address, and log in with its management secret. A local make run hub at
http://127.0.0.1:8317 works well for this.
Before you push panel changes, run make test-web.
make test
go test -v -run <TestName> ./<path/to/package>test/t3code_contract_test.go pins the three /v0/management endpoints T3 Code depends on. If it
fails, the change breaks T3 Code.
Releases are cut from a version tag. The version comes from the exact v* tag on HEAD;
untagged builds report dev.
-
Update CHANGELOG.md: move the entries under
Unreleasedto a new version heading. -
Commit, then tag and push:
git tag v<version> git push origin v<version>
-
The
releaseworkflow runs the tests, builds the archives withmake release, attests their provenance, and publishes a GitHub release with the archives andchecksums.txt. A tag that contains-, such asv0.2.0-rc.1, is published as a prerelease. -
The same workflow builds and pushes the multi-platform image to
ghcr.io/rune-oai/t3code-proxy.
To build release archives locally, run make release. Set TARGETS to limit the platforms, for
example make release TARGETS="linux/amd64 darwin/arm64". Cross-built Linux and macOS archives
are built without CGO and cannot load dynamic library plugins; the container image is built with
CGO and can.