1
Set your API key
The simplest way to give o4 a key is an environment variable. Set it in
your terminal. For Anthropic:Other providers use their own variable, such as
OPENAI_API_KEY or
GOOGLE_API_KEY. Add the line to your shell profile to keep it for new
terminals. Providers and API keys lists every
provider and its variable. To use a Claude or ChatGPT subscription
instead of an API key, see
Claude and ChatGPT subscriptions.If you plan to use Ollama, skip this step; it
needs no key.2
Start o4 in a project
In the same terminal, go to the folder you want to work in and start o4:o4 treats the folder you start it in as the workspace. The model reads
and edits files there.
3
Choose a model in the setup wizard
On the first run, o4 opens the setup wizard, Welcome to o4. It opens
when o4 finds no API key, or when no default model is set.Choose Quick setup or Custom setup and press
Enter. The wizard
then walks through these screens:- Choose Provider. Pick your provider with
UpandDown, then pressEnter. A provider whose key is set in your environment shows env set, and Ollama shows local. - Enter API Key. o4 skips this screen for providers marked env set or local. See the note below if you see it.
- Choose Model. Pick the model to use by default.
- Choose Theme. Moving through the list previews each theme. Press
Tabto keep the current one. - Quick Settings. Press
Enteron a row to change it. The rows are Reasoning, Tool permissions, Nerd Font icons, Vim mode, and Auto-compact. Leave Tool permissions ataskso o4 asks before it edits files or runs commands;allowruns them without asking. PressTabto continue. - Review Setup. Check the summary and press
Enterto save.
Esc on any screen to go back one step. Press Esc on the first
screen, or choose I have a config file (skip setup), to close the
wizard without saving anything.The wizard saves your choices to ~/.o4/settings.json. To run it again
later, type /onboard.If you type a key on the Enter API Key screen instead, the Choose
Model screen may show No models are available for this provider.
This happens with some providers, such as Anthropic and OpenAI. Press
Esc twice to go back to the provider list, then Esc twice more to
close the wizard. Quit o4 with Ctrl+C, set the environment variable,
and start o4 again.4
Send your first prompt
After setup, you’re at the prompt at the bottom of the screen. The model
you chose is shown just below it. Type a task and press The model starts working. A status row above the prompt shows what it’s
doing and how long the turn has run. Tool calls appear in the transcript
as the model makes them. Reading and searching files happen without a
prompt.To add a line break without sending, press
Enter:Shift+Enter. To stop the
model mid-turn, press Esc.5
Approve a tool call
When the model wants to change a file or run a command, o4 stops and
shows an approval panel in place of the prompt. The panel shows what the
model wants to do, the reason it gave, and the current security state,
for example
Security: sandbox guarded · approval Ask. For a shell
command you see the exact command, and for a file change you see the
lines it adds and removes.Choose an answer with the arrow keys and Enter, or press its key:For file edits and other calls that o4 can describe with a pattern, the
panel also offers Always allow pattern (
p) and Always deny
pattern (d), for example
Always allow pattern: Edit(/Users/you/code/my-project/src/**). Either
one answers this call and saves a rule to the project’s
.o4/config.toml, so calls that match the pattern stop asking.After you approve a change to a file, o4 doesn’t ask again for the same
kind of change (such as another edit) to that file for the rest of the
session. Shell commands ask every time unless a permission rule allows
them. See Permissions for approval modes and rules.6
Review the result
When the model finishes, the prompt is ready for your next message. To
review what changed, press
Ctrl+D to open Session Diff, which lists
every file changed in the session. Press Esc to close it.To keep going, send a follow-up in the same session. The model keeps the
whole conversation. To quit o4, press Ctrl+C while the prompt is empty
and nothing is running.Start again later
o4 saves every session. When you quit, it prints a summary with the session ID, the model, the token use and cost, and the command to come back:o4 resume with no ID. See
Sessions.
To run a single prompt without the interface, for example in a script, use
print mode:
Next steps
The interface
Learn the screen layout, input modes, and panes.
Writing prompts
Mention files, attach images, and steer the model.
Choosing a model
Compare providers and switch models.
Project instructions
Tell o4 about your project’s conventions.