Repository navigation
Providers
A provider is an agent or model service that runs threads. Parallax runs each vendor's own agent with your own sign-in or API key. Providers belong to a computer: sign in on the computer that runs the work, which may not be the one you're sitting at (Hosts).
The page shows one computer's providers at a time, with a picker for the computer. Each provider has a switch that turns it on or off on that computer. One stays on. A provider that's off leaves its models out of new threads and model menus.
Its header has Refresh, Add provider (+), and Remove for the chosen provider. Removing one takes its settings and secrets off the computer. Its threads keep their transcripts.
A provider's page has these parts:
| Part | Holds |
|---|---|
| Account | Display name, then Install while it isn't installed, else its sign-in state with Sign in or Sign out |
| Runtime | Binary path, a home folder for a second account, launch arguments, and Version for OpenCode and Pi |
| Environment | Variables its runs get, such as API keys and base URLs |
| Models | Favorites, which models the model menu shows and in what order, and Add custom model |
| Usage | Claude Code and Codex only: what the account used today or this week |
| API keys | Claude Code and Codex only: Anthropic or OpenAI keys (API keys) |
A variable whose name has KEY, TOKEN, or SECRET in it is a secret by default. Secrets are kept in the computer's keychain, never shown again, and read only when a run starts. Favorites and model order are kept on this device. Custom models are kept on the computer (0040).
When plxd first runs on a computer, it adds Claude Code and Codex if their CLI is installed, and Cursor.
Add provider opens a dialog in three steps: Provider, Identity, and Config.
- Provider. Pick a card, or search the ACP Registry below the cards. Registry agents that run with npx or uvx are set up for you. One that ships as a binary needs it installed on the computer first.
- Identity. A display name and an id. The id can't change later.
- Config. The binary path, home folder, arguments, and variables. Some cards ask for a key here.
The cards are Claude Code, Codex, Cursor, Pi, OpenCode, Ollama Cloud, Hermes Agent, OpenRouter, and Local model. Grok Build and Antigravity come from the ACP Registry, and Parallax sets them up as their own kinds.
| Provider | How Parallax runs it | Sign in | Install |
|---|---|---|---|
| Claude Code | Your claude CLI, through the Claude Agent SDK (0061) |
claude auth login |
Anthropic's installer |
| Codex | codex app-server |
codex login |
npm install -g @openai/codex |
| Cursor | The Cursor SDK (0053) | In your browser, or CURSOR_API_KEY
|
plxd downloads the SDK |
| OpenCode 1.x | Its HTTP server (0055) | opencode auth login |
npm, in the background |
| OpenCode 2.x | opencode2 acp |
opencode2 auth login |
Install the binary yourself |
| Ollama Cloud | Hermes Agent's Ollama Cloud provider (0070) | API key in OLLAMA_API_KEY
|
Hermes Agent's installer |
| Pi 1.0, 0.x |
npx -y pi-acp@0.0.34, or @0.0.27 for Pi 0.73 |
Login runs pi, then /login
|
npm, in the background |
| Hermes Agent | hermes acp |
hermes setup --portal |
Hermes Agent's installer |
| Grok Build | grok agent stdio |
grok login |
xAI's installer |
| Antigravity | Google's ACP server, agy_acp_server.par
|
The agent's own sign-in | Downloads the server (macOS and Linux) |
| OpenRouter | Claude Code against OpenRouter | Key in ANTHROPIC_AUTH_TOKEN
|
Needs Claude Code installed |
| Local model | Claude Code against your own server, http://127.0.0.1:8080 by default |
None | Needs Claude Code installed |
| ACP agent | Any agent that speaks the Agent Client Protocol | The agent's own sign-in methods | From the registry, or by hand |
Install runs on the provider's page. Most installers run in a terminal on that computer. Pi and OpenCode install with npm in the background, on macOS and Linux into ~/.local. Hover Install to see the command.
Parallax runs the claude it finds on the computer, or the binary path you set, through the Claude Agent SDK in a Node sidecar. Claude Code's own updates come from your claude.
- Needs Node.js 22.16 or newer. Without it, the page says "Node.js 22.16 or newer is required" and Claude Code threads can't start.
- The SDK installs itself into
~/.parallax/tools/claude-agent-sdk/the first time Claude Code is used on a computer. Its progress shows under Runtime > Claude Agent SDK.
Parallax runs codex app-server with your CODEX_HOME, or the one set on the provider.
Cursor runs through Cursor's SDK in a Node sidecar. It needs Node.js 22.13 or newer and npm. Install downloads the SDK into ~/.parallax/tools/cursor-sdk/.
Sign in opens Cursor's sign-in in your browser. Approve it there, and the page shows the account. Sign out forgets it. A CURSOR_API_KEY variable on the provider replaces the browser sign-in. A CURSOR_API_KEY set in your shell is not used.
Cursor has no Supervised access, can't revert a turn, and can't fork a session natively (Threads).
OpenCode 1.x runs through its HTTP server. Leave Server URL blank and Parallax starts opencode serve on 127.0.0.1 for each run, with a password of its own. Or give the URL of a server you run, and its password, which is kept in the keychain. The Version setting switches to OpenCode 2.x, which runs as opencode2 acp.
Below Full access, an OpenCode thread runs no subagents.
Ollama Cloud needs an API key in OLLAMA_API_KEY. It runs on Hermes Agent's own Ollama Cloud provider, in a Hermes home of its own, so it shares nothing with a Hermes Agent you use directly. Install puts Hermes Agent on the computer. Models are listed from Ollama Cloud.
Both run Claude Code against another endpoint set in ANTHROPIC_BASE_URL, with the key in ANTHROPIC_AUTH_TOKEN. Local model points at http://127.0.0.1:8080 with the token local. Change both to match your server. Models are listed from the endpoint's /v1/models.
Any agent in the ACP Registry, or any program that speaks ACP, can run threads. Its sign-in comes from the agent itself: a terminal command, or a browser flow it starts. Parallax enforces Access levels by answering the agent's permission requests (Threads).
Sign in, on a provider's page, runs the provider's sign-in command in a terminal on that computer, even over SSH. When the terminal closes, Parallax checks the provider again and its Account row shows the result. Cursor signs in through your browser instead.
The first-launch setup offers the same Install and Sign in buttons for this computer's agents (Getting Started).
The Claude Code and Codex pages each have an API keys section, for Anthropic and OpenAI keys. Add API key takes a label and the key. The key is kept in the computer's keychain and only shown masked after that.
A key is a fallback for a subscription (0012). When a Claude Code or Codex thread fails because the subscription is signed out or has hit a usage limit, plxd starts it once more on a key for the same provider. A Project's subagents don't fall back to a key on their own.
Other providers take their keys as variables on the provider, such as OLLAMA_API_KEY, ANTHROPIC_AUTH_TOKEN for OpenRouter, and CURSOR_API_KEY.
A computer can have more than one provider of the same kind, each signed in on its own. Give each its own home folder in Runtime, such as CLAUDE_CONFIG_DIR or CODEX_HOME. The model menu then offers an account chooser for that provider.
Parallax warns when you add a second account of Claude Code, Codex, Cursor, Grok Build, or Antigravity: "Several accounts of one provider in one app aren't supported. Switching between them puts the accounts at risk. For many accounts, use a CLIProxyAPI hub." (0088)
Hubs, under Settings > Providers, connect a CLIProxyAPI hub that holds the accounts (0089).
- Add hub takes a name, the hub's URL, its access key, an optional management key, and which computers to add it to.
- Each hub adds a Claude Code and a Codex provider that run through it. The model menu shows them as another account, with the hub's models.
- With a management key, the hub's page lists its accounts with their plan and limits, and Add an account signs one in to the hub in your browser.
A Project places each subagent on the provider its composer picked. When that account is out of quota, plxd uses another provider of the same kind with the most room left, or holds the subagent until one frees up (0046).
The Usage page (Mod+Alt+U, or Usage in the sidebar) adds up every connected computer (0039).
| View | Shows |
|---|---|
| Cost | Cost by provider and model over Today, 7 days, 30 days, or 90 days, against the range before |
| Tokens | Processed tokens, cached and uncached input, cache writes, and output, over the same ranges |
| Limits | Each subscription's limit windows and how much of each is used |
Where the numbers come from:
-
Claude Code and Codex: their own logs on each computer, read with ccusage. Parallax runs
ccusageif it's installed, elsenpx -y ccusage@20, so the computer needs Node.js or ccusage. This counts every session on that computer, not only Parallax's. - Cursor: Cursor's usage API, with the sign-in of the Cursor desktop app on that computer. Without it signed in, Cursor shows nothing.
Other providers don't show on the Usage page.
Pull requests go through the GitHub CLI, gh, on each computer (0050). Set it up in Settings > Source control, which has its own computer picker:
-
Install, if no
ghis found. Parallax downloads the latest release, checks its checksum, and puts it in~/.parallax/tools/gh. Aghyou installed yourself is always used first. -
Sign in. Parallax starts
gh auth loginand shows the one-time code with Copy and Open GitHub. The code expires after 15 minutes. - Enter the code on GitHub. The row then says Signed in as @your-login.
After signing in, Parallax runs gh auth setup-git, so git push over HTTPS uses the same sign-in. gh keeps the token, and Parallax never reads it. If a pull request action fails because gh isn't ready, it offers Set up GitHub.
| Need | For |
|---|---|
| Node.js 22.16 or newer | Claude Code |
| Node.js 22.13 or newer, and npm | Cursor |
| npm | Installing Codex, Pi, and OpenCode from Parallax |
| Node.js or ccusage | Claude Code and Codex on the Usage page |
| The agent's own CLI on the computer | Every provider but Cursor. OpenRouter and Local model use Claude Code, and Ollama Cloud uses Hermes Agent. |
Start
Using Parallax
Your computers
Maintenance
Contributing