Nexus Composer

Nexus Composer is a desktop app that lets the AI agents your team already uses call OneNexus-hosted models — without switching tools, and without hand-maintained proxy settings or model IDs.

Codex Desktop, Codex CLI, VS Code, Claude Desktop, and Claude Code CLI are the agents Composer supports today, and more are being added. Setup is the same for every agent until Choose your client, where each one has its own steps.

Composer lets you switch the active provider for a client. Each request still goes to exactly one provider — never to both. When OneNexus is selected, a local proxy converts the client’s protocol and forwards the request.

Composer must stay running

While a client is routed through OneNexus, its requests go through Composer’s local proxy. If you quit Composer, those requests fail. Leave it running, or switch the client back to its original provider first.

Quick-start video (1:30): the six steps from creating an API key to sending a test. The detailed steps follow below.

What you need

Requirement	Detail
Pilot access	An approved OneNexus pilot account and tenant — if you lack one, request pilot access.
Operating system	macOS 14 or later on Intel or Apple silicon, or Windows on x64 or ARM64. Linux (Ubuntu 24.04+) is coming soon.
Client	Codex Desktop, Codex CLI, VS Code, Claude Desktop, or Claude Code CLI — the agents supported today. More are being added.
Nexus API key	A Platform API key from the console. Open Inference → API Keys → Generate API key, set Type to Platform, and copy the secret when shown.
ChatGPT login	Only needed for OpenAI Official models in Codex.
Claude login	Only needed to keep Claude’s own models in Claude Code CLI (Claude + OneNexus mode).
Network	Outbound access to OneNexus, to OpenAI when using OpenAI Official, and to Anthropic when using Claude’s own models.

An Inference key reaches only the Served Model Names of its selected self-hosted models, not the hosted catalog Composer uses. A Platform key is the credential Composer needs — it calls every published catalog model, including models added later, and cannot be narrowed. Check the Type column under Inference → API Keys if unsure: a Platform key shows Platform.

Composer checks the client versions it supports — after installing, open Settings → About for the current minimum versions, which change with client releases.

Download and install Composer

Only use installers from the official Nexus Composer download page, which validates the release manifest and every installer it currently offers before enabling a download.

If downloads are temporarily unavailable, reload the page later or contact your onboarding contact — never use an unofficial mirror.

macOS

A single universal installer runs on both Intel and Apple silicon Macs — there is only one macOS .dmg to download.

1. Download the macOS .dmg from the official page.
2. Open the disk image and follow its installation instructions.
3. Launch Nexus Composer from Applications, then eject the disk image.

Signing and notarization may vary during the pilot. If macOS blocks the installer, confirm it’s from the official page, then ask your onboarding contact before overriding the warning.

Windows

There are two Windows installers, one per processor type. Most PCs are x64; choose ARM64 for PCs with a Snapdragon (ARM) processor. To check, open Settings → System → About and read System type.

1. Download the .msi for your PC — x64 or ARM64 — from the official page.
2. Run the .msi and follow the setup wizard.
3. Launch Nexus Composer from the Start menu.

If Windows SmartScreen warns about the installer, confirm it’s from the official page, then ask your onboarding contact before choosing to run it anyway.

Open Composer for the first time

1. Open Nexus Composer and dismiss the first-run notice after reading it.

2. Until a Nexus account is connected, Composer shows a OneNexus is not connected banner above each client page. Choose Manage API key on it to open the Nexus Account card.

   

   Shown above the VS Code page; the Codex page carries the same banner. Manage API key is the shortest way to the Nexus Account card — the gear icon, then General, reaches the same place.

You can manage the OpenAI Official route without a Nexus account — the banner says as much. OneNexus-hosted models need the Platform key from the next section.

Connect your Nexus account

Don’t have a Platform key yet?

Create one in the OneNexus Console before you continue: Inference → API Keys → Generate API key, with Type set to Platform. Copy the secret while the dialog shows it — it cannot be displayed again.

A Platform key shows no model list — it calls the whole catalog and cannot be narrowed.

Platform is the only type that works here. It calls every published catalog model, which is what Composer routes to; a key scoped to your own self-hosted models cannot reach that catalog, and swapping secrets is not a way to find out which one you have. Check the Type column under Inference → API Keys instead.

Under Settings → General → Nexus Account:

1. Paste your Platform key into Nexus API Key, then choose Connect.

   

   Before you connect, the card reads Not connected and Connect is greyed out.

2. Wait for validation and confirm that the status reads Connected.

3. Check that the displayed username and tenant are yours. Stop here and contact your onboarding contact if either is wrong.

On success, Composer validates the key, stores it in your OS credential store, downloads the managed catalog, and updates only the client profiles it manages — other Codex settings, MCP configuration, skills, and sessions stay untouched.

Use Replace API Key to connect a replacement, and Forget key to remove the stored credential.

