Install

Veyyon ships as the npm package @veyyon/pi-coding-agent and installs the veyyon executable. It is a TypeScript + Bun agent loop with Rust natives (@veyyon/pi-natives) for hot paths (grep, walker, shell/PTY, hashline edits). After install, run veyyon plugin doctor.

Requirements

Bun (recommended runtime) or a recent Node.js.
Git — most workflows expect a repository.
On Linux: user-namespace support for bubblewrap-based shell isolation (WSL2 yes; WSL1 no).
On macOS: Seatbelt is used for the shell sandbox.

Install (npm / Bun)

$ bun install -g @veyyon/pi-coding-agent
$ veyyon --version

npm works too:

$ npm install -g @veyyon/pi-coding-agent
$ veyyon --version

bun install also builds @veyyon/pi-natives. Config and state default to ~/.veyyon.

After install

The first interactive veyyon opens the setup ceremony (splash → providers → glyphs → theme → outro). Force it again with veyyon setup. Re-open providers inside a session with /setup or /providers. See Getting started.

Build from source

$ git clone https://github.com/santhsecurity/veyyon.git
$ cd veyyon
$ bun setup      # installs workspace deps and builds @veyyon/pi-natives
$ bun dev --version

bun dev runs the in-repo build; use it while evaluating or contributing.

Shell completions

$ veyyon completions bash|zsh|fish

Verify the install

$ veyyon --version
$ veyyon plugin doctor
$ veyyon plugin doctor --fix

veyyon plugin doctor checks plugin health and warns when optional external binaries (sd, sg, git) or common API keys are missing. See Diagnostics.

Spec — not shipped: a top-level veyyon doctor with install-wide --summary / --json self-test. Today diagnostics are scoped to veyyon plugin doctor and the TUI /debug.

Relocate the config directory

By default Unix uses ~/.veyyon. PI_CONFIG_DIR renames the home-relative config directory, and PI_CODING_AGENT_DIR relocates the whole agent base (config.yml, agent.db, sessions, and more):

$ export PI_CODING_AGENT_DIR=/path/to/veyyon-agent
$ veyyon plugin doctor

Layout: File locations.

First credentials

On first interactive launch, the setup ceremony (or veyyon setup) walks sign-in and API keys. Inside a session, use /setup / /providers to re-open that panel, /login (or /login <provider>) for OAuth and key entry, or export the provider’s environment variable and skip the interactive step. See Authentication and Configuring providers.

Uninstall

Remove the global package:

$ bun remove -g @veyyon/pi-coding-agent
$ # or: npm uninstall -g @veyyon/pi-coding-agent

Then remove state if you want a clean machine:

$ rm -rf ~/.veyyon          # irreversible: config, secrets, sessions, plugins, skills, logs
$ # if you relocated the agent base:
$ rm -rf "$PI_CODING_AGENT_DIR"

Project-local files (AGENTS.md, .veyyon/ in a repo) are not removed by deleting the home directory — clean those per repository if desired.

To keep projects but wipe only sessions:

$ rm -rf ~/.veyyon/agent/sessions

Getting started — first interactive edit with sample terminal output.
Model contract — choose credentials with the harness boundary in mind.
Safety — approvals and fail-closed behavior.
Troubleshooting / FAQ — when the doctor is not enough.

The Veyyon Harness Handbook