TierMux documentation

Introduction

TierMux is three things built on one dataset: a verified catalog of free-tier LLM providers and models, a free agentic coding assistant for VS Code, and a self-hosted gateway that serves inference from your own keys on your own infrastructure.

Every provider in the catalog has been verified with real requests. Capability flags — tool calling, image input, reasoning — are measured, not copied from a pricing page, and listings that stop answering are removed rather than left to fail silently. The catalog reflects what is callable today, not what was callable when it was indexed.

The API is read-only, needs no account and no key, and sends Access-Control-Allow-Origin: * on every response, so a browser can call it directly.

Quick start

Three entry points, depending on what you came for.

Code in your editor#

1. Install the extension. In VS Code: Extensions (Ctrl Shift X) → search TierMux → Install. In Cursor, Windsurf, Antigravity, VSCodium or Trae, take the same build from Open VSX.
2. Open it. Activity Bar → TierMux.
3. Type. Four providers ship keyless, so the first message answers with no key, no account and no config.

That is the whole setup. Adding free keys comes later and is the single biggest upgrade you can make.

Read the catalog#

Every free reasoning model currently in the catalog, in three languages:

curl -s "https://tiermux.mainulislam3057.workers.dev/models?tag=frontier" \
   | jq '.models[] | select(.pricing.free) | .model_id'

const res = await fetch(
   "https://tiermux.mainulislam3057.workers.dev/models?tag=frontier"
);
const { models, version, last_updated } = await res.json();

const free = models.filter((m) => m.pricing.free);
console.log(`${free.length} free frontier models (catalog ${version}, ${last_updated})`);

import json, urllib.request

url = "https://tiermux.mainulislam3057.workers.dev/models?tag=frontier"
with urllib.request.urlopen(url) as r:
    data = json.load(r)

free = [m for m in data["models"] if m["pricing"]["free"]]
print(len(free), "free frontier models", "| catalog", data["version"])

Full shapes are in the API reference and the object reference.

Run the gateway#

The gateway is in final testing and the public repo has not landed yet. This catalog already serves the exact configuration payload it consumes, so a gateway deployed on day one works against it with no extra setup. The full design is here →

Concepts

Six words that mean something specific in TierMux. Worth two minutes now.

VS Code extension

A free, open-source agentic coding assistant that pools 30+ free-tier providers into one self-healing surface. No subscription, no per-token bill, no TierMux server in the request path.

Install#

One VSIX runs in VS Code and every VS Code fork. The only difference is which registry your editor reads:

First run#

Activity Bar → TierMux, then type

That is the whole first run. The row above the composer reports how many models are ready and what routing is set to; the banner above it surfaces whatever free tier is currently worth knowing about.

• Bottom-left picks the mode: Ask · Plan · Agent.
• Next to it, the model picker — leave it on Auto, or click to pin one.
• / runs a skill, @ attaches a file, the paperclip adds an image.
• Shift Enter is a newline; Enter sends.
• The footer counts lifetime tokens, requests, and what those turns would have cost on a paid API.

Modes and the model picker

Three modes, picked in the composer. Ask is the default.

An approved plan executes as one agent turn with its steps enumerated in the prompt. Progress survives a reload — there is a Resume button.

Auto is a model choice, not a mode#

The model picker sits next to the mode picker and defaults to Auto. Auto classifies your message — chat, coding, debug, plan, agent, vision, by regex, with no model call — then builds a chain and works down it. Pin a model instead and that turn goes to exactly that model, with no routing.

How a turn is routed#

The chain is: your pinned model if there is one, else the task table's pick, then every enabled model strongest-first — one model per provider first, so the chain spans providers instead of exhausting one. Then each upstream answer is given a fixed meaning:

Providers and keys

Optional, and the highest-leverage ten minutes you can spend on the extension. More keys means more headroom before a wall; unused keys just rest.

⚙ gear → Providers

Click a provider to expand it. Paste a free key, then tick only the models you want in the chain. Enabled providers sort to the top.

• The T V R badges on each model row mean tools, vision and reasoning — measured, not advertised.
• Each model row can carry its own key, for providers that issue per-model credentials.
• Providers marked keyless need nothing at all.
• Skip this tab entirely and the keyless four still answer.

The keyless four#

Enabled out of the box, no account required: Kilo Gateway, OpenCode Zen, OVH AI Endpoints and Pollinations. This list is read from the live catalog.

Providers with a free key#

Every other provider issues free keys through its own portal. The live list, with a direct link to each portal, is in the provider directory further down this page — the get a key ↗ link in each row goes straight to the right signup.

