Models and keys

Vortex provides the agent loop and the workspace control around it. You provide the model. There is no model bundled with the app and no inference server in the middle: you add a key or a local model, and the agent uses it.

Where keys come from

Add a key in Settings → Models, or set it in the environment before launching the app:

• OPENROUTER_API_KEY
• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• VORTEX_RUN_API_KEY and VORTEX_REVIEW_API_KEY for the headless Headless CLI, which also accept --api-key

Keys are never written to the repo and never written to logs. The model picker only shows providers you have a key for, so you cannot select something that will fail on the first request.

Providers you can add

Anything that speaks the OpenAI chat API works through the compatible path. That is the escape hatch when your team runs its own gateway.

Requests go straight to your provider

Requests go directly from your Mac to the provider whose key you supplied. Provider costs stay yours, and Vortex does not route workspace code through its own servers. Workspaces, code, prompts, and chats are never transmitted to us.

Local models

Vortex can run an optional local GGUF model on your Mac through the local model path, using llama.cpp with Metal on macOS. This is a model you point at, not one bundled with the app: download the GGUF, add it in Settings, and select it like any other model.

Local models fit small jobs, code that must not leave the machine, and fast first passes before escalating.

Helper-model pools

A helper-model pool lets cheap models handle routine steps while a stronger model handles planning. A typical split:

• Planning and hard reasoning: your strongest model.
• Retrieval summarisation, file triage, commit messages, and small mechanical edits: a cheap or local model.
• Escalation: when a helper model is out of its depth, the step is retried on the stronger model.

Pools are useful with a metered provider, because the expensive model only sees the steps that need it.

Choosing between cloud and local

If a repo must not leave the machine, use a local model or a self-hosted OpenAI-compatible endpoint inside your network.

Caps and limits

Agent caps live in ~/.vortex/config.toml and can be overridden with VORTEX_* environment variables. Use them to bound how long a run may take or how much context a step may pull in, rather than relying on a prompt to behave.

Caps are per run, not per model, so the same limit applies whether a step lands on a cloud provider or a local GGUF model.

Troubleshooting

401 unauthorized

The key is wrong, or it belongs to a different provider than the model you picked. Check which provider the selected model comes from in the model picker, then confirm the matching key is set. A key set in the environment wins at launch, so an old shell export can override a key you just typed into Settings.

A model is not listed

The picker hides providers you have no key for, so an empty list usually means no key. Add the key in Settings → Models, or set the environment variable and relaunch. For a self-hosted server, check the base URL on the OpenAI-compatible entry.

Rate limits

Rate limits come from your provider, not from Vortex. Options: wait and retry, move routine steps onto a helper model or a local model, or point the provider entry at an endpoint with a higher quota. A run that fails partway keeps its plan file and pending patches, so you can resume instead of starting over.

Next steps

• Quickstart — connect a model and run a first job.
• Plan files — decide which model plans and which implements.
• Headless CLI — vortex run and vortex review with the same keys.

Get an invite

Vortex is in a closed beta on macOS. Add your email to the waitlist to get an invite and a download link.