env_exec
Run shell commands or scripts inside a running virtual machine and retrieve their output and exit codes. Use it to configure, inspect, or directly modify the guest environment.
Instructions
Run a shell command inside an environment and return its exit code and output. The command is one shell string: pipes, redirects, globs and quoting are interpreted by the guest shell, unlike the CLI's terrarium exec, which passes its arguments literally. Which shell that is: /bin/sh on Linux guests; on a Windows guest, the shell recorded for its golden, which is PowerShell for a golden terrarium built and cmd.exe for an older or adopted one, unless terrarium adopt --shell said otherwise. Pass shell (powershell, cmd or sh) to run under a different one, and script instead of command for anything multi-line or heavily quoted - a script reaches the shell on stdin, so nothing in it is re-parsed on the way. The environment must be running. Commands run as a user with passwordless sudo, so this can change or destroy anything inside the guest - the host is not affected. A command that outruns timeout_sec is killed in the guest, with its child processes, and the error says what was killed: nothing is left running where you cannot see it. On a Windows guest an ordinary command runs in session 0, which has no screen: if it opens a window or a dialog it waits there forever and env_screenshot shows nothing. Set desktop to run it in the session a user is logged into instead, where env_screenshot can see what it wants. Only works when the environment's golden has SSH credentials; without them, use env_screenshot, env_type, env_keys and env_click.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | name of the environment to run in | |
| shell | No | run under this shell instead of the guest's own: powershell, cmd or sh | |
| script | No | multi-line script to run instead of command; it reaches the shell on stdin so nothing in it is quoted or split | |
| command | No | shell command to run in the guest; omit when passing script | |
| desktop | No | Windows guests only: run in the session a user is logged into, so env_screenshot shows the window or dialog the command opens. Without it a command runs in session 0, which has no screen | |
| timeout_sec | No | seconds to wait before giving up (default 300) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| output | Yes | ||
| exit_code | Yes |