Skip to main content

Set up your tools with proxium login

One command signs you in and sets up every AI tool on your machine. It finds Claude Code, OpenCode, Pi, Hermes, Codex, Gemini CLI and Cursor, and skips the ones that are not installed.

  1. Run npx proxium login. It needs node 20 or later. The first run copies the command to ~/.local/bin/proxium, so later you run proxium by name. To install it without npm, run curl -fsSL https://proxium.tech/install.sh | sh, then proxium login.
  2. The command signs you in. The browser opens with a code. On a machine with no display, the command prints the code and the page, and you approve it on any device.
  3. Approve the code. Then each tool shows the Proxium MCP server, and the command starts each tool's own sign-in.

After the approval the command also does these steps for your project:

  • It uses your only project, the one that --project names, or a new one.
  • It keeps your login in sealkeep, else in the keyring of your OS, else in a file only you can read.
  • It keeps the project for proxium launch.
  • Claude Code, OpenCode, Pi and Hermes use your login and get no key. Each one runs proxium token when it needs a key:
    • Claude Code through claude-proxium, which runs proxium launch claude.
    • Pi and Hermes through their model provider settings.
    • OpenCode through a small plugin in ~/.config/proxium/opencode-plugin.
  • An OpenCode before version 2 gets one app and one key. The key goes to sealkeep, else to the keyring of your OS, else to a file only you can read. Its configuration names the key variable and never holds the key.
  • It adds Proxium as a model provider in OpenCode, Pi and Hermes, and writes a launcher for each tool: opencode-proxium, pi-proxium, hermes-proxium and claude-proxium. They start the tool with the model auto.
  • In Hermes it also puts the headers of Proxium on model.extra_headers, merged with the ones you set there. Hermes reads that key, and not the provider entry, for its auxiliary calls (the title of a session, compression, vision). Without the project, a login that names several projects fails on them with project_required.
  • It sends one test call for each new key.

Run proxium login again at any time. It repairs or refreshes what is there and makes no second key for a tool that has one. A project that cannot route yet needs the platform pool. The operator of the gateway gets it from the command, and anyone else asks the operator.

The two modes​

Full Proxium (recommended). Start the tool through Proxium: proxium launch claude, or the launchers opencode-proxium, pi-proxium and hermes-proxium. Every call of the session goes to the model auto, the main agent's and each subagent's, and the classifier picks the model of each call. In Claude Code, the models haiku, sonnet and opus that a subagent names are auto too. A subagent with effort: low gets the reasoning level low.

Proxium as a vendor. Start the tool as usual, with its own main model. Its subagents run on Proxium:

  • OpenCode gets two subagents in ~/.config/opencode/opencode.json: coder and verifier, on proxium/auto. Change model in the file to pin one model. An agent of the same name that you wrote stays as it is.
  • Hermes sends the subagents of delegate_task to proxium/auto, when you set no other delegation provider.
  • Pi has no subagents. Choose proxium/auto as its model to use Proxium.
  • Claude Code: see Claude on your login, agents on Proxium.

Run proxium login --no-agents to change no subagent.

Claude on your login, agents on Proxium​

proxium launch claude --agents starts Claude Code on your own Claude login. A local router sits between Claude Code and the model providers:

  • A call with a Claude model goes to Anthropic, with your Claude login, as it came.
  • A call with any other model goes to Proxium, with your Proxium login. Your Claude login never goes to Proxium.

To run a subagent on Proxium, name a Proxium model in its file, .claude/agents/<name>.md:

---
name: coder
description: Coding worker. Use for any coding task.
model: <vendor>/<model>
effort: low
---
Write the code that the task asks for, and run its tests.

model: auto lets Proxium choose. effort becomes the reasoning level of the call. Claude Code reads a new or changed agent file while it runs.

You can also ask in the chat, with no file. For example: "Start an agent on <vendor>/<model> with effort low." Claude then puts proxium:<vendor>/<model> at the start of the description of the subagent. A mod in ~/.config/proxium/claude-mod, which the command loads with --plugin-dir, makes that id the model of the subagent.

proxium launch claude --agents
proxium launch claude --agents --project acme-1a2b3c
PROXIUM_ROUTER_LOG=/tmp/routes.log proxium launch claude --agents
  • The router listens only on 127.0.0.1, on a random port and path, and stops when Claude Code ends.
  • Claude Code keeps the config folder it uses today, so your settings, plugins and login stay as they are.
  • PROXIUM_ROUTER_LOG writes one line for each call: the model, where it went and the status.
  • With CLAUDE_CODE_SUBAGENT_MODEL_FORCE set, Claude Code ignores the model of each subagent file, and no subagent reaches Proxium. The command warns when it finds the variable.

Plan reuse in the router​

With --plan shadow or --plan skip, the router adds plan reuse to the Claude calls that offer tools. It works as Plan reuse describes, with three differences:

  • The plans, the gates and the records stay on your machine. The gates are in ~/.local/state/proxium/plan-gates.json, and the fill gate of each model is in ~/.local/state/proxium/plan-fill.json. The records are in ~/.local/state/proxium/plans.jsonl. Nothing about them goes to Proxium.
  • A file_exists guard reads the file system of your machine.
  • With extended thinking on, the router puts a skipped call into the assistant turn before it, as a second tool call. The last turn of the next call then starts with its thinking block.
proxium launch claude --agents --plan shadow   # measure only
proxium launch claude --agents --plan skip     # skip the planned reads of proven pairs
PROXIUM_PLAN=skip proxium launch claude --agents
proxium plans                                  # the report of the last 7 days
proxium plans --days 30

Another Claude account​

Claude Code keeps one login in each CLAUDE_CONFIG_DIR. Name the folder ~/.claude-<account>, and proxium launch claude-<account> runs that login with the same router:

CLAUDE_CONFIG_DIR=~/.claude-work claude   # sign in to the work account once
proxium launch claude-work                # it always runs with --agents
proxium launch claude-work -- --resume <session id>

The folder must exist: an account that never ran claude has no login to keep. A claude-<account> tool always runs with --agents, because that account's Claude login is the point of it.

Start Claude Code with your login​

proxium launch claude starts Claude Code with Proxium as its model provider. Claude Code runs proxium token for its key, so it keeps no key and never holds an expired one.

proxium launch claude
proxium launch claude -- -p "Explain this function"
proxium launch --project acme-1a2b3c claude
  • The project is --project, else the variable PROXIUM_PROJECT, else the project of proxium login.
  • The model is auto unless you set ANTHROPIC_MODEL. Any Proxium model or tier works, such as ANTHROPIC_MODEL=code.
  • Claude Code uses its own config folder, ~/.claude-proxium, so it never uses a subscription login. Your ~/.claude/CLAUDE.md is linked into it.
  • The Proxium MCP server is in the session too, with your login. It needs no second sign-in.
  • Each call shows in the log of the project under the app claude-code.

Use your login in a script​

proxium token prints a token of your login. A tool or a script sends it as the key, with the project in x-proxium-project:

curl https://proxium.tech/v1/chat/completions \
  -H "Authorization: Bearer $(proxium token)" \
  -H "x-proxium-project: acme-1a2b3c" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'

The token expires soon after it is made. Run proxium token for each call, or when the gateway answers invalid_token. The command gives the same token until it is close to its end, then a new one. When your login expires, it asks you to run proxium login again.

Change the routing as a file​

proxium routing exports the routing of your project as a YAML file. Change the file, plan it and apply it:

proxium routing export -o routing.yaml
proxium routing plan routing.yaml
proxium routing apply routing.yaml

The format and the other commands are in the routing document.