Run commands

POST /v1/instances/{id}/exec runs a shell command inside the instance, straight from your backend. It is the escape hatch for anything the API does not wrap as its own call. The command runs through sh -c as the image’s default user, on the same box the agent works on, so it sees the agent’s files, tools, and credentials.

Request

command

string

required

The shell command to run inside the instance. It is passed to sh -c, so pipes, redirects, and && chains all work.

Only running instances accept commands. Exec against any other status returns 400 invalid_request (a deleted instance returns 404 not_found), and it does not wake a sleeping instance: start it, or hit one of its URLs, first. If the platform cannot reach the instance at all, you get 502 provisioning_failed.

Response

A command that runs but exits nonzero is a normal result: you get 200 with its exit_code, stdout, and stderr. Errors are reserved for the platform, not your command.

exit_code

integer

The command’s exit code. Nonzero is still a 200; read this to branch.

stdout

string

Standard output, capped at 512 KB. See truncated.

stderr

string

Standard error, with its own separate 512 KB cap.

truncated

boolean

true when either stream spilled past its 512 KB cap. The middle of the output is cut and a truncation marker is left in its place.

exit_code values 125, 126, and 127 may come from the container runtime rather than your command, for example 127 when the binary is not found. A command runs for up to 280 seconds, after which the call fails with 502 provisioning_failed; start longer jobs in the background (nohup ... &) and poll with a second exec.

Example

curl -X POST https://api.agent37.com/v1/instances/ab12cd34ef/exec \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "command": "node --version" }'

import requests

resp = requests.post(
    "https://api.agent37.com/v1/instances/ab12cd34ef/exec",
    headers={"Authorization": "Bearer sk_live_..."},
    json={"command": "node --version"},
)
result = resp.json()
print(result["exit_code"], result["stdout"])

const resp = await fetch(
  "https://api.agent37.com/v1/instances/ab12cd34ef/exec",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ command: "node --version" }),
  }
);
const result = await resp.json();
console.log(result.exit_code, result.stdout);

{
  "exit_code": 0,
  "stdout": "v24.2.0\n",
  "stderr": "",
  "truncated": false
}

Build on exec

Anything the API does not wrap as its own endpoint, you build on exec. For moving files, prefer the instance’s own files endpoints at https://{instanceId}.agent37.app — PUT /v1/files/content to upload, GET /v1/files/content to download — but a quick text read works over exec too. A “Download the report” button in your product can be one exec call that reads the file the agent wrote:

curl

curl -X POST https://api.agent37.com/v1/instances/ab12cd34ef/exec \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "command": "cat ~/reports/ev-makers-memo.md" }'

Pushing a file in is the same trick in reverse. Encode it on your side and decode it inside the instance:

curl

curl -X POST https://api.agent37.com/v1/instances/ab12cd34ef/exec \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "command": "mkdir -p ~/data && echo aGVsbG8sd29ybGQK | base64 -d > ~/data/ev-prices.csv" }'

For binary or large files, use the files endpoints on the instance URL instead — GET /v1/files/content streams a download of any size, with no 512 KB cap — or stage them at a URL your backend controls and curl them down from inside the instance.

Get started

Build with Agent37

Hosting API

Agent API

Reference

Request

Response

Example

Build on exec

​Request

​Response

​Example

​Build on exec

Request

Response

Example

Build on exec