Getting started

Four steps take a fresh machine to a first change in a project: install, run the first-time setup, sign in to a provider, hand Veyyon a task.

1. Install

The quickest path is the one-line installer, which downloads a self-contained binary and links a short vey command.

$ curl -fsSL https://get.veyyon.dev | sh    # Linux or macOS
$ vey --version

On Windows, run irm https://veyyon.dev/install.ps1 | iex instead.

The installer only downloads a published release binary. If you would rather build from a checkout, clone the repository yourself, into any directory you like, and run the setup script there.

$ git clone https://github.com/santhreal/veyyon.git
$ cd veyyon
$ bun run setup
$ bun dev --version

bun run setup installs the workspace dependencies and builds @veyyon/natives, the Rust addon. That checkout is yours: you chose where it lives, and the installer neither creates it nor writes into it. Your configuration lives under ~/.veyyon, and the default profile keeps its agent state in ~/.veyyon/profiles/default/agent/.

The installer sets up shell completions for you when your shell supports them. The Install chapter has the full details.

2. First launch

The first time you run veyyon (or any time you run veyyon setup), the setup UI walks you through five steps:

The splash screen.
Providers, where you sign in or paste an API key, and optionally enable web search.
Glyphs, where you choose a Nerd Font, plain Unicode, or ASCII.
Theme.
The session welcome.

You can return to provider setup later with /setup inside the TUI, and manage the accounts you already have with /providers. To skip setup entirely, set VEYYON_SKIP_SETUP=1, or resume an existing session.

Veyyon needs at least one model provider. You have three common options.

Use an API key. Set the provider’s key in your environment, then pick one of its models in /model. For example, export DEEPSEEK_API_KEY and choose a DeepSeek model.

Sign in with OAuth. Run /login, or name a provider directly with /login anthropic. These are the same flows the Providers setup scene uses.

Add a custom gateway. Declare a provider in ~/.veyyon/profiles/default/agent/models.yml:

providers:
  my-gateway:
    baseUrl: https://gateway.example.com/v1
    api: openai-completions
    apiKey: MY_GATEWAY_API_KEY
    models:
      - id: claude-sonnet
        name: Claude Sonnet via Gateway
        contextWindow: 200000
        maxTokens: 8192

Run a local model. With the Ollama daemon running, Veyyon discovers local models and needs no key:

$ ollama serve
$ veyyon

Open /model and choose an ollama/... entry from the discovered list.

For the full picture, see Models and providers and Configuring providers.

4. Run your first task

Change into a project you know, and start Veyyon.

$ cd ~/code/my-project
$ veyyon

Describe a small, checkable task:

Add a function add(a, b) in src/lib.rs and a unit test. Run the test.

A typical run looks like this:

Veyyon reads the files it needs with read and search.
It proposes an edit through the hashline edit and write tools.
When your policy requires it, you approve the tool call. The tools.approvalMode setting sets when this happens; see Safety.
The change lands, and the diff appears in the TUI.
If you asked for tests, Veyyon runs them with bash; under the default auto mode that call runs without a prompt, and a stricter mode prompts you first.

Approval mode

Every tool call falls into one of three tiers: read, write, or exec. The tools.approvalMode setting sets which tiers run without asking and which ones prompt you first.

Mode	Runs without asking	Prompts you for
`plan`	`read` (it proposes, but does not write)	`write` only inside an active plan-mode session; `write` and `exec` are otherwise denied
`ask`	nothing	every call, `read` included
`ask-command`	`read` and `write`	anything that executes: `bash`, `eval`, `browser`, `task`, `ssh`
`auto` (default)	all tiers	a per-tool policy, a path outside the working directory, credential use, and a tool’s own flagged calls
`yolo`	all tiers	a blatantly destructive command, and a per-tool `deny` or `prompt`

The older names still work: always-ask maps to ask, and write and auto-edit both map to ask-command. The schema default is auto. You can change it in /settings or in your config. See Approvals and Safety.

Where to go next

A few surfaces are worth trying early:

A multi-file change. Ask for a refactor across modules. Hashline edits batch the paths together.
The session tree. /tree jumps back to an earlier message and branches from it inside the same session file.
Model slots. /model sets the interactive model. You set the subagent and compaction models in settings; see Models, roles, and profiles.

From here, the Quickstart is a shorter walkthrough, Configuration covers settings, Sessions explains resuming and branching, Memory covers the mnemopi backend, and Diagnostics covers the doctor and debug tools.

Keyboard shortcuts