Where keys live#

In VS Code's encrypted secret storage — not in settings.json, and not in your workspace. Requests go VS Code → provider, directly. There is no TierMux server in the path and nothing to opt out of.

MCP, skills and custom endpoints

Three more gear tabs. All optional; each one extends what a turn can reach.

MCP servers

+ Add server, or edit tiermux.mcpServers in settings.json directly. Every tool a connected server exposes becomes an agent tool for the rest of the session.

• The registry below the list installs common servers — filesystem, GitHub, Fetch, Puppeteer — in one click.
• Remote search defaults to the official MCP registry; point tiermux.mcpRegistrySearchUrl elsewhere, or blank it to disable remote search.
• TierMux: Reconnect MCP Servers re-establishes them without a window reload.

Skills

A skill is a saved prompt you run as /name. Installed ones land in .agents/skills/, the cross-tool convention, so they are shared with other agent tools in the same workspace.

• Browse the catalog, or point tiermux.skillRegistryUrl at your own list to replace it.
• TierMux: Add Skill from GitHub installs one by URL.

!

Read the source before installing. A skill is a prompt that steers the agent, so it runs with the agent's permissions. Vendor repo on a card means only that it installs from the vendor's own repository — not that anyone reviewed it.

Custom endpoints

At the bottom of the Providers tab. Name, base URL, type, an optional key, then Save & fetch models.

• OpenAI-style — Ollama, LM Studio, vLLM, LiteLLM, llama.cpp, Azure OpenAI.
• Newer — the Responses API shape.
• Anthropic-style — Claude-compatible endpoints.
• Local servers are probed for their real context window rather than trusting the number they advertise.

Usage

Lifetime tokens, request count and estimated money saved, broken down per model. Tracked locally on your machine and cleared only when you ask.

• Useful for the question that actually matters: which free tier are you leaning on, and what happens the day it changes?
• If one provider carries most of your traffic, that is the one to add a second key for.

Approvals and safety

The agent edits files and runs commands. What it may do without asking is yours to set, and the defaults ask.

⚙ gear → Others

• Require write confirmation — a diff you approve before any file is written, created or deleted. On by default.
• Command approval — always (ask every time, the default), allowlist (built-in safe prefixes plus your own), or off.
• Utility model — the small one used for chat titles and commit messages.
• Inline completions — off by default; ghost text is a high request volume against free-tier limits.
• Diagnostic trace — turn it on when a turn feels slow and read the TierMux Diag output channel.

The rails that are not optional#

• Every path argument is confined to the workspace. A tool call cannot escape it.
• Checkpoints capture the before-content of a write before the mutation, so Undo genuinely restores rather than asking the model to reconstruct.
• Stop really kills the shell — not just the stream.
• After a turn edits files, your own verify command runs; a non-zero exit feeds the failure back for bounded fix-and-recheck rounds.
• A turn that hits its step cap stops visibly and offers Continue with full memory. Nothing is redone.

Settings reference

Everything the extension contributes to settings.json, with its default. All of it is optional — the defaults are the recommended configuration.

Agent#

Models, context and completions#

Plans, skills and MCP#

{
  "tiermux.agent.requireWriteConfirmation": true,
  "tiermux.agent.commandApproval": "allowlist",
  "tiermux.agent.commandAllowlist": ["npm test", "npm run build", "git status"],
  "tiermux.agent.verifyCommand": "npm test",
  "tiermux.context.ambientSliceRadius": 10
}

Commands

Everything in the Command Palette (Ctrl Shift P / Cmd Shift P) under TierMux:.

Troubleshooting

The failures people actually hit, and what each one means.

Gateway

A self-hostable LLM gateway that consumes this catalog and serves inference through your own provider keys, on your own infrastructure. TierMux maintains the catalog; nothing else leaves your deployment.

• Speaks all three protocols over one endpoint — Claude Code, Codex CLI, Cline, Zed and the OpenAI Agents SDK connect directly.
• Key rotation, circuit breakers, per-model quarantine, aliases, and an auto model that ranks on observed facts rather than a static list.
• Prompts, responses, provider keys and routing state never leave the deployment. The only outbound call to TierMux is the public catalog fetch.
• Migrations apply themselves on cold start. There is no migration command on either target — which is what makes the one-click deploy viable at all.

Installing and updating

The wizard is the shortest route to both: it checks the machine, asks where the gateway should run, and either starts it here or deploys it to your own Cloudflare account. The same three steps update an existing deployment.

npm run setup

