Documentation Index
Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
Use this file to discover all available pages before exploring further.
runtime.run_cmd(command=...) accepts either a single shell string or a command + explicit args list:
runtime.run_cmd(command="pip install pandas --quiet")
runtime.run_cmd(command="echo hello; sleep 1; echo world")
runtime.run_cmd(command="pip", args=["install", "pandas", "--quiet"])
runtime.run_cmd(command="ls", args=["-la", "/workspace"])
Basic Usage
from gravixlayer import GravixLayer
client = GravixLayer()
runtime = client.runtime.create(template="python-3.14-base-small")
# Single-string form
result = runtime.run_cmd(command="ls -la /workspace")
print(result.stdout)
print(result.exit_code)
# Equivalent command + args form
result = runtime.run_cmd(command="ls", args=["-la", "/workspace"])
print(result.stdout)
runtime.kill()
Install Packages
from gravixlayer import GravixLayer
client = GravixLayer()
runtime = client.runtime.create(template="python-3.14-base-small")
# Install a Python package — single string form
runtime.run_cmd(command="pip install pandas --quiet")
# Or with command + args (safer for user-supplied package names)
runtime.run_cmd(command="pip", args=["install", "pandas", "--quiet"])
# Verify installation
result = runtime.run_cmd(
command="python",
args=["-c", "import pandas; print(pandas.__version__)"],
)
print(result.stdout)
runtime.kill()
Run Shell Scripts
from gravixlayer import GravixLayer
client = GravixLayer()
runtime = client.runtime.create(template="python-3.14-base-small")
# Single string — chained commands run in one shell invocation
result = runtime.run_cmd(command="echo $HOME && python --version")
print(result.stdout)
# Equivalent with explicit shell invocation
result = runtime.run_cmd(
command="sh",
args=["-lc", "echo $HOME && python --version"],
)
print(result.stdout)
runtime.kill()
With Environment Variables
Set env_vars at runtime creation so variables are available to every run_cmd / run_code call:
from gravixlayer import GravixLayer
client = GravixLayer()
runtime = client.runtime.create(
template="python-3.14-base-small",
env_vars={"APP_MODE": "production"},
)
result = runtime.run_cmd(command="sh", args=["-lc", "echo APP_MODE=$APP_MODE"])
print(result.stdout) # APP_MODE=production
runtime.kill()
Streaming Output
For long-running commands, pass on_stdout / on_stderr / on_exit callbacks to receive output incrementally as the process produces it. The transport switches to Server-Sent Events transparently; the returned CommandRunResponse still carries the aggregated stdout/stderr/exit_code so existing code keeps working.
from gravixlayer import GravixLayer
client = GravixLayer()
runtime = client.runtime.create(template="python-3.14-base-small")
result = runtime.run_cmd(
command="sh -lc 'for i in 1 2 3 4 5; do echo line-$i; sleep 1; done'",
on_stdout=lambda chunk: print(chunk, end="", flush=True),
on_stderr=lambda chunk: print(chunk, end="", flush=True),
on_exit=lambda code: print(f"\n[exit={code}]"),
)
print("final exit code:", result.exit_code)
print("duration:", result.duration_ms, "ms")
runtime.kill()
agent user inside the runtime. sudo is configured for the agent user with NOPASSWD, so commands like sudo apt-get install -y ... work without prompting.
Parameters
| Parameter | Type | Required | Description |
|---|
command | string | Yes | Command to execute. May be a single shell string or a program name. |
args | list[string] | No | Additional arguments appended to command. |
working_dir | string | No | Working directory. |
timeout | integer | No | Timeout in seconds. |
on_stdout | callable(str) | No | Per-chunk stdout callback. Enables streaming mode. |
on_stderr | callable(str) | No | Per-chunk stderr callback. Enables streaming mode. |
on_exit | callable(int) | No | Final exit-code callback. Enables streaming mode. |
Response
| Field | Type | Description |
|---|
stdout | string | Standard output (aggregated when streaming) |
stderr | string | Standard error (aggregated when streaming) |
exit_code | integer | Process exit code |
duration_ms | integer | Execution duration in milliseconds |
success | boolean | True when exit code is 0 |
error | string | API-level error (if any) |
