Shelley on exe.dev

Every 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 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 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.
• Conversations start in your home directory unless you pick another.
• The image includes a headless Chromium on Shelley’s PATH, so the browser tool works out of the box.

Logs are in the journal:

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:

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. The key stays off the VM, and Shelley picks up the models like any other integration models.
• In Shelley. Add a custom model 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. 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 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), 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 if it has one.
• &tags=... tags the new VM.

Public repos can put a button in their README:

[![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), for exe.dev’s integrations, action links, and speech-to-text.
• Email as a notification 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):

LABEL exe.dev/install-shelley=true

See exe.dev’s customization docs 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:

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