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

agen --version

2. Get a free NVIDIA NIM key

NVIDIA NIM is the easiest starting point: the free tier needs no billing setup, and it hosts gpt-oss-120b — an open-weight model large enough for reliable tool calling, which is what an agent actually depends on.

1. Open build.nvidia.com/explore/discover
2. Sign up (email or an existing Google / GitHub / NVIDIA account)
3. Open any model card and press Get API Key
4. Copy the key — it starts with nvapi-

Keep the key on your clipboard for the next step.

3. Add the model

Start the TUI:

agen

Then, inside it:

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

Prefer something smaller? openai/gpt-oss-20b is on the same list, but open-weight models under 100B call tools unreliably — worth knowing before you blame the agent.

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 five keys

With the input box empty:

Enter sends. Alt+Enter inserts a newline. Enter during a run queues a steer message rather than interrupting.

Advanced: the two subscription providers

When the free tier stops being enough, the next step is not another pay-per-token key — it is a subscription you may already be paying for. These two are the first choice for a second, fall-back model: the cost is already fixed monthly, so an agent that takes a few extra turns doesn't move the bill.

Neither takes an API key. Both authenticate through a device-code OAuth flow, and the token lands in the OS keychain like any other credential.

Add Codex

Add Grok (xAI)

Already authenticated once? The flow asks <Provider> token exists · re-login? first. No keep existing reuses the stored token and jumps straight to the model list — pick Yes re-authenticate only when switching accounts.

With more than one model registered, Shift+W / Shift+S cycles the dispatcher model from the TUI, and /model dispatch / /model summary set the dispatcher and summary models explicitly.

Where to go next

If something goes wrong