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

Exit codes without trailers

Some HTTP clients cannot read trailers, fetch among them. Send Accept: application/x-ndjson and the response is one JSON object per line instead: the output, base64-encoded and labelled stdout or stderr, then the exit code.

$ curl -X POST https://exe.dev/exec \
     -H "Authorization: Bearer exe1.AAA" \
     -H "Accept: application/x-ndjson" \
     --data-raw 'ssh my-vm "echo hello; echo oops >&2; exit 3"'
{"stdout":"aGVsbG8K"}
{"stderr":"b29wcwo="}
{"exit_code":3}

The output still streams as it is produced. If the VM never reports an exit status, the last line is an {"error": "..."} instead, and the output may be incomplete. A response that ends with neither was cut off.

Every 30 seconds, the response also gets a blank line, which carries nothing: it keeps HTTP clients and proxies that give up on a quiet connection (Node's fetch does after 5 minutes) from cutting off a command that is working without printing anything. Skip blank lines when you read the response. The plain response, without Accept: application/x-ndjson, has none: its body is only your command's output.

Long-running commands

ssh has no time limit over the API: the command runs for as long as the request stays open, and is stopped when the client disconnects. For a command that runs longer than your HTTP client or proxy will wait on a quiet connection, use Accept: application/x-ndjson, whose blank lines keep the connection busy, or return immediately and check on it later.

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, use 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"'