shelley

Help

FAQ

Questions people ask about Shelley, and a few they don't.

.md

Why “Shelley”?

Because the main tool it uses is the shell, and its author likes putting “-ey” at the end of words. It is also named after Percy Bysshe Shelley, with an appropriately ironic nod at “Ozymandias.” Shelley is a computer program, and, it’s an it.

And the logo is the S. You know the one.

Is Shelley only for exe.dev?

No. It was built for exe.dev, and it comes running on every exe.dev VM, but it’s an ordinary binary for macOS and Linux (amd64 and arm64) that runs anywhere. There are no Windows builds. For what’s different on exe.dev, see Shelley on exe.dev.

How do I turn Shelley off on my exe.dev VM?

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

You don’t have to use Shelley; other coding agents run fine on exe.dev VMs, and some come pre-installed. See Shelley on exe.dev.

Does it have authentication? A sandbox?

No, and no. Shelley is single-user: anyone who can reach its port can use it, and it runs commands as the user who started it, with that user’s permissions. It listens on all network interfaces by default. Bring your own auth and isolation; Running it safely has the details and some recipes. On exe.dev, the VM is the sandbox and exe.dev’s proxy is the auth.

Can I try it without an API key?

Yes. shelley --predictable-only serve runs against a built-in fake model called predictable. It won’t write your code, but you can click around. Or use it on exe.dev, where models are included.

Where did my conversations go?

Probably into a different database. --db defaults to shelley.db in the current directory, so starting Shelley from somewhere else starts a fresh one. Pick a fixed path and always pass it:

shelley --db ~/.shelley/shelley.db serve

Global flags like --db go before serve. See where files live.

Can it listen on localhost only?

Not with a flag: --port sets the port, not the address. Use systemd socket activation (serve -systemd-activation) with a socket bound to 127.0.0.1; Installation has a pair of units for it. Or firewall the port.

Why does shelley need to be on my PATH?

The agent runs shelley itself, from its shell: shelley skill cat to load a skill, and shelley mcp to call MCP servers. Homebrew puts it there for you; with the plain binary, move it somewhere like /usr/local/bin.

I edited AGENTS.md and nothing changed.

Guidance files are read into the system prompt when a conversation starts, so edits apply to new conversations. Subagents don’t see them at all. See AGENTS.md for which files are read, and from where.

Can I use local (stdio) MCP servers?

No. Shelley connects to remote servers over Streamable HTTP, and the agent reaches their tools through shelley mcp rather than as native model tools. See MCP servers.

Recording doesn’t work.

Voice recordings are transcribed with OpenAI’s transcription models, so you need OPENAI_API_KEY set (or an exe.dev LLM integration, an llm_gateway, or a custom OpenAI model with the right name; see Models and API keys). Browsers also only allow microphone access on https:// pages and localhost, so plain http:// to another machine won’t record.

How do I update it?

Open the ⋮ menu and choose Check for New Version. Shelley downloads the release, checks it against the published checksums, replaces itself, and exits; with the systemd socket setup from Installation, the next request starts it again. There’s also an opt-in auto-upgrade, and SHELLEY_SKIP_VERSION_CHECK=true turns the checks off. With Homebrew, brew upgrade --cask shelley works too. Details in Installation.

What do the version numbers mean?

A release is cut on every push to main that passes tests. Versions look like v0.N.9OCTAL: N is the total commit count, and the digits after the 9 are the short (six-hex-digit) commit SHA in octal. shelley version tells you which one you have.

How does it relate to Sketch?

Shelley grew out of Sketch, an earlier coding agent from the same team. Unsurprisingly, much of Shelley is written by Shelley, Sketch, Claude Code, and Codex.

Can I contribute? Where do I get help?

Yes: Shelley is Apache-2.0 licensed and lives on GitHub. Contributions are welcome; we require a CLA. For bugs, open an issue. For questions and chatter, there’s the exe.dev Discord.