← Features

HTTPS API: Run commands on VM

You can execute commands on your VMs over the HTTPS API, using the same /exec endpoint with the same ssh command you would type into the REPL.

Quick start

Generate a token that is allowed to use ssh:

ssh exe.dev ssh-key generate-api-key --label=deploy --cmds=ssh --exp=30d
# Restricts to one VM
ssh exe.dev ssh-key generate-api-key --label=deploy --cmds="'ssh my-vm'" --exp=30d

Then run:

curl -X POST https://exe.dev/exec \
     -H "Authorization: Bearer exe1.AAA" \
     -d 'ssh my-vm whoami'

Output and exit codes

The response body is output of your command combined, so you can redirect the curl output as you need to. Be aware that stderr is mixed in there (unlike a typical shell redirect).

curl -X POST https://exe.dev/exec \
     -H "Authorization: Bearer exe1.AAA" \
     -d 'ssh my-vm cat build/app.tar.gz' > app.tar.gz

The exit code is in the X-Exe-Exit trailer; use -D for curl to show it:

$ curl -sD - -X POST https://exe.dev/exec \
     -H "Authorization: Bearer exe1.AAA" \
     --data-raw 'ssh my-vm false'
X-Exe-Exit: 1

Quoting and all that

Your command passes through two parsers, and each one eats a layer of quoting:

  1. The lobby parses the request body with a shell lexer.
  2. The VM parses whatever the lobby handed it, much like sshd

So a pipeline, a redirect, or a quoted argument has to survive being quoted twice. Type a command below to see both layers:

If you want to return JSON, run a complicated bash pipeline, or start a process and return immediately, whip up the appropriate one-liner for that. The world is your oyster.

Returning immediately

To detach your command from the initiating HTTPS request, detaching it with setsid nohup and shell redirection.

curl -X POST https://exe.dev/exec \
     -H "Authorization: Bearer $TOKEN" \
     -d 'ssh my-vm "setsid nohup ./build.sh > /tmp/build.log 2>&1 & echo started"'