Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Core concepts

The vocabulary for how Veyyon runs: sessions, permissions, and the boundary between the harness and the model provider. For operator commands see Using Veyyon; for feature guides see Features.

Pages

The CLI is veyyon. It calls a configured model endpoint with your credentials and runs a tool loop: read, edit, verify, stop. The pages below define the units and contracts of that loop, so that later chapters can assume you know them.

PageWhat it defines
Sessions, turns, and threadsThe runtime units. A session is the persisted run, a turn is one request plus the agent loop, and a thread is the active path through the session tree.
Permission modelThe approval-mode boundary. tools.approvalMode (plan, ask, ask-command, auto, yolo) sets which tool tiers run automatically and when Veyyon prompts you first. There is no operating-system command sandbox.
Model contractThe bring-your-own-key boundary: endpoint, model, and key. It covers what the harness owns versus what the provider owns, Freeform versus Function tools, and how system prompts and tool schemas are presented.

Foundations that pair with these pages

The foundations pages give the design spine without repeating the operator workflow.

How the pieces fit

  you ──► veyyon (TUI or a one-shot prompt)
            │
            ├─ session / thread / turn   (concepts/sessions-turns-threads)
            ├─ approval mode             (concepts/permission-model)
            └─ model call                (concepts/model-contract)
                  │
                  ├─ system prompt + tool schemas (harness)
                  ├─ endpoint + key               (your provider)
                  └─ model id                     (discovered or pinned)

Changing providers changes the endpoint, the credentials, and the model id. Tool repair, edit verification, approvals, and context compaction stay the same, because they are harness behavior. See Configuring providers and Models and providers.

  • Permission model and Approvals cover the approval modes.
  • Approvals usually need no tuning: the default auto runs every tier while the per-tool policies, the working-directory boundary, credential use, and a tool’s own critical commands all still prompt. Pick a rung explicitly only when you want a different trade-off, and note that a headless run has nobody to answer a prompt, so a rung that prompts turns a tool call into a failure rather than a pause.
  • Non-interactive mode covers scripted veyyon launch patterns.