> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Connect a model and finish your first task with o4.

This page takes you from a fresh install to a finished task: connect a model,
send a prompt, and approve the model's first action. You need o4 installed
(see [Install o4](/installation)) and an API key from a model provider, or
[Ollama](https://ollama.com) running locally.

<Steps>
  <Step title="Set your API key">
    The simplest way to give o4 a key is an environment variable. Set it in
    your terminal. For Anthropic:

    ```bash theme={null}
    export ANTHROPIC_API_KEY="your-key"
    ```

    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](/models/providers) lists every
    provider and its variable. To use a Claude or ChatGPT subscription
    instead of an API key, see
    [Claude and ChatGPT subscriptions](/models/subscriptions).

    If you plan to use [Ollama](/models/local-models), skip this step; it
    needs no key.
  </Step>

  <Step title="Start o4 in a project">
    In the same terminal, go to the folder you want to work in and start o4:

    ```bash theme={null}
    cd ~/code/my-project
    o4
    ```

    o4 treats the folder you start it in as the workspace. The model reads
    and edits files there.
  </Step>

  <Step title="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:

    1. **Choose Provider.** Pick your provider with `Up` and `Down`, then
       press `Enter`. A provider whose key is set in your environment shows
       **env set**, and Ollama shows **local**.
    2. **Enter API Key.** o4 skips this screen for providers marked **env
       set** or **local**. See the note below if you see it.
    3. **Choose Model.** Pick the model to use by default.
    4. **Choose Theme.** Moving through the list previews each theme. Press
       `Tab` to keep the current one.
    5. **Quick Settings.** Press `Enter` on a row to change it. The rows are
       **Reasoning**, **Tool permissions**, **Nerd Font icons**, **Vim mode**,
       and **Auto-compact**. Leave **Tool permissions** at `ask` so o4 asks
       before it edits files or runs commands; `allow` runs them without
       asking. Press `Tab` to continue.
    6. **Review Setup.** Check the summary and press `Enter` to save.

    Press `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`.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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 `Enter`:

    ```text theme={null}
    Find where this project reads its configuration, and add a comment that explains the lookup order.
    ```

    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 `Shift+Enter`. To stop the
    model mid-turn, press `Esc`.
  </Step>

  <Step title="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:

    | Key | Answer |
    | - | - |
    | `y` | **Yes, proceed.** Run this call. |
    | `t` | **No, and tell o4 what to do instead.** Refuse and type a note for the model. Press `Enter` to send it. |
    | `Esc` | Refuse this call. |

    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](/safety/permissions) for approval modes and rules.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

```text theme={null}
o4 session ended
Session: 6560acfd-b36d-4bf2-ab80-b58ba8970f54
Model: anthropic:claude-sonnet-4-6
Runtime: 12m 4s
Usage: 48210 input / 3120 output tokens, cache 0 read / 0 write, $0.1914
Resume: o4 resume 6560acfd-b36d-4bf2-ab80-b58ba8970f54
```

To choose from your saved sessions instead, run `o4 resume` with no ID. See
[Sessions](/guides/sessions).

To run a single prompt without the interface, for example in a script, use
print mode:

```bash theme={null}
o4 --print -p "Summarize what this repository does"
```

See [Print mode and scripting](/guides/print-mode).

## Next steps

<CardGroup cols={2}>
  <Card title="The interface" icon="window-maximize" href="/guides/interface">
    Learn the screen layout, input modes, and panes.
  </Card>

  <Card title="Writing prompts" icon="pen" href="/guides/prompting">
    Mention files, attach images, and steer the model.
  </Card>

  <Card title="Choosing a model" icon="microchip" href="/models/overview">
    Compare providers and switch models.
  </Card>

  <Card title="Project instructions" icon="file-lines" href="/configuration/project-instructions">
    Tell o4 about your project's conventions.
  </Card>
</CardGroup>