Connected plus a username and tenant you recognise. If either is wrong, stop here.

Keep the key out of everything else

Never paste a Nexus API key into a screenshot, log, support message, Git repository, prompt, or hand-edited configuration file. If a key is exposed, revoke it in the console and connect a replacement.

Check your client installation

Open Settings → About. Composer detects each supported client, compares found versions against a minimum version, and warns about conflicting installations.

If Codex CLI is missing, use Install. If Composer finds more than one Codex installation, choose Diagnose installs and confirm which executable your shell runs before changing anything.

Composer does not install or update Claude Desktop or Claude Code CLI. If either card shows Update recommended, update that client yourself.

Each client is checked against the version Composer needs. Diagnose installs is the button to reach for when it finds more than one Codex.

Before your first request

Your data is not retained

Prompts and outputs are not retained, and are not used to train or fine-tune OneNexus models. See Pilot & security.

Choose your client

Composer changes the route for one client at a time. Claude Desktop and Claude Code CLI are the exception: they share the Claude page, and selecting a card there switches both. Pick yours.

Codex Desktop

The card marked Effective route is where requests actually go.

Codex Desktop starts on OpenAI Official, and stays there until you change it — Composer shows that card as Active. OneNexus sits beside it with a Select button, and nothing moves until you press it.

1. Choose Select on the OneNexus card to route Codex through OneNexus. Wait until that card reads Active and carries no warning.

   

   Active and Effective route have moved to OneNexus. The banner names the next step: Composer will not restart Codex Desktop for you.

2. Quit Codex Desktop — not just its window — then reopen it. It keeps the route it started with.

3. In a new conversation, open the model picker. The OneNexus models now sit alongside the OpenAI ones — choose the one you want and start your first chat.

   

   OneNexus models are prefixed with the provider, so they are easy to tell apart from the OpenAI ones.

To keep OpenAI Official models selectable alongside the OneNexus ones, sign in to ChatGPT inside Codex Desktop. Composer manages the OneNexus catalog itself — what you see depends on your tenant, current availability, and whether Codex restarted after a catalog change.

Without a ChatGPT login

On the OneNexus card, open settings and enable Use OneNexus without ChatGPT sign-in, then restart Codex Desktop. This mode publishes only the compatible OneNexus catalog and may hide OpenAI Official models — leave it off to switch providers from the model picker.

Enable Use OneNexus without ChatGPT sign-in on the OneNexus card, then restart Codex Desktop.

Codex CLI

One card serves both Codex clients — there is no separate route for the CLI.

Codex CLI shares Composer’s Codex route, so the card you select is the same one Codex Desktop uses.

1. Choose Select on the OneNexus card to route Codex through OneNexus. Wait until that card reads Active and carries no warning.

2. Exit every running Codex CLI process, then start Codex again in a new terminal — a running process keeps the configuration it started with.

3. Confirm a OneNexus model is selected, then start your first chat.

   

   The red warning is expected: that overridden base URL is Composer’s local proxy. Unlike Codex Desktop, the CLI lists OneNexus models without a provider prefix — they are the entries below the gpt- ones.

Restart the CLI after every provider change, not only this first one.

VS Code

Composer’s VS Code tab opens a page titled Visual Studio Code chat.

This routes VS Code’s built-in Chat agent. It starts on GitHub Copilot and stays there until you change it — Composer shows that card as Active. OneNexus sits beside it with a Select button, and nothing moves until you press it.

1. Choose Select on the OneNexus card to route VS Code Chat through OneNexus. Wait until that card reads Active and carries no warning.

2. Open or reload VS Code so it picks up the new model group.

3. In a new Chat conversation, pick a OneNexus model and start your first chat.

   

   VS Code names the provider to the right of each model. Only the current one sits at the top — expand Other Models to reach the rest.

Composer adds these as a model group it manages, and in VS Code they are text only — no images or file attachments.

Claude Desktop

Composer’s Claude tab opens a page titled Claude. It has two cards, Anthropic official and OneNexus, and sets up Claude Desktop and Claude Code CLI separately. It starts on Anthropic official, which Composer shows as Active, and nothing moves until you choose Select on OneNexus.

One page serves both Claude clients. The status line above the cards shows where each one sends its requests.

1. Choose Select on the OneNexus card. Wait until that card reads Active and carries no warning. A notice asking you to restart the Claude clients is expected. The status line above the cards then reads Claude Code: Combined · Claude Desktop: OneNexus.

   

   The restart banner is expected. Composer will not restart Claude Desktop or Claude Code for you.

2. Quit Claude Desktop — not just its window — then reopen it. Composer does not restart it for you.

3. Start a new chat, or a new Code or Cowork task, and choose a OneNexus model in the model picker.

With OneNexus selected, Claude Desktop uses only OneNexus models. It needs no Claude login, and your existing login is kept. Claude Desktop cannot show Claude’s own models next to OneNexus ones — only Claude Code CLI can.

