LEARN / SSH API, HTTPS API, MCP

Automation: SSH API, HTTPS API, tokens and MCP

“The exe.dev API is SSH.” The HTTPS API is “nothing but the SSH API shoved into a POST body.” That gives you one command set to learn, which works from a shell, an HTTP client or an agent.

Sources: https://exe.dev/docs/api, https://exe.dev/docs/https-api, https://exe.dev/docs/https-api-local-key, https://exe.dev/docs/https-api-run-on-vm, https://exe.dev/docs/https-tokens-for-vms, https://exe.dev/docs/vm-scoped-ssh-keys, https://exe.dev/docs/mcp, https://exe.dev/docs/agent-skill, https://exe.dev/docs/repo-buttons.

SSH is the API

$ ssh exe.dev ls --json | jq '.vms[0]'
{
  "https_url": "https://bloggy.exe.xyz",
  "region": "lon",
  "region_display": "London, UK",
  "ssh_dest": "bloggy.exe.xyz",
  "ssh_host": "bloggy.exe.xyz",
  "status": "running",
  "vm_name": "bloggy"
}

ssh_dest is ready to use, and it may carry a username prefix such as vm+bloggy@vm.exe.xyz.
Tools that need the parts separately should use ssh_host and ssh_user.
Registration is interactive. A key with no account gets Please complete registration by running: ssh exe.dev.
An account with no plan gets a JSON error pointing to billing.
The first time you connect, check the host key fingerprint: SHA256:JJOP/lwiBGOMilfONPWZCXUrfK154cnJFXcqlsi6lPo (https://exe.dev/docs/faq/host-key).

The HTTPS API: POST /exec

ssh exe.dev ssh-key generate-api-key --exp=30d     # get a token
curl -X POST https://exe.dev/exec \
     -H "Authorization: Bearer exe1.AAA" \
     -d whoami

The body is the command, exactly as you would type it in the REPL, and JSON output is always on.

Token permissions (signed JSON, public plaintext)

Field	Meaning	Default
`exp`	Unix time after which the token is invalid	Distant future (exe.dev “strongly recommend[s] always setting `exp`”)
`nbf`	Unix time before which it is invalid	Distant past
`cmds`	Allowed command names; subcommands are listed separately; `"ssh <vm-name>"` limits ssh to one VM	`["help","ls","new","whoami","ssh-key list","share show","exe0-to-exe1","team","team members"]`
`ctx`	Uninterpreted; passed to VMs as `X-ExeDev-Token-Ctx`	none

“The permissions JSON is public and embedded as plaintext in your token. Do not put secrets in it.”

Limits and errors

Status codes. 401 invalid token, 400 bad body or syntax, 413 when the body is over 64 KB, 504 when a command runs past 30 seconds, and 429 when you are rate limited.
No stdin and no pty. Commands that need interactive input won’t work. In exe.dev’s words: “If it hurts, don’t do it.”
No replay protection. “There is no built-in nonce or jti mechanism. Use short-lived tokens (small exp) to limit the replay window.”

Local token creation

You can mint tokens offline by signing with your SSH key: ssh-keygen -Y sign -n v0@exe.dev. These are exe0 tokens, and exe0-to-exe1 converts one into the short exe1 handle (https://exe.dev/docs/https-api-local-key).

Running commands inside a VM over HTTPS

Send -d 'ssh my-vm whoami' to /exec. A few details:

The exit status comes back in an X-Exe-Exit trailer.
Accept: application/x-ndjson streams the output.
Long jobs should detach with setsid nohup.

Source: https://exe.dev/docs/https-api-run-on-vm.

Tokens for your VM’s own HTTPS endpoints

The auth proxy assumes a browser and cookies. “For API servers or git push over HTTPS, you can generate bearer tokens that the proxy will respect”:

ssh exe.dev ssh-key generate-api-key --vm=my-vm --label=deploy

Scope. The namespace is v0@VMNAME.exe.xyz, so a token works for one VM only.
How to send it. X-Exedev-Authorization: Bearer <token> is preferred, and the proxy strips it before forwarding. Plain Authorization: Bearer still works but is deprecated. Basic auth also works, with the token as the password, which suits git on the VM proxy only.
What your server sees. X-ExeDev-UserID, X-ExeDev-Email and X-ExeDev-Token-Ctx.

VM-scoped SSH keys

cat key.pub | ssh exe.dev ssh-key add --vm=my-vm adds a key that can SSH to that one VM and sign HTTPS tokens for it (https://exe.dev/docs/vm-scoped-ssh-keys).

The exe.dev MCP server

exe.dev runs its own MCP server at https://exe.dev/mcp. “The client will open your browser to connect.”

There are plugins for Claude and an app for ChatGPT in https://github.com/boldsoftware/exe.dev.

This field guide’s /mcp endpoint is a different thing. It is read-only, unofficial, and only reads exe.dev’s public docs. See the MCP page.

Teaching agents

Agent skill. exe.dev publishes skill/SKILL.md in https://github.com/boldsoftware/exe.dev. It points agents to the docs index at https://exe.dev/docs.md (https://exe.dev/docs/agent-skill).
llms.txt. https://exe.dev/llms.txt lists every docs page with a .md version.
Repo buttons. https://exe.dev/new?repo=https://github.com/OWNER/REPO starts a VM, opens Shelley, clones the repo and prefills the deploy instructions. Shelley follows AGENTS.md when a repo has one (https://exe.dev/docs/repo-buttons).

Getting help

Email support@exe.dev, or join the Discord.
Include your VM name.
grant-support-root <vm-name> on lets exe.dev staff SSH into the VM, and off revokes it (https://exe.dev/docs/getting-help).

← Proxy, sharing, domains, email · Integrations →