Understand Clidex,
move faster.

About Clidex

What is Clidex

Unlike any relay/proxy service, Clidex is not a unified API gateway that reverse-proxies Claude or Codex. The Clidex client launches a real Pty interactive terminal using official Claude and Codex subscription accounts, giving you the native CLI experience.

Are Clidex’s models real?

Every model in Clidex is served directly by the official CLI. All accounts on the platform are genuine subscription accounts, which guarantees high availability and high fidelity — every model is the official, native model, with no dilution at the source.

Why we don’t reverse-proxy

Reverse-proxying means a gateway has to simulate the client and send requests on its behalf, which can never fully guarantee that the fingerprint information in each request matches. Every request Clidex sends comes from the native Claude and Codex CLI itself, so there’s no fingerprint-mismatch risk at all. Each account is also assigned an independent static IP to keep usage patterns single-purpose, which sharply reduces the odds of account suspension.

Quick Start

Install Clidex

Download and run the install script in your terminal:

• macOS, Linux, WSL

  curl -fsSL https://clidex.dev/install.sh | bash

• Windows PowerShell

  irm https://clidex.dev/install.ps1 | iex

• Windows CMD

  curl -fsSL https://clidex.dev/install.cmd -o install.cmd && install.cmd && del install.cmd

If you see The token '&&' is not a valid statement separator, you’re in PowerShell, not CMD. If you see 'irm' is not recognized as an internal or external command, you’re in CMD, not PowerShell. Your prompt shows PS C:\ in PowerShell, and C:\ (without PS) in CMD.

If the install command fails with syntax error near unexpected token '<', 403, or another curl error, see Troubleshoot installation to match the error to a fix or an alternative install method.

We recommend installing Git for Windows on native Windows so Claude Code and Codex can use the Bash tool. Without Git for Windows, Claude Code falls back to PowerShell as its shell tool. WSL setups don’t need Git for Windows.

Connect your Clidex account