# or double-click:
#   macOS    start.command
#   Windows  start.bat

It serves one page on 127.0.0.1:8790 and opens it. Nothing is installed globally and no terminal work follows — the Worker bundle ships pre-built, so there is no wrangler and no build step.

1 · It checks the machine#

Three requirements, checked for you

• Node v22.5.0 or newer. The gateway stores data through Node's built-in SQLite, which landed in v22.5.0.
• The gateway bundle. Pre-built and ready to deploy — the check reports its size.
• Network. Only needed for the Cloudflare route; it confirms the Cloudflare API answers from here.

Roughly thirty models answer with no provider key at all, so you can test the gateway before adding any.

2 · You choose where it runs#

Both are free, and neither is permanent

• Cloudflare — a Worker with a D1 database in your own account. Reachable from anywhere, and it stays up when this computer does not.
• This computer — runs here on SQLite for as long as the window stays open. The quickest way to try it; you can deploy to Cloudflare later without losing anything.

3 · Deploying to Cloudflare#

One scoped API token, used once

Open Cloudflare API tokens ↗, then Create Token → Create Custom Token, and add exactly these three permissions:

Cloudflare shows the token once. Paste it, verify, and the wizard creates the D1 database, uploads the script, and enables the workers.dev URL — with real upload progress rather than a spinner.

Updating an existing gateway#

Same three steps, one toggle

On the last step, switch from Fresh install to Update existing. Only the Worker code is replaced — the database, the admin account, your provider keys and every issued API key stay exactly as they are.

The token walkthrough collapses to a show the steps link, because you have already made one; the same token works again.

Updating the other way round#

If you deployed from a fork rather than the wizard, or you run it in Docker, updating is the equivalent action in that world:

Deploying the gateway

Two targets, one source tree, one schema. D1's engine is SQLite, so the schema is genuinely shared — only the driver differs.

The Deploy button forks the repo into
your GitHub, provisions D1, deploys,
and wires up Workers Builds.

Every later push to your fork
auto-deploys.

Needs: a browser and a CF account.

docker compose up -d      # :8788/panel

npm install && npm start   # Node 22.5+

# Built-in node:sqlite — no compile
# step, no Redis, no Postgres.
# Config: PORT and DATA_DIR.

The packaged release ships a pre-built Worker bundle, so deploying needs neither wrangler nor a build step on the far end. State survives docker compose down and every image update.

First run#

