# Shelley on exe.dev

> Where Shelley lives on an exe.dev VM, where its models come from, and how to upgrade, customize, or turn it off.

Every [exe.dev](https://exe.dev/) VM started from the default `exeuntu` image
comes with Shelley installed and running. There's nothing to download and no
API key to set, and the VM is the machine of its own that the
[security page](/docs/security) recommends. Most of the rest of these docs
apply as written; this page covers what's different.

## Where it is

Open `https://<vmname>.shelley.exe.xyz/`. exe.dev's proxy handles the login,
so only you can reach it, plus anyone you've given
[Root access](https://exe.dev/docs/sharing) to the VM. (A Web share isn't
enough; it doesn't include Shelley.)

Under the hood, Shelley runs as your VM user (`exedev`) under systemd:

- `shelley.socket` listens on `127.0.0.1:9999`, so it's reachable only
  through exe.dev's proxy, never directly from the internet.
- `shelley.service` runs
  `shelley -debug -db ~/.config/shelley/shelley.db -config /exe.dev/shelley.json serve -systemd-activation -require-header X-Exedev-Userid`.
  The proxy sets `X-Exedev-Userid`; see [`-require-header`](/docs/security#-require-header).
- Conversations start in your home directory unless you pick another.
- The image includes a headless Chromium on Shelley's `PATH`, so the
  [browser tool](/docs/tools) works out of the box.

Logs are in the journal:

```sh
journalctl -u shelley -f
```

Run as many conversations as you like, on one VM or spread across several;
each VM has its own Shelley and its own database.

## Models

On exe.dev you don't need API keys. Shelley discovers the LLM integrations
attached to the VM (through the `reflection` integration) and offers their
models in the model picker. New accounts get a default integration named
`llm`, attached to every VM, backed by exe.dev's managed gateway. Any attached
integration of type `llm` shows up, not just that one.

If the integration's model list changes while Shelley is open, click
**Refresh** in the model picker. If Shelley shows no models at all, it tells
you which of these to run in the exe.dev shell (`ssh exe.dev`), then Refresh:

```sh
integrations attach llm auto:all
integrations add llm --name llm --attach auto:all
integrations attach reflection auto:all
integrations add reflection --name reflection --fields all --attach auto:all
```

The `attach` forms are for when the integration exists but isn't attached; the
`add` forms create it.

### Bringing your own key

Two ways, with different trade-offs:

- **On the integration.** Add your provider key (or a ChatGPT subscription)
  as a provider source on an exe.dev
  [LLM integration](https://exe.dev/docs/integrations-llm). The key stays off
  the VM, and Shelley picks up the models like any other integration models.
- **In Shelley.** Add a [custom model](/docs/models#custom-models-and-endpoints)
  from **Manage…** in the model picker. This works for any compatible endpoint,
  but the key is stored in Shelley's database on the VM.

Environment variables like `ANTHROPIC_API_KEY` don't help much here. You'd
have to add them to the systemd unit, and the integration's models win
wherever both offer the same model ID, so the key only adds models the
integration doesn't have.

### Credits

Models from exe.dev's managed gateway are paid for with Shelley credits. Plans
with Shelley access include an initial credit, and you can buy more at
[exe.dev/user/shelley](https://exe.dev/user/shelley). Your own keys and
subscriptions don't use credits.

On a team, credits aren't shared: each member has their own balance and
history. Members can buy credits with the team's card; the credits land in the
member's own balance, and the charge goes to the team's billing owner, who can
see per-member Shelley spending on the team billing page. See exe.dev's
[billing docs](https://exe.dev/docs/billing/overview) for what each plan
includes.

## Upgrading

A VM runs the Shelley that was current when the VM was created, unless you
turn on auto-upgrade in the Version dialog. To update it, either:

- open the ⋮ menu in Shelley and choose **Check for New Version**
  (see [Upgrading](/docs/install#upgrading)), or
- run `shelley install <vmname>` in the exe.dev shell.

After an upgrade, systemd starts the new version on the next request, and
conversations that were in the middle of a turn carry on.

## Opening Shelley from a link

`https://exe.dev/new` creates a VM and opens Shelley on it. Query parameters
pre-fill the new VM:

- `?prompt=...` starts Shelley with that prompt.
- `?repo=https://github.com/OWNER/REPO` clones the repo and pre-fills
  instructions to deploy it. Shelley follows the repo's
  [AGENTS.md](/docs/agents-md) if it has one.
- `&tags=...` tags the new VM.

Public repos can put a button in their README:

```markdown
[![Build with Shelley](https://raw.githubusercontent.com/boldsoftware/exe.dev/main/assets/buttons/build-with-shelley.png)](https://exe.dev/new?repo=https://github.com/OWNER/REPO)
```

The same trick makes a good "Edit with Shelley" link on internal tools: point
it at the VM's `https://<vmname>.shelley.exe.xyz/`, or at `exe.dev/new` with a
pre-filled prompt and tags.

## exe.dev extras

A few things only light up on exe.dev:

- Skills marked `when: exe.dev` ([skills](/docs/skills)), for exe.dev's
  integrations, action links, and speech-to-text.
- Email as a [notification](/docs/conversations#notifications-and-phones)
  channel.
- Voice recordings transcribed through the LLM integration, no OpenAI key
  needed.

## Custom images

If you boot VMs from your own image, add this label to have exe.dev install a
recent Shelley in `/usr/local/bin` when the VM is created (and have exe.dev's
UI assume it's there):

```dockerfile
LABEL exe.dev/install-shelley=true
```

See exe.dev's [customization docs](https://exe.dev/docs/customization) for the
rest.

## Turning it off

You don't have to use Shelley. Other coding agents run fine on exe.dev VMs, and
some come pre-installed on the default image. To stop Shelley and keep it from
starting again:

```sh
sudo systemctl disable --now shelley.socket shelley.service
```