shelley

Reference

shelley.json

The optional config file, its two fields, and the environment variables Shelley reads.

.md

Shelley mostly configures itself from flags, API keys in the environment, and settings you change in the UI (which live in the database). The config file is optional and small.

Using it

Shelley reads a config file only when you pass one:

shelley -config ~/.shelley/shelley.json --db ~/.shelley/shelley.db serve

There’s no default location. If the path doesn’t exist, Shelley carries on without it; if the file isn’t valid JSON, Shelley refuses to start. Unknown keys are ignored.

Fields

{
  "default_model": "claude-sonnet-4.6"
}
Field Type Does
default_model string Model selected by default for new conversations. The -default-model flag overrides it. If the model isn’t available, the first ready model is used instead. shelley models lists the IDs and marks the default with *.
llm_gateway string Base URL of an exe.dev-style LLM gateway. Details below; you probably don’t need it.

That’s all of them. The struct that parses the file is shelleyConfig in cmd/shelley/main.go.

On an exe.dev VM, Shelley runs with -config /exe.dev/shelley.json, and that file has other keys too (links, terminal_url, and so on). Current Shelley ignores them.

llm_gateway

With a gateway set, Shelley sends model requests through it instead of directly to the providers:

Provider Requests go to
Anthropic <llm_gateway>/anthropic
OpenAI <llm_gateway>/openai
Fireworks <llm_gateway>/fireworks/inference
xAI <llm_gateway>/xai

The gateway is expected to add credentials itself. If ANTHROPIC_API_KEY, OPENAI_API_KEY, or FIREWORKS_API_KEY is set, Shelley sends that key to the gateway for that provider. Gemini doesn’t go through the gateway; GEMINI_API_KEY still talks to Google directly.

The gateway is skipped when you pass -disable-gateway, and when Shelley finds an exe.dev LLM integration (which -disable-llm-integration turns off). Put together:

  • Without a gateway, models come from any exe.dev LLM integration plus your provider API keys.
  • With a gateway, Anthropic, OpenAI, Fireworks, and xAI models go through it, and Gemini through GEMINI_API_KEY if set.
  • With a gateway and an LLM integration, the integration wins. The gateway is skipped, and so are ANTHROPIC_API_KEY, OPENAI_API_KEY, and FIREWORKS_API_KEY; only GEMINI_API_KEY still adds models.
  • Custom models added in the UI come on top. predictable is always built in, but the UI only offers it under -predictable-only, which hides everything else.

See Models and API keys.

Environment variables

Besides the API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, FIREWORKS_API_KEY; see Models and API keys), Shelley reads:

Variable Effect
SHELLEY_SKIP_VERSION_CHECK=true Don’t check GitHub for new releases. In-app upgrades are disabled too.
SHELLEY_SOCKET The server shelley client and shelley mcp talk to when there’s no -url. Shelley sets it for the commands it runs.
XDG_CONFIG_HOME Moves the default Unix socket to $XDG_CONFIG_HOME/shelley/shelley.sock. Nothing else: hooks, skills, and AGENTS.md stay under $HOME/.config.
LISTEN_FDS, LISTEN_PID Set by systemd; read with serve -systemd-activation.

Shelley sets these for the agent’s bash commands and the UI’s terminals, so your scripts can use them:

Variable Value
SHELLEY_CONVERSATION_ID The conversation’s ID.
SHELLEY_CONVERSATION_SLUG Its slug, once it has one.
SHELLEY_MODEL The model in use.
SHELLEY_CWD The working directory.
SHELLEY_GIT_ROOT The git root, inside a repository.
SHELLEY_PORT, SHELLEY_URL The server’s port, and http://localhost:<port>.
SHELLEY_SOCKET The server’s Unix socket, unless disabled.
SHELLEY_USER_EMAIL The exe.dev user’s email, when known.

Empty values are left unset.

Other files Shelley reads

These aren’t configured in shelley.json; Shelley looks for them in fixed places.

Path What
~/.config/shelley/AGENTS.md Your personal guidance. See AGENTS.md for the other locations.
~/.config/shelley/<name>/SKILL.md Your skills. See Skills.
~/.config/shelley/hooks/ Hook scripts. See Hooks.
~/.config/shelley/shelley.sock The default Unix socket.
~/.local/state/shelley/agents-md.git History of personal AGENTS.md edits made in the UI.

Everything else (conversations, settings, custom models, MCP servers and their logins) is in the database given by --db.