1. Open /panel. With no admin yet, you land on /panel/install.
2. Set an admin username and password. That is the entire form. You are never asked where the catalog lives, because that is not yours to manage — it loads on its own.
3. Install locks. /panel/install stops working, so nobody can claim the account after you.
4. Add a provider key, then issue an API key. /v1/* refuses to serve until at least one API key exists. There is no open mode and no default password.

Agents and clients

Everything that has been connected to this gateway, and the three things each one asks for under its own set of names. Seventeen clients, one endpoint.

The three values#

Whatever a client calls its fields, it is asking for the same three. Base URL turns up as “API endpoint”, “Custom URL” or “Provider API”; the provider type must be set to OpenAI Compatible before any of them take effect, because every other provider type ignores the URL and calls its own servers.

Verifying a connection#

Before blaming the client, check the gateway answers. A 200 with a non-empty list means the URL, the key and the catalog are all good — so anything still broken is on the client's side of the wire.

curl -s -H "Authorization: Bearer tmx_your_key_here" \
  "https://YOUR-DEPLOYMENT/v1/models"

Gateway routing and failure policy

A fixed, deterministic order — and a substitution is always announced, never silent.

1. Exact alias — yours, panel-configured, resolves before model names
2. Exact model_id
3. Normalized key — deepseek/deepseek-v4:free and deepseek-v4 collide, which is what makes cross-provider fallback possible
4. Wildcard match — deepseek/* style patterns
5. Configured fallback alias
6. auto — unknown names land here instead of dead-ending on a 404; x-tiermux-model and the response body both name what actually ran

Before any of it: requests declaring tools only reach tool-capable models, image-carrying requests only vision-capable ones, and prompts are steered away from models whose context window cannot hold them.

Failure policy#

The auto profiles, hedging, quota headroom and recovery windows →

Catalog API — conventions

Five read-only endpoints. All are GET, all are CORS-enabled, and none of them takes an API key.

https://tiermux.mainulislam3057.workers.dev

Authentication#

None. There is no key to obtain and no header to send. Every response carries Access-Control-Allow-Origin: * and Access-Control-Allow-Methods: GET, so browser code can call these endpoints directly with no proxy.

Caching and versioning#

The four catalog endpoints answer with Cache-Control: public, max-age=120. /api/service-status answers no-store, because a stale kill-switch read is worse than an extra request.

Every catalog response carries three fields at the top level:

Filtering#

Two query parameters exist across the API. Unknown parameters are ignored rather than rejected.

Every enabled model as a flat list, each entry joined with its provider. The endpoint most clients want.

curl -s "https://tiermux.mainulislam3057.workers.dev/models?tag=reasoner&provider=google"

Response

{
  "version": "1.6",
  "last_updated": "…",
  "last_synced_at": "…",
  "count": 9,
  "models": [
    {
      "model_id": "gemini-2.5-flash",
      "display_name": "Gemini 2.5 Flash",
      "enabled": true,
      "context_window": 1000000,
      "capabilities": { "tools": true, "vision": true, "reasoning": true },
      "tags": ["mid"],
      "limits": { "rpm": 15, "rpd": 1500 },
      "pricing": { "free": true, "input": 0.3, "output": 2.5 },
      "recommended": false,
      "provider_id": "google",
      "provider_display_name": "Google"
    }
  ]
}

The provider directory with a model count per provider, and no model bodies. Use it to build a picker without downloading the whole catalog.

{
  "version": "1.6",
  "last_updated": "…",
  "last_synced_at": "…",
  "count": 34,
  "providers": [
    {
      "provider_id": "google",
      "display_name": "Google",
      "base_url": "https://generativelanguage.googleapis.com/v1beta",
      "keyless": false,
      "key_url": "https://aistudio.google.com/apikey",
      "enabled": true,
      "model_count": 10
    }
  ]
}

Providers with their models nested, plus announcements, in one request. This is the payload shape the gateway consumes.

{
  "version": "1.6",
  "last_updated": "…",
  "last_synced_at": "…",
  "announcements": [ { "id": 7, "title": "…", "details": "…" } ],
  "providers": [
    {
      "provider_id": "groq",
      "display_name": "Groq",
      "base_url": "https://api.groq.com/openai/v1",
      "keyless": false,
      "key_url": "https://console.groq.com/keys",
      "enabled": true,
      "models": [ { "model_id": "…", "capabilities": { … } } ]
    }
  ]
}

With ?tag=, models are filtered first and providers left with no matching model are dropped entirely — so the response never contains an empty models array you have to skip over.

Operator announcements: new providers, newly verified free tiers, removals, and product updates such as the gateway launch.

{
  "version": "1.6",
  "last_updated": "…",
  "last_synced_at": "…",
  "count": 3,
  "announcements": [
    { "id": 1, "title": "New provider verified", "details": "Plain text, newlines preserved." }
  ]
}

details is plain text, not HTML or markdown. Render it in a <pre> or escape it — the rendered feed at the bottom of this page does exactly that.

The cheapest possible read, carrying no catalog data. This is the endpoint automated clients should poll.

{ "service_enabled": "1", "last_synced_at": "…" }

The value is the string "1" or "0", not a boolean. When it reports "0", the four catalog endpoints answer 503 until the operator flips it back. last_synced_at is the same field the catalog endpoints carry, so a client can watch for a stalled sync from this one cheap read.

Object reference

The two objects that appear across the API.

Model#

Provider#

Errors and status codes

Every error is JSON with a single error string. There are no error codes to switch on — the HTTP status is the contract.

async function loadCatalog(previous) {
  try {
    const res = await fetch(BASE + "/models");
    // 503 means paused, not broken: keep whatever you had.
    if (res.status === 503) return previous;
    if (!res.ok) throw new Error("HTTP " + res.status);
    const data = await res.json();
    // A malformed body must not replace a good catalog either.
    if (!Array.isArray(data.models)) throw new Error("bad shape");
    return data;
  } catch (err) {
    return previous;
  }
}

Rate limits#

There is no per-client rate limit on these endpoints and no 429. The 120-second cache is what protects the service, which is also why a tighter poll buys you nothing.

The limits on a model are a different thing entirely: those are the upstream provider's limits, per key, and they are the numbers your own client has to respect.

Model directory

The complete model directory, generated live from the catalog on page load. Capability badges are measured per model: T tool calling, V image input, R reasoning output.

Provider directory

Every provider in the catalog, with its endpoint and key information. Keyless providers need no account; the others issue free API keys through their own portals — the get a key ↗ link goes straight there.

Announcements

Catalog and product updates from the operator, newest first. The same feed is available as JSON at /announcements.

FAQ