Run a command

POST /v1/infra/servers/:id/exec

Runs a shell command on a BLACKHOLE server through the tunnel agent. The full standard output (stdout), error stream (stderr), and return code are passed to the client. By default the response is JSON, returned after the command finishes (recommended for AI agents and scripts). If you need line-by-line progress, pass ?stream=true and read the stdout/stderr/exit SSE events. A failure during command execution arrives in streaming mode as an error event.

For AI agents and MCP clients, always use JSON mode (without ?stream=true) — they cannot parse SSE. The official Vibecode MCP client (the manage_server_deploy tool) drops this parameter itself and always works in JSON mode.

Streaming gives you live progress, but it does not raise the execution time limit: the limit is the same in both modes and equals timeout + 30 seconds, while timeout itself is capped at 600 seconds. For work that clearly will not fit within that limit, start a background job — see "Background jobs" below.

Which servers it runs on

The server kind arrives in the kind field of the GET /v1/infra/servers and GET /v1/infra/servers/:id responses.

Parameters

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/exec" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la /opt/app", "timeout": 30}'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/exec" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm ci --production", "workdir": "/opt/app", "timeout": 180}'

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/exec`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      command: 'node -v',
      timeout: 10,
    }),
  }
)
const { data } = await res.json()
console.log(`exit ${data.exitCode} in ${data.duration}s:\n${data.stdout}`)

JavaScript — OAuth application

// A command with environment variables and a working directory
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/exec`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      command: 'npx tsx scripts/seed.ts',
      workdir: '/opt/app',
      env: { DATABASE_URL: 'postgresql://localhost/mydb' },
      timeout: 60,
    }),
  }
)

Response fields

Response example

{
  "success": true,
  "data": {
    "exitCode": 0,
    "stdout": "Linux epd65hdv07p8g89c0c06 6.8.0-107-generic #107-Ubuntu SMP PREEMPT_DYNAMIC Fri Mar 13 19:51:50 UTC 2026 x86_64 x86_64 x86_64 GNU/Linux\n",
    "stderr": "",
    "duration": 5,
    "truncated": false
  }
}

Error response example

409 — another operation is already running on the server. This is a failure before the command starts, so the HTTP status reflects the outcome. A Galaxy application returns the same status when the host's shared exec channel is busy — that one arises during execution, but it means the same thing: busy, retry:

{
  "success": false,
  "error": {
    "code": "EXEC_BUSY",
    "message": "Another operation is running on this server",
    "retryable": true,
    "retryAfter": 10
  }
}

The response also carries a Retry-After HTTP header (in seconds, equal to the retryAfter field) — this is a short poll interval: keep retrying with it until the lock clears. The full upper bound — when the lock auto-expires — is in error.hint.autoExpiresInSeconds.

Errors

The endpoint's errors fall into two groups, and they are delivered differently. A failure before the command starts arrives with a real HTTP status. A failure during execution arrives in the response body — with one exception: a busy exec channel (EXEC_BUSY) on a Galaxy application arrives as a real 409, because it is a "busy" refusal rather than a failure.

Errors before the command starts

Errors during execution

The HTTP status does not reflect the command's outcome. On a standalone virtual machine (kind: "STANDALONE") the connection is held open for the whole run, and the 200 status is sent before execution begins — so both a successful and a failed command arrive with the code 200. The failure marker is the success: false field and the error object in the response body. Check success in the body, not the HTTP status: a client that branches on the status will treat a failed command as successful. For a Galaxy application (kind: "GALAXY_APP") the same error arrives with the status 502.

The `hint` fields on `EXEC_TIMEOUT`

The hint arrives both in the JSON response and in the SSE error event of streaming mode. An agent-side EXEC_BUSY carries a hint object of the same shape — on a standalone virtual machine (kind: "STANDALONE") its recoveryAction points to POST /v1/infra/servers/:id/unstick. On a Galaxy application that path is closed to the owner, so its recoveryAction describes retrying and contacting support.

