Getting Started

Prerequisites

• Linux (sandbox via bubblewrap; bwrap auto-installs through apt/dnf/yum/pacman/apk if missing) or macOS (sandbox-exec)
• At least one LLM provider account — an OAuth subscription (Codex, Copilot, Grok) or an API key (OpenAI, Claude, Gemini, Grok, DeepSeek, Mistral, NVIDIA, Ollama Cloud, OpenRouter, Cloudflare), or a local OpenAI-compatible server (Ollama, LM Studio, custom URL)
• Go 1.25.1 or higher, only if building from source
• Optional: pdftotext (poppler-utils) so read_files can parse PDFs
• Optional: OPENAI_API_KEY to enable semantic search (text-embedding-3-small)
• Optional: an OpenAI or Gemini credential to enable audio — /model stt lets read_files transcribe audio and video, /model tts registers generate_audio. Both are off until a model is picked

Install

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

Or build from source:

git clone https://github.com/agenvoy/Agenvoy.git
cd agenvoy
make build

make build compiles, stamps the current exact-match git tag into internal/runtime.CurrentVersion, installs the binary to /usr/local/bin/agen, and refreshes the bundled skills and tools.

Configure at least one provider

Launch the TUI and run /model — it walks through provider selection, live model discovery from that provider's API, and credential storage. Tokens land in the OS keychain (security on macOS, secret-tool on Linux, encrypted file fallback otherwise) under the fixed service name agenvoy.

The main config lives at ~/.config/agenvoy/config.json; it holds registered models and runtime limits, never credentials.

First run

agen

The daemon starts automatically if it isn't already running. Inside the TUI, /new creates a named session and /sessions moves between sessions.

The input box is always focused — type your message and press Enter to send (Alt+Enter inserts a newline; Enter during a run queues a steer message instead). Type / to open the command palette (matches command name or description); Tab/Enter confirms the highlighted entry, Esc dismisses it. With the input empty: Shift+Tab toggles auto-approve, Shift+F toggles fast mode, Shift+W/Shift+S cycles the dispatcher model, and Shift+A/Shift+D cycles the reasoning level.

Or drive it from the browser

The daemon serves a dashboard from the same port the API runs on. With agen running, open:

http://127.0.0.1:17989

The page is embedded in the binary, so nothing is fetched from a remote host and nothing leaves your machine. Since v1.0.1 the third-party libraries it uses are downloaded once at daemon startup into ~/.config/agenvoy/vendor/ and served locally, and a service worker precaches the rest — so the dashboard keeps working with no network at all. Sessions, chat, schedules, models, MCP servers, rules and operator notes are all editable there.

To run one request without the TUI, post it:

curl -sS -H 'Content-Type: application/json' \
  -d '{"content":"summarize the latest changes in main.go"}' \
  http://127.0.0.1:17989/v1/send

Without session_id the request runs in a new temporary session; model and skill are optional. There is no allow_all field.

Next steps

• Sessions & Agents — sessions, agent routing, and subagents
• Execution Engine — the iteration loop and three-pass tool dispatch
• Providers — supported LLM backends and the dispatcher model
• MCP Client — plug in external tool servers
• CLI Commands — full command list

[!NOTE] This document was auto-generated by Claude after reading the full source code.