Quickstart

Install TELOS, connect your harnesses, and watch the savings — in three commands.

TELOS sits between your agent and the model API. It rewrites each request so the parts that are genuinely stable keep hitting the KV cache, without changing a single byte the engine actually sees as semantically meaningful. You get there in three steps.

1. Install

   # Linux / macOS / WSL2 / Android (Termux)
   curl -fsSL https://raw.githubusercontent.com/learningCatHD/telos-sdk/main/scripts/install.sh | bash
   

   Prefer pip?

   pip install -U telos-sdk
   

   Requires Python ≥ 3.10. See Installation for the from-source path and dependency details.

2. Connect

   telos init
   

   With no arguments, telos init will:

   • auto-detect which harness CLIs are installed locally (claude-code / codex / openclaw / hermes),
   • inject config pointing each at the local gateway,
   • start the gateway in the background (state in ~/.telos/gateway.json),
   • print the gateway and dashboard addresses.

   No changes to your agent code, no changes to PATH, and npm update won’t lose it.
3. Observe

   telos dashboard
   

   Opens an offline HTML dashboard in your browser showing savings per call in absolute dollars. Every invocation is appended to ~/.telos/usage.jsonl and aggregated in real time.

   

After telos init

telos              # pick a harness and enter its CLI
telos dashboard    # open the live dashboard in the browser
telos mode both    # switch the optimization gear, hot-reloading the running gateway
telos gateway status   # check the gateway's run status

Choose your integration path

There are two functionally equivalent ways to route traffic through TELOS.

Path B · Proxy gateway

Zero-intrusion. Point ANTHROPIC_BASE_URL at the local gateway — no code changes. This is what telos init sets up. Recommended.

Path A · SDK transport

In-process. Swap your anthropic.Anthropic() / openai.OpenAI() client for the TELOS transport; every .create() call stays the same.

Next steps

The Protocol

Understand why the cache can’t break.

Three-color bands

PIN / FOLD / DROP, explained.

Support Matrix

Which harnesses, models, and frameworks are covered.

Don’t trust the percentages — TELOS is open source. Run it on your own workflow and see whether that 92% is real, or just another “X× tokens” claim.