Skip to main content
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()
All user code (including streamed commands) executes as the unprivileged 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

ParameterTypeRequiredDescription
commandstringYesCommand to execute. May be a single shell string or a program name.
argslist[string]NoAdditional arguments appended to command.
working_dirstringNoWorking directory.
timeoutintegerNoTimeout in seconds.
on_stdoutcallable(str)NoPer-chunk stdout callback. Enables streaming mode.
on_stderrcallable(str)NoPer-chunk stderr callback. Enables streaming mode.
on_exitcallable(int)NoFinal exit-code callback. Enables streaming mode.

​
Response

FieldTypeDescription
stdoutstringStandard output (aggregated when streaming)
stderrstringStandard error (aggregated when streaming)
exit_codeintegerProcess exit code
duration_msintegerExecution duration in milliseconds
successbooleanTrue when exit code is 0
errorstringAPI-level error (if any)