Install, sign-in, models, allowance, usage, data — grouped by topic. Ctrl+F is your friend.

Installation

Q: Can I install the CLI on my computer?

The CLI supports Apple Silicon Macs, Windows x64 and Linux x64 (install via npm, Node.js 20+; Apple Silicon Macs also have a standalone binary). There is no CLI for Intel Macs, Windows ARM64 or Linux ARM64; on the first two you can use the desktop app. See Installation.

Q: `neox: command not found`

The standalone binary lives at ~/.neox/bin/neox. Add that directory to your PATH:

export PATH="$HOME/.neox/bin:$PATH"

Put that line in ~/.zshrc or ~/.bashrc and open a new terminal. For an npm install, check that npm's global bin directory is on your PATH.

Q: How do I upgrade? I upgraded but I'm still on the old version.

Run neox update. If you're still on the old version, run which neox — you may have more than one copy (say, one from npm and one standalone). Delete the one you don't want.

Q: macOS says it "cannot verify the developer"

Open System Settings → Privacy & Security, find the blocked-app notice, and click "Open Anyway".

Q: Is there a Linux desktop app or an iOS app?

Not yet. On Linux x64 you can use the CLI. On mobile there is an Android app for viewing and controlling sessions on your computer — get it from the download page.

Q: Do I have to create an account?

No. Bring your own API key (BYOK) and Neox charges nothing; you pay the model provider directly. You only need to sign in for a Neox subscription.

Use the device code flow:

neox login --device-code

It shows a URL and a code. Open the URL on any device and enter the code.

Q: How do I switch accounts?

One CLI is signed in to one account at a time. Run neox logout, then neox login with the other account.

Models and providers

Q: A model I expected is missing

neox model ls --source=cloud   # what your subscription covers
neox model ls --source=byok    # what your own keys cover

Subscription models depend on your plan — see the model catalog and pricing.

Q: How do I set up my own key (BYOK)?

CLI — run neox provider add and follow the prompts, then neox provider test to check the connection; inside the interactive UI use /provider
Desktop — Settings → Models → Providers; you can also import keys already set up in other tools on your machine

Then pick a model with /model, or pass --model on a one-shot query. Keys are stored encrypted on your machine; in BYOK mode requests go from your device straight to the provider and don't pass through Neox servers.

Q: What happens when I run out of allowance?

If extra usage is on and your platform balance covers it, usage continues on the balance at actual cost. Otherwise you get a clear error until the allowance resets or you upgrade. Neox will not fall back to your BYOK keys and start spending your money. You can turn extra usage off any time on the Subscription page of the console.

Usage

Q: Will a long-running command (like `npm install`) get killed?

No. A command still running at the default 120 seconds is moved to the background and keeps going. Environment variables adjust this:

NEOX_BASH_DEFAULT_TIMEOUT_MS=120000   # how long to wait in the foreground
NEOX_BASH_MAX_TIMEOUT_MS=600000       # hard ceiling
NEOX_DISABLE_FG_ADOPT=1               # never move to the background

Q: The agent is stuck and not producing output

Press Esc to interrupt and restate what you want, or try another model. More in Debugging.

Q: What do I do when the context fills up?

It's compressed automatically by default. You can also do it by hand:

> /context      # see how much is used
> /compact      # compress the conversation, keep the essentials
> /clear        # clear the conversation; memory is kept

No. Each stores its sessions locally; on the same account they share your subscription and allowance.

Q: How do I see exactly what the agent sends to the model?

NEOX_DUMP_LLM_PAYLOAD=1 neox

The full request for each turn is written to ~/.neox/logs/llm-requests/. It contains the whole conversation, so delete it when you're done.

Anything else

Q: Where do I report a bug or suggest something?

Use the feedback page or email support@neox-dev.com with reproduction steps and the log from ~/.neox/logs/ covering that time.

Q: Is my data used for training?

Neox does not train models on your code or conversations. Request logs are deleted after 30 days, and prompt content is stripped before they're written. With a subscription, requests are forwarded to the relevant model provider, which handles them under its own terms; providers of some free models may use requests to improve their services. See the Privacy Policy and Security.

Frequently asked questions