Command Reference

A command is a unit of work sent from the studio to an agent. The contract is exact: what each command takes, what it returns, and how its state moves.

The envelope

Every command travels inside the same message envelope:

{
  "v": 1,
  "type": "command",
  "kind": "request",
  "id": "0a3b…",
  "timestamp": "2026-10-21T08:14:22.101Z",
  "payload": {
    "command": "shell",
    "args": { "script": "uname -a", "cwd": "/tmp" },
    "timeout": 300000
  }
}

Command status

pending  ──▶  in_progress  ──▶  completed

The status lives in the database, not in memory, so both delivery paths — the socket and the polling fallback — write the same rows and the same states.

Result envelope

The agent answers with the same envelope, kind set to response and the command's id:

{
  "v": 1,
  "type": "command",
  "kind": "response",
  "id": "0a3b…",
  "timestamp": "2026-10-21T08:14:22.229Z",
  "payload": {
    "ok": true,
    "data": {
      "status": "success",
      "output": {
        "stdout": "Linux bench-01 …",
        "stderr": "",
        "exitCode": 0,
        "durationMs": 128
      }
    }
  }
}

A command that runs but ends badly — a non-zero exit code, say — still answers with ok: true; the failure shows up as data.status: "error". An ok: false answer means the command could not be run at all, and carries an error object instead of data:

{
  "v": 1,
  "type": "command",
  "kind": "response",
  "id": "0a3b…",
  "timestamp": "…",
  "payload": {
    "ok": false,
    "error": { "code": "MISSING_SCRIPT", "message": "No script provided" }
  }
}

The studio stores the whole result — including the error — as JSON.

Error codes

The same set is produced by both delivery paths — the socket and the polling fallback — because both call the same handlers.

Timeout and spawn failures

Two failures are reported through the output rather than through the result's status.

The commands

The argument list of each command is a contract, not a convention: the studio's Agents console builds its form from it, and the agent's local command test builds the same form from it.

shell

Runs a shell script on the machine under test.

The script's timeout is the envelope's payload.timeout, in milliseconds. It defaults to 300000.

The agent writes the script to <cwd>/.agent_script_<timestamp>.sh, makes it executable and spawns /bin/bash on it with cwd as the working directory.

On timeout, stderr reads Command timed out after <ms>ms.

{
  "command": "shell",
  "args": {
    "script": "#!/bin/bash\necho hello",
    "cwd": "/tmp"
  },
  "timeout": 300000
}

get_system_info

Takes no arguments. Returns a snapshot of the machine.

{
  "command": "get_system_info",
  "args": {}
}

{
  "ok": true,
  "data": {
    "status": "success",
    "output": {
      "stdout": "{\n  \"hostname\": \"bench-01\",\n  \"platform\": \"linux\",\n  \"arch\": \"x64\",\n  \"cpuCount\": 8,\n  \"totalMemory\": 16654786560,\n  \"freeMemory\": 9123409920,\n  \"uptime\": 864021,\n  \"loadAverage\": [0.4, 0.3, 0.2],\n  \"networkInterfaces\": []\n}",
      "durationMs": 0
    }
  }
}

The parsed object holds hostname, platform, arch, cpuCount, totalMemory, freeMemory, uptime, loadAverage and networkInterfaces.

get_serial_ports

Takes no arguments. Returns the serial ports available on the machine, each with its path, manufacturer, serialNumber, vendorId and productId where the platform reports them.

Like get_system_info, the answer is a JSON string in output.stdout — an array of port objects, or [] when the serialport native bindings are missing.

open_serial

Opens a serial port on the agent.

{
  "command": "open_serial",
  "args": { "path": "/dev/ttyUSB0", "baudRate": 115200 }
}

The local endpoint takes them:

{ "action": "open", "path": "/dev/ttyUSB0", "baudRate": 115200, "dataBits": 8, "stopBits": 1, "parity": "none" }

close_serial

Closes a port the agent has open. Takes path.

serial_write

Writes to a port the agent already has open.

The result reports whether the write succeeded: stdout reads Data sent to <path> or Failed to send to <path>. A write to a port the agent does not have open is refused and the result is status: "error".

screen_watch

Starts or stops the screen watch on a device under test. While the watch is on, the bench sends a screen_frame event for every frame it takes.

The bench takes one frame per device per tick, and skips a tick when the previous capture is still running — a slow device ends up at a lower frame rate rather than a growing queue.

The frames themselves travel as screen_frame events, not as the result of this command. The command's own result says only whether the watch was started or stopped.

run_test_suite

Runs a test suite on the device under test. This is the command the platform's test runner issues when it executes a suite.

The result is a normal command result: status, the output of the runner, and — on failure — an error with a code and a message.

upload_artifact

Uploads an artifact from the bench to the studio.

The file is read on the agent and transferred to the studio, where it is kept with the artifacts of the project. The result is a normal command result.

See also

• Remote Shell and Serial — the same commands, in use.
• Socket Protocol — how the envelope travels.
• API Reference — the endpoints that carry commands.
• Error Codes — the codes above, in one list.