Skip to content
SolenopsisCampo edited this page Nov 8, 2026 · 1 revision

FAQ

Starting up

It refuses to start and says the project is the harness (exit code 2)

You launched it from the harness's own folder. The directory you launch from is the project, and the harness may not be its own project. cd to the folder you want to work in and launch from there, or name it with AGENT_WORKSPACE=~/my-project. See Getting Started.

Which Python do I need?

Python 3.11 or newer, with its venv module, for every install. The npm, yarn, bun and pnpm routes also need Node.js 18 or newer for the launcher. An older Python is refused at install time.

It stops at startup naming a key in settings.json

An unknown key in settings.json stops the harness on purpose, naming the file and the key, so a typo never reads as a setting. Fix the spelling, or check the list of every key.

Five well-formed keys are refused by name, with a reason, because a project's settings.json outranks yours and a cloned repository must not be able to set them: shell_approval_mode, ensemble_models, critic_model, embedder_model and research.granted_tools. Set the first four in config.yaml (or with /critic and /embedder). Grants exist only as per-run flags.

Every model call fails

No provider key is set up yet, and both shells say so at launch. In the TUI, run /connect; otherwise add the key to providers.json. See Getting Started.

Tools

The model says it cannot read my files or run commands

read, view_image, write, edit, shell and the shell session tools are off in a fresh install, and only you can turn them on, in config.yaml or with /config in the TUI. Tool Permissions explains each one first.

I turned a tool on and nothing changed

  • Relaunch. config.yaml is read once, at startup.
  • view_image is offered only when the provider is marked accepts_images in providers.json, and never in a research pass.
  • shell refuses any command that may run code until Docker or Podman is running, unless you enable the weaker fallback. See Shell and Sandbox.
  • An active agent may leave the tool out of its allowed_tools. /agent default goes back to no agent.
  • A piped CLI run cannot ask you anything, so tools that need approval are hidden from it entirely.

The file tools ask about every file in my project

They run without asking only inside the workspace, which by default is the workspace folder in the directory you launched from. Everything else asks, including the rest of your project. To let them work across the project without a prompt per file, launch with AGENT_WORKSPACE set to the project folder, knowing that the model can then change any file there without asking. A path through a .venastine folder is always refused.

A shell command with a Windows path fails

Use forward slashes. A backslash counts as an escape character, so cat sub\dir\notes.txt is sent to the container, where that path does not exist. cat sub/dir/notes.txt works.

Why did this command ask me? It only reads

Under the shipped tiered mode, only a read-only command whose arguments all stay inside the workspace runs without asking. An argument that looks like a path outside it, a quoted or escaped argument, or a program not on the inert_commands list each makes it ask. Shell and Sandbox explains why the check is that strict.

Projects, agents and skills

My project's agents, skills or AGENTS.md are being ignored

They load only after you trust the project, and trust is tied to the files' contents, so it is asked again after they change. If you answered no, or the run had no terminal to ask in, they stay absent. In a script, --trust-project grants it and prints what it trusts.

My own agent or skill does not show up

Work through the checklist. The usual causes are an agent in a subfolder of agents/, frontmatter that does not start on the first line, a name that a built-in already uses, or no relaunch after the edit. Every file the loader skips is logged with the reason.

Updates and data

My config.yaml edits disappeared after an update

  • pnpm puts every install in a new directory, so config.yaml edits do not survive an update. Use npm, yarn or bun if you rely on them.
  • npm merges your values back after an update, except an edit made after your last session that you never launched before updating.
  • The GitHub installer carries them forward on every rerun.

settings.json and everything else in ~/.config/venastine survive every update.

Where is my data, and how do I delete it?

PRIVACY.md lists everything stored on your machine, what leaves it and when, and how to delete each part. There is no telemetry. venastine --venastine-doctor prints where this install keeps its database, log and keys.

Where is the log?

venastine --venastine-doctor prints its location. In a clone it is logs/app.log in the directory you launched from. Set AGENT_LOG_LEVEL=DEBUG for more detail. Secret-shaped strings are redacted on the way into the file.

Research runs

Can I cap what a research run costs?

There is no default spend ceiling. max_token_budget in settings.json caps the tokens billed by each chat turn, each research pass and each /init, so a ten-pass run can bill up to ten times that figure. Spending limits set at your provider are the stronger control: they see the same bill and cannot be skipped by a code path.

How do I stop a run, and is the work lost?

In the CLI, press Ctrl+C. A run is saved pass by pass, so one you stop, or one that crashes, still leaves its record up to the last pass it finished.

Why does a claim say UNVERIFIED when it looks right?

UNVERIFIED covers a claim scoring below 0.3, any factual claim the run could not ground against a source whatever its score, and a claim still flagged after two rounds of revision. It means "not checked", not "false". Open the claim with /claims (or Ctrl+L) to see its score breakdown and sources.

Copying and the TUI

How do I copy text out of the TUI?

Use /copy: the last answer by default, or report, claims, conversation or all. Some terminal multiplexers drop clipboard writes silently, so /copy --file <path> is the route that always works. Shift+drag usually lets your terminal select text directly.

Reporting a problem

  • A bug, a missing feature, or a doc that is wrong: open an issue.
  • A security vulnerability: never in a public issue. Report it privately, as SECURITY.md describes.

Checked against release 0.3.12 (commit f33ef8a). Where this page and the README disagree, the README is the reference.

Clone this wiki locally