A tunnel communication failure arrives in the same shape — with its own code in the error.code field (for example TUNNEL_NOT_FOUND or GATEWAY_TIMEOUT: …). Some gateway codes carry details after a colon (GATEWAY_UNREACHABLE: …, GATEWAY_TIMEOUT: …), so match error.code by prefix, not by an exact comparison. In streaming mode (?stream=true) the same errors arrive as an SSE error event. The event data carries code and message, and for EXEC_TIMEOUT, GATEWAY_TIMEOUT and an agent-side EXEC_BUSY it also carries a hint. The GATEWAY_TIMEOUT hint states the key point: no exit status came back, so the outcome of the command is unknown and it may still be running on the server — do not re-run it blindly, check the state first. These events carry no success field — the error event itself is the failure marker.

Full list of common API errors — Errors.

Known specifics

• A sleeping standalone virtual machine is woken by the command itself. If the server (kind: "STANDALONE") is in sleeping status, the platform starts the wake and waits for it within the same request — up to 6.5 minutes — and only then runs the command. A separate /wake call is not needed, but the client's request timeout must be longer than that window. If the server does not come up, 503 WAKE_TIMEOUT arrives and the server returns to sleeping — the command never ran, so a repeat request is safe.
• The command runs through /bin/sh. The command field is executed by the /bin/sh interpreter — a minimal POSIX shell (dash), not bash. Constructs specific to bash (set -o pipefail, [[ … ]], arrays) are not available there and fail with an error. Run them explicitly — via command: "bash -c 'set -o pipefail; …'" or as a script file command: "/bin/bash /opt/app/script.sh".
• Server-level locking. While an /exec or /deploy is running, a second such call returns 409 EXEC_BUSY. If the previous /deploy was interrupted (for example, failed at the healthcheck step or the client aborted the connection on a timeout), the server lock remains held until it expires automatically — for /deploy this is up to 15 minutes, for /exec — until the command's timeout plus 90 seconds has elapsed. The lock can be released immediately by calling DELETE /v1/infra/servers/:id/lock, after which /exec works again. There is no need to recreate the server.
• The maximum size of stdout/stderr is 5 MB per stream. If the command's output is larger, truncated: true arrives and the tail is cut off. The command still ran to completion, and exitCode is correct. For large output, redirect to a file: command: "my-cmd > /opt/app/output.log 2>&1" and then read it via /exec cat /opt/app/output.log.
• The .env from /deploy is not picked up automatically. Systemd loads .env when the service starts, but not for one-off commands via /exec. If you need DATABASE_URL / API keys, pass them in the env field: { env: { DATABASE_URL: "..." } }.
• The two timeouts together give timeout + 30 seconds. The agent kills the process exactly at timeout; the Gateway waits another 30 seconds for the final events and only then returns EXEC_TIMEOUT.
• Keeping the connection alive in JSON mode. If the command runs longer than 15 seconds, the server periodically sends spaces in the response body — this prevents timeouts in nginx and intermediate proxies. The spaces go inside the already-opened JSON object, so the body looks like JSON ({) from its very first byte instead of starting with spaces: strict clients and ordinary parsers read it the same way, and you do not need to trim anything by hand.
• Client timeout: make sure it is inter-byte, not total. The keepalive spaces reset "silence" timeouts, so the classic Python socket timeouts (urlopen(..., timeout=300), the requests read timeout) will not by themselves abort a long command in JSON mode. Two other things do abort it. First — clients and wrappers with a true wall-clock deadline for the whole request (for example, aiohttp with ClientTimeout(total=…) or an agent framework's own deadline): keepalive cannot help against those. Second — the server-side timeout of the command itself (300 seconds by default): once it expires, the agent kills the process and you get EXEC_TIMEOUT regardless of the client settings — do not mistake it for a client-side disconnect. In practice: in Python set split timeouts — requests.post(url, json=body, headers=headers, timeout=(10, 60)) — 10 seconds for connect and 60 for the inter-byte pause. If the client does drop the connection, the server-side lock persists for up to timeout + 90 seconds (EXEC_BUSY for repeated calls). Commands longer than a few minutes are better run as a background job — see "Background jobs" below. On a sleeping server this rule does not apply right away: the spaces start only after the wake, so up to 6.5 minutes of complete silence precede the first byte of the response, and the timeout=(10, 60) recipe aborts the request before the command even starts. Either raise the inter-byte timeout above that window, or wake the machine in advance with /wake and wait=true, then call /exec on a machine that is already up.

Unsticking a stuck channel

If /exec still returns EXEC_BUSY after DELETE /v1/infra/servers/:id/lock (and /deploy fails with the code DEPLOY_FAILED and the message "Another command is running"), the agent-side exec mutex is stuck: the server lock is released, but a background process keeps the channel busy. That case is handled by POST /v1/infra/servers/:id/unstick — its parameters, response and every refusal code are covered there.

Choosing the mode

Three call modes and when each one fits:

Do not set the client-side overall request deadline lower than the command's timeout — the client would cut the connection before the server can answer. A sleeping server adds up to 6.5 minutes of wake time to that deadline — the example below assumes a machine that is already up. An example of split timeouts in Python:

import requests
r = requests.post(
    f"{VIBE_URL}/v1/infra/servers/{SERVER_ID}/exec",
    headers={"X-Api-Key": VIBE_API_KEY},
    json={"command": "npm ci --production", "workdir": "/opt/app", "timeout": 600},
    timeout=(10, 60),   # 10 seconds to connect, 60 for a pause between bytes
)

Raising the timeout of /exec does not help the install step — deploy steps have their own 300-second limit, separate from the 600 seconds of /exec.

Important: the timeout default is 300 seconds, not 600. The 600 ceiling exists, but to use it the field must be passed explicitly. A command planned for nine minutes and started without timeout is killed at the fifth minute.

Background jobs

The timeout of /exec is capped at 600 seconds, and when it expires the agent terminates the whole process group forcibly (SIGKILL, no grace period). Run anything longer — package installation, a database dump restore, a heavy build — as a background job: /exec returns instantly, the channel is freed (a second call will not hit EXEC_BUSY), and the process keeps running independently of the HTTP connection.

Recommended — a transient systemd unit

{ "command": "systemctl reset-failed restore-db 2>/dev/null; systemd-run --unit=restore-db /bin/bash /opt/data/restore.sh", "timeout": 30 }

The job gets its own cgroup and lives independently of the exec session. Manage it with standard calls:

• status: { "command": "systemctl is-active restore-db" } — active (running), inactive (finished successfully), failed (crashed).
• logs: journald picks up the unit's output automatically — read it via GET /v1/infra/servers/:id/logs?service=restore-db.
• systemctl reset-failed <name> before a rerun — otherwise systemd refuses to create a unit with the name of the failed job.

Lightweight — background with output redirect

{ "command": "(cd /opt/app && npm run build > /tmp/build.log 2>&1 &)", "timeout": 10 }

Redirecting both streams to a file is mandatory — it releases the exec session's pipes. Progress: { "command": "tail -20 /tmp/build.log" }.

Anti-pattern — bare `nohup`

nohup cmd & without a redirect does not work: in a pipe (rather than a terminal) nohup does not redirect the output, the background process inherits the exec session's pipe, and the agent waits for it to close right up to the timeout — then forcibly terminates the whole process group, including your "background" process. Always add > file 2>&1.

Pass secrets (database passwords and the like) via the env field, not inside command — the agent logs executed commands (the first 200 characters). Also keep in mind that the install/preStart steps of /deploy have their own 300-second timeout — move heavy installations into a one-off /exec or a background job, not into the install script.

See also

• Full deploy
• Release a stuck lock
• Service logs
• Upload a file
• Repair the tunnel
• A fast release cycle
• Galaxy app