Quickstart
Last updated
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 covers the same ground with more detail and more options.
1. Install
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:
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.
- Open ollama.com/settings/keys
- Sign up or sign in
- Create a new API key
- Copy the key
Keep the key on your clipboard for the next step.
3. Add the model
Start the TUI:
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 |
| Understand what the agent can already do | Built-in Tools |
| Make the agent build and keep its own tools | Tool Extension |
| Share your tools with Claude Code or Codex | MCP Server |
| Schedule something to run every morning | Scheduler |
| Drive it from a browser instead | Start agen, then open http://127.0.0.1:17989 |