Skip to main content
Glama

Run a command in the guest

exec

Run a shell command inside a cloud Linux computer as root, returning stdout and stderr as text or base64. Use background mode for long-running builds, servers, and test suites.

Instructions

Run a shell command inside the computer. Runs as root with no display by default — anything that opens a window needs desktop: true, anything slower than a few seconds needs background: true, and anything that needs an environment variable takes env rather than an assignment written into the command. Against the hosted platform, waiting here is capped at about two minutes by a proxy in front of it, not by timeout_s. One computer runs at most sixteen background commands at once: the seventeenth is refused rather than queued, and exec_kill on a pid you already hold is what makes room. What the command printed comes back as stdout and stderr when it is text, and as stdout_b64 and stderr_b64 — base64 of the exact bytes — when it is not, so a command that emits binary is never quietly turned into replacement characters.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "command": "<command>"
    },
    "name": "exec"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNoAbsolute path to run in. If it does not exist the command does not run, and exit_code is 127.
envNoEnvironment for this command, as {NAME: "value"}. Use it instead of writing FOO=bar in front of the command: a prefix assignment is shell syntax, so a value holding a space, a quote, a newline or a $ has to be quoted correctly by you and is silently truncated or re-parsed when it is not, while this reaches the process whole and unquoted. It also keeps a secret out of the command line, which is world-readable in the guest's ps and, for a background command, comes back to you inside every exec_poll answer. The variables are added on top of the guest's login profile rather than replacing it, so PATH and the rest are still there, and they apply to this command only — including with desktop: true. Names must not be empty or contain "=". At most 64 entries, each at most 4096 bytes counted as NAME=value in UTF-8; past either nothing runs.
commandYesA shell command line.
desktopNoRun inside the logged-in desktop session instead of as root with no display. Required for anything with a window: the guest agent has no DISPLAY, so a GUI app started without this cannot draw. Not needed for secrets bound as environment variables (set_computer_secrets): on an image that supports it, every exec, plain or desktop, runs with the bound variables as they are at that moment. Linux only.
timeout_sNoHow long to wait for it to exit, up to the server limit of 600 seconds. A command that outlives this keeps running inside the guest — your deadline passing means you stopped waiting, not that the work was destroyed. Against the hosted app.mandala.computer, do not reach past about 120 here: a proxy in front of the platform abandons the request at roughly two minutes and answers 524 whatever this says, so a larger number buys no time and only delays the failure. Use background: true for anything slower. The range above 120 is for a self-hosted MANDALA_BASE_URL reached without that proxy.
backgroundNoReturn a handle immediately instead of waiting. Use for builds, installs, test suites and servers, then read output with exec_poll. To learn that it finished, wait_for_event with types ["process.exited"] and the pid this returns — the computer reports the exit, so waiting for it costs one call rather than an exec_poll loop. Strictly better than backgrounding with "&", which throws away the exit code and the output. A computer runs at most sixteen of these at once, and past that this is refused with a 409 saying how many are already running rather than queued. A slot is held until its command exits, which for a server is never, so the way out of that refusal is exec_kill on a pid an earlier exec returned — not another attempt.
computer_idNoWhich computer. Defaults to the one selected with use_computer.
retain_outputNoExplicit synchronous output retention only. False/absent preserves default behavior. A valid result_id confirms a retained version; optional failure never replays the command.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.18.0
    • addedInput schema / properties / env / propertyNames
      Added value: +{
      +  "type": "string"
      +}
  2. Changed1 schema field changedv0.15.0
    • changedInput schema / properties / env / description
      Previous value: -"Environment for this command, as {NAME: \"value\"}. Use it instead of writing FOO=bar in front of the command: a prefix assignment is shell syntax, so a value holding a space, a quote, a newline or a $ has to be quoted correctly by you and is silently truncated or re-parsed when it is not, while this reaches the process whole and unquoted. It also keeps a secret out of the command line, which is world-readable in the guest's ps and, for a background command, comes back to you inside every exec_poll answer. The variables are added on top of the guest's login profile rather than replacing it, so PATH and the rest are still there, and they apply to this command only — including with desktop: true. Names must not be empty or contain \"=\"."New value: +"Environment for this command, as {NAME: \"value\"}. Use it instead of writing FOO=bar in front of the command: a prefix assignment is shell syntax, so a value holding a space, a quote, a newline or a $ has to be quoted correctly by you and is silently truncated or re-parsed when it is not, while this reaches the process whole and unquoted. It also keeps a secret out of the command line, which is world-readable in the guest's ps and, for a background command, comes back to you inside every exec_poll answer. The variables are added on top of the guest's login profile rather than replacing it, so PATH and the rest are still there, and they apply to this command only — including with desktop: true. Names must not be empty or contain \"=\". At most 64 entries, each at most 4096 bytes counted as NAME=value in UTF-8; past either nothing runs."
  3. First observedv0.13.1

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does: it discloses running as root with no display by default, the ~2-minute proxy cap against hosted platform (independent of timeout_s), the 16-concurrent-background-command limit with a 409 refusal rather than queueing, and that a timeout only stops waiting, not the work. It also explains output encoding (stdout/stderr vs base64 byte streams).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action, then layers on behavior in a single dense paragraph where nearly every clause carries specific information. It is long but nearly all content earns its place; a modest structural improvement (splitting the behavioral caveats) would help readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters, nested env object, no output schema, and no annotations, the description covers execution context, limits, timeout semantics, and return format. Nothing an agent needs to call it correctly and interpret results is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the per-parameter descriptions already document env, desktop, timeout_s, background, cwd, and retain_output in depth. The description reinforces usage (env vs assignment, background for slow work) but adds little parameter meaning beyond what the schema already provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run a shell command inside the computer'), and the surrounding text distinguishes it from exec_poll, exec_kill, and wait_for_event by role. An agent can immediately tell this is the command-execution entry point versus the polling/killing siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes conditions to mechanisms: window-opening needs desktop:true, slow work needs background:true, environment variables go in env rather than prefix assignment, and freeing a background slot uses exec_kill on a held pid. It names the alternatives (exec_poll, wait_for_event, exec_kill) and the situations that select them.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools