Skip to content
Nocturnal
Go to the app

Model providers and API keys

Nocturnal runs coding agents by driving a provider's own command-line tool on your computer. Two are supported:

  • Claude Code (Anthropic) — the Opus, Sonnet, and Fable models
  • OpenAI Codex — the GPT models your OpenAI or ChatGPT account can use

Both appear in the same model picker on the composer. Picking a GPT model runs Codex; picking Opus runs Claude Code. Nothing else about a session changes.

Nocturnal looks first, asks second

The first thing Nocturnal does is scan this computer for agent tools you already have. It checks your PATH and the usual install locations on macOS and Windows — including every Node version under nvm, where a global npm install usually lands — then reads each tool's own sign-in state. If it finds one, that is what your agents use — there is nothing to paste and no key to create.

Settings → Providers shows the result as a short list: what was found, which version, and how it is signed in. A tool signed in on a subscription says so explicitly, because that is the case where you owe nothing extra.

You can switch any provider off there. Off means Nocturnal ignores it even though it is still installed and working — the models stay visible in the picker but refuse to launch, and the picker says why.

Using a subscription you already pay for

If you have signed the provider's CLI in yourself, Nocturnal uses that session as-is:

  • Claude Code: claude login signs in with your Claude plan.
  • Codex: codex login signs in with your ChatGPT plan (Plus, Pro, or Business).

This is the cheapest path and the one to prefer. Usage counts against the plan you already have. Nocturnal never sees those credentials — they stay in the CLI's own config (~/.claude, ~/.codex) and Nocturnal only reads whether a sign-in exists, never the tokens themselves.

Nocturnal does not resell model access. Its own subscription covers the app, not the models.

Using an API key instead

An API key is an alternative to signing in with a subscription. It is a long secret string that identifies your account to the provider, and usage on a key is billed per token directly by that provider, separately from any subscription. A key is worth using when you do not have the matching consumer plan, or when you want agent usage billed to an organisation account.

Create one here:

Both consoles show a key exactly once. Copy it before closing the dialog; if you lose it, delete that key and make another. A key you paste somewhere by mistake should be deleted from the console immediately — revoking it there is what actually stops it working.

Paste the key into Settings → Providers. It is written to ~/.nocturnal/secrets.json with owner-only permissions on that computer. Keys are never sent to the Nocturnal cloud, never included in a mirrored conversation, and are redacted out of agent logs.

A key on its own is not enough to run agents. Nocturnal drives the provider's CLI rather than calling the API directly, so the CLI still has to be installed — the key just tells it who you are. Keys are also used for smaller extras: voice transcription, and commit-message suggestions.

Installing a provider CLI

If a provider is missing, Settings → Providers gives the command. In a terminal on the computer that will run your agents:

npm install -g @anthropic-ai/claude-code   # then: claude login
npm install -g @openai/codex               # then: codex login

The scan runs when Nocturnal opens. If you install a CLI while the app is already running, open Settings → Providers and press Rescan — no restart needed. That page also shows when the last scan ran.

Choosing between them

The picker groups models by family and marks any group whose provider is not usable yet, with the reason — not installed, not signed in, or switched off. Defaults live in Settings → Models; a session remembers whatever you picked when you sent.

Codex decides which models your account may use and keeps that list on disk, so Nocturnal reads Codex's own list rather than shipping a fixed one. This matters: a ChatGPT plan and a pay-as-you-go API account are offered different models, and asking for one the account cannot use fails the run. Whatever your codex can run is what the picker offers.

Modes work on both providers. Ask is read-only, Plan produces a plan without editing, and Agent makes changes. On Codex these map onto its sandbox: Ask and Plan run read-only, and Agent writes within your workspace. A plan from either provider is saved to the project the same way, so you can plan with one and build with the other.