# 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; Claude Code through the local `claude` CLI once it is on `PATH`) 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, Gemini or OpenRouter 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

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

Or build from source:

```bash
git clone https://github.com/pardnchiu/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) under the fixed service name `agenvoy`; when `secret-tool` is unavailable they go to `~/.config/agenvoy/.secrets` (mode 0600). Reads try the keychain, then that file, then an environment variable of the same name.

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

## First run

```bash
agen
```

The daemon starts automatically if it isn't already running. Since v1.2.0 the daemon runs every request and the TUI talks to it over a Unix socket; while it is unreachable the status line shows `Connecting`. Inside the TUI, `/new` creates a session (optionally `/new <name>`, then pick a role as its description) and `/session` 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 sends plain text as a steer message; `/` commands wait until the run ends). 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 (`⏸ safe` ↔ `⏵⏵ auto`; the TUI starts in `auto` inside a subdirectory of `$HOME`), **Shift+F** toggles fast mode, **Shift+W**/**Shift+S** cycles the session model, **Shift+A**/**Shift+D** cycles the session reasoning level (`auto` included), and **Shift+G** toggles `CLAUDE.md` / `AGENTS.md` injection.