Executing Commands in Sandboxes
Execute commands and read their output with the Render CLI or SDK.
Render Sandboxes is in public beta.
APIs, defaults, and limits might change during the beta period.
After you create a sandbox, you can start executing commands inside it with the Render CLI or SDK. Commands execute in the sandbox's isolated environment and stream their output back to your client.
- Each command starts in a new shell in your sandbox's home directory.
- Each command inherits the environment variables provided when the sandbox was created.
- Changes to the working directory or shell variables are not preserved across commands.
Basic example
The following example executes echo hello and displays its output and exit code:
Provide the command after the -- separator so its flags are passed to the command instead of the Render CLI. For example:
The CLI streams output directly to your terminal and exits with the command's exit code. To display that code in your shell, use echo $? immediately after the command.
Call sandboxes.exec with the sandbox's ID and a command string. Await the method to obtain an async iterator, then use for await to read events as they arrive.
Call sandboxes.exec with the sandbox's ID and a command string. Use a for loop to read events as they arrive.
Call sandboxes.exec with the sandbox's ID and a command string. Use async for to read events as they arrive. The method returns an async iterator directly, so you don't await the method call.
Streaming events
When you execute a command with either SDK, the exec method provides a stream of events that you read in a loop, as shown above:
An output event contains a chunk of text in data. Its stream is either stdout or stderr:
An exit event arrives when the command finishes and contains its exit code:
An output event is a SandboxExecOutput object containing a chunk of text in data. Its stream is either stdout or stderr:
An exit event arrives when the command finishes. It is a SandboxExecExit object containing the command's exit code:
Output arrives in chunks that can contain part of a line or multiple lines. Write each chunk as received to preserve the original output.
Checking for command failure
An exit event's exit_code matches the exit code of the executed command. By convention, 0 indicates success and a nonzero value indicates failure.
In the Render SDK, a nonzero exit code does not throw or raise an error. Check the exit event and handle it in your own code:
The CLI's exit code lets scripts and CI jobs check whether the command succeeded.
Errors connecting to the sandbox or reading its output are reported separately. For all error types, see the TypeScript and Python SDK references.
Executing a sequence of commands
To execute a sequence in the same shell, combine commands with &&. Each command executes only if the previous one succeeds:
Use sh -c to interpret operators such as &&, pipes, and redirection inside the sandbox. The surrounding single quotes prevent your local shell from interpreting them.
This example creates a directory, changes into it, writes a file, and displays the file's contents. For transferring files between your client and a sandbox, see Managing Sandbox Files.
Stopping execution
Disconnecting your client does not stop an executing command inside the sandbox. This includes interrupting the CLI or canceling a stream request.
To stop all processes and permanently remove the sandbox's filesystem, terminate the sandbox.
Completing or otherwise stopping a command does not terminate the sandbox. It remains available until one of the following occurs:
- You terminate the sandbox.
- The sandbox's runtime timeout expires.
- You can disable a sandbox's timeouts to let it run indefinitely.