• Log in to the Clidex dashboard: https://dash.clidex.dev/login
• Open the CLI Access menu and copy the one-click pairing command shown on the page (in the form clidex init https://api.clidex.dev <YOUR_TOKEN>)
• Paste the command into your terminal and press Enter — seeing “✔ Paired successfully: ” means you’re connected

init only needs to run once, and it validates the token immediately. The address must be the machine API endpoint starting with api., not the dash. dashboard address — the command shown on the page already has this right, so just copy it as-is.

Start a session

cd into any project directory and simply run:

clidex

The first time you start in a project, you’ll be prompted to choose Claude / Codex before its native interactive terminal opens. The current directory is automatically bound as your workspace. If you’ve saved a choice for this project, later launches use it directly.

After choosing an agent, your first session with that agent type also asks whether to sync your local config and the current project’s session history — see “Sync Local Config & Session History” below.

Choose and remember an agent

Use ↑ / ↓ to switch between Claude and Codex, Enter to confirm, or Esc to cancel startup. “Remember this project’s choice” is checked by default. Press Space to uncheck it if you want to be asked on every launch.

clidex                         # Use the project's saved choice, or prompt if none is saved
clidex --choose-agent          # Choose again and decide whether to remember it
clidex --claude                # Use Claude for this session only
clidex --codex                 # Use Codex for this session only
clidex --choose-agent -w ~/project  # Choose again for a specific workspace

• --claude / --codex override this session only and leave the project’s saved choice unchanged. These flags and --choose-agent are mutually exclusive.
• To restore the prompt on every launch, run clidex --choose-agent, uncheck “Remember this project’s choice,” and confirm.
• Choices are saved separately for each workspace directory. With -w, the specified directory’s preference applies. Preferences are stored locally in ~/.config/clidex/projects/, without adding files to your project.
• clidex connect and clidex max follow the same rules. Automatic account-switch reconnections keep the agent selected for this session.
• In non-interactive environments such as pipes and scripts, the saved choice is used. If none exists, specify --claude or --codex explicitly.

CLI Commands

Common flags:

Common clidex status combinations:

clidex status          # human-readable output
clidex status --json   # for scripts / monitoring

Common clidex tray flags:

clidex tray --display used                    # show percentage as "used" instead of the default "remaining"
clidex tray --interval 60s --low-balance 20    # polling interval and low-balance alert threshold

-s/--addr, -t/--token, and similar flags are an escape hatch for connecting directly to a known node during local debugging — you don’t need them for normal use. Nodes are assigned automatically by the platform based on your subscription tier, and certificates are issued along with the session.

Sync Local Config & Session History

Bring the Claude / Codex setup you’ve already tuned on your machine, plus the session history of the current project, over to Clidex — new sessions feel just like home, and /resume picks up your earlier conversations.

How to sync

clidex --load          # Sync Claude config and the current directory's session history
clidex --load codex    # Sync Codex config and the current directory's session history

--load only uploads; it doesn’t open a session or read or change the project’s saved agent choice. Omitting the type still syncs Claude; use clidex --load codex to sync Codex. It cannot be combined with --choose-agent. After scanning, it first lists what was skipped, then shows a selection list:

• ↑ / ↓ to move, Space to toggle, a to select all, Enter to confirm, Esc to cancel
• The selected items are packed and uploaded (with a progress bar); every new session picks them up automatically
• Each selected category is replaced as a whole: e.g. if you select skills, skills you deleted locally are deleted on the platform too; unselected categories stay as they are on the platform
• Press Ctrl+C during the upload to exit — the whole upload is discarded and previously synced config is untouched
• When not running in a terminal (pipes, scripts), no list is shown and everything is synced

You’ll be asked on your first session with each agent type: after clidex init, the first time you use Claude or Codex, its selection list asks whether to sync. Press Esc to skip and go straight into the session.

Syncing requires a positive account balance. With insufficient balance you’ll be asked to top up first, and the first-session prompt is skipped until your first session after topping up.

What gets synced

settings.json preferences

Only the following personal preferences in settings.json are synced; every other field is left out:

• A value is only updated when it changed locally, so settings you changed in a session via /config won’t be reverted
• Values the platform doesn’t support (e.g. custom: themes) are listed in the scan summary and skipped

Other notes

• Not synced: the env, hooks, permissions, model and other fields of settings.json, as well as config.toml, MCP, plugins and memory (memory/). These can point sessions at other API endpoints or run machine-specific commands, so they don’t belong in the cloud
• Scripts inside skills keep working in sessions
• Symlinks are followed; directories like .git and node_modules are skipped
• Limits: 1 MB per file, 20 MB and at most 2000 files of config in total; anything over the limit is listed in the scan summary

Session history

• Only the current working directory’s sessions are synced (the current directory, or the one given with -w; sessions started in subdirectories don’t count). To sync another project, cd into it and run clidex --load or clidex --load codex again; if the current directory has no local session records, that item won’t appear in the list
• After syncing, start the matching agent (clidex --claude or clidex --codex) in the same directory and use /resume to pick up where you left off. You can also run clidex if the saved or prompted choice matches that agent
• Reasoning content is removed on import: it’s bound to the model and account that produced it, fails verification on the platform’s accounts, and would prevent the session from being resumed. The surrounding messages are re-linked, so the conversation itself is unaffected
• Sessions that already exist on the platform aren’t overwritten (you may have continued them there); they’re only updated when you’ve continued the conversation further locally
• Limits: 50 MB per session, 200 MB in total

Premium Max

Users whose balance meets the platform threshold can open sessions on Max-tier subscription accounts only:

clidex max             # Use the project's saved agent, or prompt if none is saved
clidex --claude max    # Claude, Claude Max subscription accounts only
clidex --codex max     # Codex, ChatGPT Pro (including Pro Lite) subscription accounts only

• Balance threshold: your balance must be at least the threshold set by the platform. Otherwise the session is refused and the terminal shows the threshold and your current balance — top up and retry, or drop max to use normal allocation
• Automatic fallback when no Max account is available: the session still opens on a regular account, and the terminal tells you no Max account was available this time — you’re never locked out
• Automatic account switching also prefers Max: when the account’s quota hits the threshold mid-session and Clidex switches accounts, it still prefers a Max account and only falls back when none is available
• Other flags work as usual, e.g. clidex max -w ~/project --no-tray

How It Works

Credential quota threshold reached: automatic account switch with session continuation

Each account may have multiple upstream AI credentials bound to it. When the credential currently in use approaches the usage threshold set by the platform, the platform proactively closes the current session and has the client re-request one — the entire process requires no manual intervention:

1. The terminal prints a notice: Current account's credential quota is low, switching accounts and resuming your session (attempt N/3, retrying in X) ...
2. The CLI keeps this session’s selected agent (Claude / Codex), automatically re-requests a session from the platform, and receives a new credential and execution node
3. Your previous conversation context is carried over — there’s no need to restate your request
4. Retry intervals increase with each attempt (2s, 4s, 6s), up to 3 automatic reconnect attempts; if it still fails, you’ll get a clear error prompting you to manually run clidex connect again
5. Sessions started with clidex max also prefer a Max account when switching

This mechanism requires no user intervention — during the process you’ll only see the terminal briefly pause while it prints the switch notice.

Insufficient balance / no accounts available: new sessions are refused, running sessions are not cut off

If your balance is insufficient, or the execution layer isn’t temporarily ready and the account pool has no node to assign, the platform will not forcibly interrupt a session that’s already running. Instead, it refuses outright whenever you request a new session — including the very first clidex connect, as well as the automatic account-switch reconnection described above. The reason for the refusal is generated by the platform and printed directly in the terminal (e.g., insufficient balance, no accounts available, etc.). When this happens, you need to top up in the dashboard or contact an administrator — it won’t resolve itself automatically.

The tray: your only window into the automatic switching above

By default, clidex / clidex connect attaches a ring-progress icon to your menu bar / notification area (disable with --no-tray), which automatically disappears when the session ends; you can also run clidex tray to keep it running persistently on its own. It’s the only place, while you’re coding, where you can see events the platform doesn’t otherwise announce — like low-balance alerts:

• Pay-as-you-go: the icon shows your balance directly, turning yellow below --low-balance (default $5) and red below a fifth of that
• When status can’t be read, it shows ?, distinct from an actual “zero usage” state

Acceleration channel and auto-update (supporting mechanisms)

• On poor network conditions (cross-border routing, ISP detours), a session can route the underlying TCP through an SSH / HTTP relay; TLS is still negotiated end-to-end between the client and the execution node, so the relay only forwards bytes and never sees the content. If the channel can’t connect, it automatically falls back to a direct connection rather than blocking the session.
• clidex connect / status check for a new version in the background at most once per day; if a new version is available, it’s downloaded and swapped in the background while your session keeps running, with a notice shown once the session ends — the next launch will use the new version. Set the environment variable CLIDEX_AUTO_UPDATE=0 to only notify without auto-switching, or CLIDEX_UPDATE_CHECK=0 to skip the check entirely.