# Quickstart

The shortest path from nothing to a working agent: one install command, one free API key, one model. No credit card, no config file editing.

If you already have a provider account, [Getting Started](/docs/getting-started) covers the same ground with more detail and more options.

## 1. Install

```bash
curl -fsSL https://agenvoy.com/scripts/install.sh | bash
```

The script detects macOS or Linux, installs the `agen` binary to `/usr/local/bin`, and pulls in what it needs (`git`, `make`, a C compiler, `python3`, `node`, `pdftotext`, and `bwrap` on Linux). It asks for `sudo` once, to write into `/usr/local/bin`.

Check it landed:

```bash
command -v agen
```

## 2. Get a free Ollama Cloud key

Ollama Cloud is the easiest starting point: the free plan needs no billing setup, and `gemma4:31b` runs on it — enough to get a working agent without a card on file.

1. Open **[ollama.com/settings/keys](https://ollama.com/settings/keys)**
2. Sign up or sign in
3. Create a new API key
4. Copy the key

Keep the key on your clipboard for the next step.

## 3. Add the model

Start the TUI:

```bash
agen
```

Then, inside it:

| Step | What you do |
|---|---|
| 1 | Type `/model` and press **Enter** |
| 2 | Choose **add** — "add model from provider" |
| 3 | Press → to the **API Key** tab and choose **Ollama Cloud** (the picker opens on **OAuth**; `o` on a row opens that provider's key page) |
| 4 | Paste the key. Input is masked, and the key goes straight to the OS keychain — never into a config file, never into the conversation |
| 5 | Agenvoy fetches Ollama Cloud's live model list. Pick **`gemma4:31b`** |

That is the whole setup. The model is registered in `~/.config/agenvoy/config.json`; the credential is not.

> Pick it because it runs on the free plan, so the agent works with no card on file. The free plan has a usage cap; check it on your Ollama account, since **Shift+U** no longer reports Ollama Cloud (Removed in v1.2.0). Open-weight models call tools less reliably than frontier models — worth knowing before you blame the agent. Treat it as the dispatcher, and point the session model at a subscription plan (ChatGPT Plus, SuperGrok) once you have one.

## 4. Ask it something

Type a question into the input box and press **Enter**:

```
What's the weather in Taipei right now?
```

No weather tool ships with Agenvoy. Watch what happens instead: the agent searches its own registry, finds nothing, fetches the tool-building contract, picks a public API, writes a Python tool, sandbox-tests it, then calls it and answers. The tool is saved — the second time you ask, it just runs.

Try a few more:

```
Summarize the README in this folder
Report the TSMC stock price every morning at 8am
Which of my documents mentions the prompt guide?
```

## 5. Know these six keys

With the input box empty:

| Key | Effect |
|---|---|
| `/` | Command palette — matches on command name or description |
| **Shift+Tab** | Toggle auto-approve (otherwise each non-read-only tool call asks first) |
| **Shift+F** | Toggle fast mode |
| **Shift+G** | Toggle `CLAUDE.md` / `AGENTS.md` injection (off at start). When on and the work directory has one of them, `[CLAUDE.md]` or `[AGENTS.md]` shows on the mode line and the file is added to every turn's context; `CLAUDE.md` wins when both exist |
| **Shift+W** / **Shift+S** | Cycle the session model (`auto` or a registered model) |
| **Esc** | Dismiss a popup or the notice box; during a run it asks whether to cancel or pause |

**Enter** sends. **Alt+Enter** inserts a newline. **Enter** during a run sends plain text as a steer message rather than interrupting; `/` commands wait until the run ends.

## Where to go next

| You want to | Read |
|---|---|
| Add a second provider, or switch models per session | [Managing Models](/docs/providers-config) |
| Understand what the agent can already do | [Built-in Tools](/docs/built-in-tools) |
| Make the agent build and keep its own tools | [Tool Extension](/docs/tool-extension) |
| Share your tools with Claude Code or Codex | [MCP Server](/docs/mcp-server) |
| Schedule something to run every morning | [Scheduler](/docs/scheduler-skills) |
| Drive it from a browser instead | Start `agen`, then open `http://127.0.0.1:17989` |