Core concepts
This chapter is the mental model for how Veyyon runs. Read it when you need the vocabulary behind sessions, permissions, and the BYOK model boundary. Day-to-day commands live in Using Veyyon; feature guides live under Features.
What this chapter covers
Veyyon is a terminal coding harness. The CLI is veyyon. You point it at a model endpoint with a key you
supply, and the harness drives a loop of read, edit, verify, and stop. The concepts below explain the
units of that loop and the contracts that keep it predictable across providers.
| Page | What it defines |
|---|---|
| Sessions, turns, and threads | The 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 model | How approval modes and the OS sandbox combine. The sandbox is the hard boundary (Landlock/seccomp on Linux, Seatbelt on macOS); tools.approvalMode decides when Veyyon asks first. |
| Model contract | The BYOK boundary: endpoint + model + key. What the harness owns versus what the provider owns, Freeform vs Function tools, and how system prompts and tool schemas are presented. |
Foundations that pair with these pages
Before or after this chapter, the foundations pages give the design spine without repeating the day-to-day workflow:
- Core concepts (foundations) defines session, thread, turn, rollout JSONL, and the state database in more detail.
- Architecture overview maps subsystems to responsibilities.
- Provider and model configuration: Providers and
docs/providers.md.
How the pieces fit
you ──► veyyon (TUI or a one-shot prompt)
│
├─ session / thread / turn (concepts/sessions-turns-threads)
├─ sandbox + approvals (concepts/permission-model)
└─ model call (concepts/model-contract)
│
├─ system prompt + tool schemas (harness)
├─ endpoint + key (your provider)
└─ model id (discovered or pinned)
The harness stays the same when you change providers. You change the endpoint, the key, and optionally the model id. Tool repair, edit verification, sandboxing, and context compaction remain harness behavior. See Configuring providers for copy-paste setups and Models and providers for day-to-day model selection.
Related reading
- Permission model and Sandbox for Landlock/Seatbelt details.
- Prefer
--approval-mode auto-editfor bounded automation. - Non-interactive mode for scripted
veyyonlaunch patterns.