Run a command in the guest
execRun shell commands inside a cloud Linux computer, including background jobs, GUI apps, and commands needing environment variables, and get stdout/stderr back.
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Absolute path to run in. If it does not exist the command does not run, and exit_code is 127. | |
| env | No | 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. | |
| command | Yes | A shell command line. | |
| desktop | No | Run 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_s | No | How 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. | |
| background | No | Return 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_id | No | Which computer. Defaults to the one selected with use_computer. | |
| retain_output | No | Explicit synchronous output retention only. False/absent preserves default behavior. A valid result_id confirms a retained version; optional failure never replays the command. |