To change Desktop’s setup, choose the gear icon on the OneNexus card to open OneNexus Claude settings. Changes save on their own. Under Claude Desktop:

• Use OneNexus gateway turns on when you select OneNexus. Turn it off to send Claude Desktop back to Claude’s own models.
• Default model is the OneNexus model new Desktop sessions start on.
• Tool network access sets which hosts tools can reach in Code and Cowork tasks. It doesn’t turn on hosted web search.
  • All hosts (default): tools can reach any host.
  • Selected hosts: tools can reach only the hosts you list in Allowed hosts, one per line.
  • Inference only: tools can’t reach the network. Model requests still work.
• Thinking effort per model sets each model’s thinking effort, for Claude Desktop only.

Each change saves as you make it — there is no Save button. After changing Tool network access, quit and reopen Claude Desktop and start a new Code or Cowork task.

A tool can’t reach the network

Choose All hosts, or choose Selected hosts and add the host to Allowed hosts. Then fully quit and reopen Claude Desktop and start a new Code or Cowork task.

To go back, choose Select on Anthropic official. Composer restores the settings both Claude clients had before; restart both afterwards.

Claude Code CLI

The same card serves both Claude clients — there is no separate route for the CLI.

Claude Code CLI shares Composer’s Claude page with Claude Desktop, so the card you select is the same one Claude Desktop uses. Its mode and default model are set separately.

1. Choose Select on the OneNexus card. Wait until that card reads Active and carries no warning. A notice asking you to restart the Claude clients is expected. The status line above the cards then reads Claude Code: Combined · Claude Desktop: OneNexus.
2. Exit every running Claude Code session, then start Claude Code again in a new terminal.
3. Run /model and confirm a OneNexus model is selected, then send your first message.

In /model, each OneNexus entry names OneNexus in its description. New sessions start on the Default model set in Composer.

Each switch from Anthropic official to OneNexus puts the CLI in Claude + OneNexus mode, even if you chose another mode before. To change it, choose the gear icon on the OneNexus card to open OneNexus Claude settings, and pick a mode under Claude Code CLI:

• Claude + OneNexus shows Claude’s own models and OneNexus models together. Claude’s models use your Claude subscription; OneNexus models use your Nexus account.
• OneNexus only shows only OneNexus models. It needs no Claude login, and your existing login is kept.
• Anthropic official returns the CLI to Claude’s normal login and models. Composer no longer handles its requests.

Claude + OneNexus is the mode the CLI lands in after each switch to OneNexus. The Default model here applies to the CLI only.

Default model under Claude Code CLI sets the model new sessions start on. Restart Claude Code after any change here.

Without a Claude subscription

Choose OneNexus only. Claude’s own models in Claude + OneNexus need a Claude subscription and login.

In Claude + OneNexus mode, requests for Claude’s own models also pass through Composer, so they fail too if Composer quits. Set thinking effort with /effort inside Claude Code; the effort settings in Composer apply to Claude Desktop only.

To go back, choose Select on Anthropic official. Composer restores the settings both Claude clients had before; restart both afterwards.

Usage and proxy

The chat you just sent should appear under Settings → Usage Statistics, with its application, provider, and model. That view is Composer’s local record of the AI requests it routed — opening Composer alone creates no entry, and the displayed cost is an estimate, not an invoice. See Skills and prompts for this view’s fields and limits.

For Claude Desktop and Claude Code CLI, choose the Claude (via Nexus) filter. It shows both Claude clients together.

With Codex and Today selected, Total Requests counts what Composer routed. Your chat’s own row, with its provider and model, is under Request Logs below the chart.

To check the proxy, open Settings → Routing, expand Local Routing, and confirm the service is Running. It listens on 127.0.0.1, bound to the loopback interface — use Restart on the same screen if unhealthy.

Running on the Local Routing card is the signal. Without it, a client routed through OneNexus has nothing to talk to.

Keeping Composer up to date

Composer updates itself — you don’t reinstall from the .dmg or .msi for each release. Open Settings → About: the Nexus Composer card at the top carries the app’s own version and update control, separate from the client cards under Local environment check.

1. On the Nexus Composer card, choose Check for Updates.
2. When a newer release exists, the card shows New version available and the Check for Updates button changes to Update to the new version — choose it.
3. Composer downloads and installs the update, then restarts itself.

The Nexus Composer card carries the app’s own version. When you’re up to date the button reads Check for Updates; when a release is waiting it names the version to install — here, Update to v3.24.6.

Next steps

• Skills and prompts — manage reusable Codex tools and understand local usage statistics.
• Composer troubleshooting — work from a symptom and collect safe details for support.
• Protocol conversion — understand what the local proxy sends to each upstream provider.
• Platform quickstart — call a hosted OneNexus model directly from your own code.