HTTPS API: Run commands on VM
Run commands inside your VMs over the HTTPS API
You can execute commands on your VMs over the [HTTPS API](/docs/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`:
```bash
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:
```bash
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).
```bash
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:
```bash
$ 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:
<div id="command-quoter"></div>
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.
```bash
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"'
```