# shelley.json

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

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:

```sh
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

```json
{
  "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](https://github.com/boldsoftware/shelley/blob/main/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](/docs/models).

## Environment variables

Besides the API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
`GEMINI_API_KEY`, `FIREWORKS_API_KEY`; see [Models and API keys](/docs/models)),
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](/docs/agents-md) for the other locations. |
| `~/.config/shelley/<name>/SKILL.md` | Your skills. See [Skills](/docs/skills). |
| `~/.config/shelley/hooks/` | Hook scripts. See [Hooks](/docs/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`.