Frequently asked questions

This page covers snowpea basics, permission modes, CI use, updates, and extensions.

On this page:

• Learn the basics
• Modes and permissions
• Headless and CI
• Updates
• Protocol and extensions
• Choose your next guide

Learn the basics

What is snowpea, exactly?

An open-source multi-vendor coding agent that runs on your own machine. A Python core sits as a local daemon and owns everything that has state — sessions, tools, permissions, memory, schedules, messenger bindings. Clients attach to it over a documented WebSocket JSON-RPC protocol. There are three today: the terminal UI, the desktop app (snowpea desktop), and the headless CLI.

Where does my data go?

It stays on the machine running the daemon. $SNOWPEA_HOME (default ~/.snowpea, %LOCALAPPDATA%\snowpea on Windows) holds the session database (state.db), settings (settings.json), credentials (credentials.json, mode 0600), logs, attachments and speech files. Per-project settings live in <project>/.snowpea/settings.json. What leaves the machine is the prompts you send to the LLM vendor you chose, and requests to whichever search and browser providers you turned on.

Secrets are never written into settings.json and never logged.

Which vendor should I use?

The one you already have an account with. Whether the adapter is native or OpenAI-compatible makes no difference to how snowpea feels. If you have no account anywhere, local will talk to vLLM, Ollama, LM Studio or llama.cpp's server — but the model you load has to support tool calling, or the agent can talk and not act. The full list is in Setup.

Do I need a paid account?

Only for the LLM vendor. The default search provider ddgs needs no key and no account, and the default browser provider local_chromium runs a headless Chromium on your own machine.

The *_free ids in the provider list are easy to misread: they are free tiers of keyed products, not keyless endpoints. Exa answers 402 without a key; Parallel, Keenable and Tavily answer 401. The exception is exa_free, which uses Exa's official hosted MCP anonymously and never prompts for a key (rate limits apply).

Can several clients run at once?

Yes. Clients that share a SNOWPEA_HOME share one daemon and therefore one set of sessions. A session started in the terminal is in the desktop app's sidebar; a thread created in the app is visible in the TUI.

To deliberately isolate sessions, give them different homes. A different SNOWPEA_HOME means a different daemon, different settings, different sessions. This is also how you isolate CI jobs from each other:

SNOWPEA_HOME=/tmp/snowpea-ci snowpea -c "run the linter" --mode plan

Modes and permissions

What is the default mode?

accept. File reads and edits happen without a prompt; shell commands, network calls and anything that sends a message ask first. It is the same position as Claude Code's acceptEdits.

Why does it keep asking about the same command?

Because it wants to be allowlisted. An allowlist entry promotes ask to allow, and can never promote deny — so nothing you put here weakens plan mode.

/allow ^git (status|diff|log)\b
/allow ^npm (run )?test$ --global
/allow tool:web_search
/allowlist

The pattern is a regular expression matched against the shell command. Write it anchored and narrow: ^git also allows git push --force.

Is auto mode dangerous?

Yes. It asks nothing. Use it when you are watching, inside a container you are willing to lose, or for a scheduled job whose blast radius you have thought about. Reaching for auto on a developer machine to silence prompts is the wrong fix — that is what the allowlist is for.

What if nobody answers an approval?

The request is denied after 300 seconds by default. After approvals.timeoutSec the request is denied and the turn ends. Every decision, timeouts included, is appended to $SNOWPEA_HOME/logs/approvals.jsonl.

Headless and CI

How do I use it from a script?

snowpea -c "..." runs one turn with no UI and a deterministic exit code. Without a TTY there is nobody to ask, so an approval request is an immediate denial and the process exits 4. Say so explicitly when that is what you mean:

snowpea -c "run the linter" --approve-none

Code	Meaning
0	the turn completed
1	the agent ended in failure
2	usage or configuration error
3	could not connect to the daemon
4	an approval was denied, or the mode blocked the action
5	--timeout elapsed; the session was interrupted and closed

Code 4 is the interesting one. In plan mode a write attempt produces mode_denied and exit 4, which makes plan mode a usable read-only gate in CI.

What are the safe combinations for CI?

Plan mode for anything that only reads; auto mode inside a container you are willing to lose. Give each job its own SNOWPEA_HOME. And remember the daemon keeps running after your step ends — snowpea daemon stop at the end of the job if the runner is long-lived.

Updates

Does it update itself?

No. It checks once a day in the background and caches the answer in $SNOWPEA_HOME/update-check.json. Nothing is installed without you saying so. When a banner appears in the terminal UI, press U on an empty input or type /update. From the command line, snowpea update --check reports and installs nothing; snowpea update does it.

{ "updates": { "check": true, "channel": "auto" } }

check: false turns the daily check off and leaves /update working on demand. channel is auto, pypi or git.

I upgraded by hand — anything else?

Stop the daemon.

uv tool upgrade snowpea-agent
snowpea daemon stop

A running daemon keeps the old code in memory, and the next client to attach would negotiate a protocol version that no longer matches what is installed.

Protocol and extensions

Can I write my own client?

Yes. The protocol is documented and generated: core/snowpea_core/server/protocol.py is the source of truth, and both the protocol reference and sdk/src/protocol.ts are generated from it. The current version is 1.5.0. A client calls system.hello with the token from $SNOWPEA_HOME/token immediately after connecting; any other method before that fails with unauthorized. The orientation is in Protocol.

How do I write a plugin or a skill?

snowpea uses the Claude Code plugin format directly — SKILL.md, hooks, MCP servers, marketplaces. See Plugins. The desktop app's skills screen also searches marketplaces and installs from them.

My code is in a container or on another host

Change the backend. There are three — local, docker and ssh — chosen with /backend or snowpea setup. See Backends.

Choose your next guide

• Troubleshooting — symptom by symptom.
• Install · Setup · Modes.
• Changelog — what changed in each release.

Next steps

Troubleshoot a problemFind a fix by symptom.→Review setupConnect models and tools.→