Run Command

POST /v1/agents/runtime/{runtime_id}/commands/run run_cmd / runCmd accepts either a single shell string or a command plus an explicit args list:

sandbox.run_cmd(command="echo hello; sleep 1; echo world")
sandbox.run_cmd(command="ls", args=["-la", "/workspace"])

await sandbox.runCmd('echo hello; sleep 1; echo world');
await sandbox.runCmd('ls', { args: ['-la', '/workspace'] });

# A string with ; or spaces must go through a shell. The CLI always sends argv.
gravixlayer runtime exec "$RT" -- bash -lc 'echo hello; sleep 1; echo world'

# Same call as command + args
gravixlayer runtime exec "$RT" -- ls -la /workspace

CLI timeout is in seconds (--timeout 300). The REST API timeout field is in milliseconds (300000). The Python SDK takes seconds and converts for you.

Basic Usage

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"

# Single-string form
result = sandbox.run_cmd(command="ls -la /workspace")
print(result.stdout)
print(result.exit_code)

# Equivalent command + args form
result = sandbox.run_cmd(command="ls", args=["-la", "/workspace"])
print(result.stdout)

sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"

// Single-string form
const listed = await sandbox.runCmd('ls -la /workspace');
console.log(listed.stdout);
console.log(listed.exitCode);

const viaArgs = await sandbox.runCmd('ls', { args: ['-la', '/workspace'] });
console.log(viaArgs.stdout);

await sandbox.kill();

# Requires: GRAVIXLAYER_API_KEY, RT (running runtime id)
gravixlayer runtime exec "$RT" --workdir /workspace --timeout 300 -- ls -la /workspace

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/commands/run" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls",
    "args": ["-la", "/workspace"],
    "working_dir": "/workspace",
    "timeout": 300000
  }'

Install Packages

Guest egress is deny-by-default, so pip install needs a network policy. The example uses allow_all for a short demo; prefer an allowlist for PyPI in production.

import uuid

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"

policy = client.network_policies.create(
    name=f"pypi-{uuid.uuid4().hex[:8]}",
    egress_mode="allow_all",
    description="Temporary egress for pip",
)
sandbox = client.runtime.create(network_policy_ids=[policy.id])  # defaults to template="base-small"

sandbox.run_cmd(command="pip", args=["install", "pandas", "--quiet"])

result = sandbox.run_cmd(
    command="python",
    args=["-c", "import pandas; print(pandas.__version__)"],
)
print(result.stdout)

sandbox.kill()
client.network_policies.delete(policy.id)

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"

const policy = await client.networkPolicies.create(`pypi-${Date.now()}`, {
  egressMode: 'allow_all',
  description: 'Temporary egress for pip',
});
const sandbox = await client.runtime.create({ networkPolicyIds: [policy.id] }); // defaults to template="base-small"

await sandbox.runCmd('pip', { args: ['install', 'pandas', '--quiet'] });

const result = await sandbox.runCmd('python', {
  args: ['-c', 'import pandas; print(pandas.__version__)'],
});
console.log(result.stdout);

await sandbox.kill();
await client.networkPolicies.delete(policy.id);

gravixlayer runtime exec "$RT" -- pip install pandas --quiet
gravixlayer runtime exec "$RT" -- python -c 'import pandas; print(pandas.__version__)'

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/commands/run" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "pip",
    "args": ["install", "pandas", "--quiet"]
  }'

Run Shell Scripts

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"

# Single string — chained commands run in one shell invocation
result = sandbox.run_cmd(command="echo $HOME && python --version")
print(result.stdout)

# Equivalent with explicit shell invocation
result = sandbox.run_cmd(
    command="sh",
    args=["-lc", "echo $HOME && python --version"],
)
print(result.stdout)

sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"

// Single string — chained commands run in one shell invocation
const chained = await sandbox.runCmd('echo $HOME && python --version');
console.log(chained.stdout);

const viaShell = await sandbox.runCmd('sh', { args: ['-lc', 'echo $HOME && python --version'] });
console.log(viaShell.stdout);

await sandbox.kill();

gravixlayer runtime exec "$RT" -- sh -lc 'echo $HOME && python --version'

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/commands/run" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "sh",
    "args": ["-lc", "echo $HOME && python --version"]
  }'

With Environment Variables

Set env_vars at runtime creation so variables are available to every run_cmd / run_code call, or pass them per command:

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create(env_vars={"APP_MODE": "production"})  # defaults to template="base-small"

result = sandbox.run_cmd(command="sh", args=["-lc", "echo APP_MODE=$APP_MODE"])
print(result.stdout)  # APP_MODE=production

# Per-command environment (client API — not on the bound handle)
result = client.runtime.run_cmd(
    sandbox.runtime_id,
    command="sh",
    args=["-lc", "echo $FOO"],
    environment={"FOO": "bar"},
)
print(result.stdout)

sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create({ envVars: { APP_MODE: 'production' } }); // defaults to template="base-small"

const result = await sandbox.runCmd('sh', { args: ['-lc', 'echo APP_MODE=$APP_MODE'] });
console.log(result.stdout); // APP_MODE=production

const perCommand = await sandbox.runCmd('sh', {
  args: ['-lc', 'echo $FOO'],
  environment: { FOO: 'bar' },
});
console.log(perCommand.stdout);

await sandbox.kill();

gravixlayer runtime exec "$RT" -e FOO=bar -- echo "$FOO"

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/commands/run" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "sh",
    "args": ["-lc", "echo $FOO"],
    "environment": {"FOO": "bar"}
  }'

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()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"

result = sandbox.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")
sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"

const result = await sandbox.runCmd(
  "sh -lc 'for i in 1 2 3 4 5; do echo line-$i; sleep 1; done'",
  {
    onStdout: (chunk) => process.stdout.write(chunk),
    onStderr: (chunk) => process.stderr.write(chunk),
    onExit: (code) => console.log(`\n[exit=${code}]`),
  },
);

console.log('final exit code:', result.exitCode);
console.log('duration:', result.durationMs, 'ms');
await sandbox.kill();

gravixlayer runtime exec "$RT" --stream -- sh -lc 'for i in 1 2 3 4 5; do echo line-$i; sleep 1; done'

curl -N -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/commands/run?stream=true" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "sh",
    "args": ["-lc", "for i in 1 2 3 4 5; do echo line-$i; sleep 1; done"]
  }'

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.

Background commands

background: true starts the command and returns HTTP 201 as soon as it is running. The process keeps running after the request ends. Follow it with the pid from that response. If the program cannot be started, the response is HTTP 200 with the same body as a finished command, and there is no pid. The SDK still returns a handle: pid is null, and wait, refresh, and kill return that result without another request. An unknown pid is HTTP 404, and so is the pid of a terminal session, which has its own routes. On a runtime whose template was built before background commands were available, background: true is HTTP 501. Rebuild the template to use it. background: true together with ?stream=true is rejected. Attach to a running command with GET .../commands/{pid}/stream. A deadline is optional. Omit timeout (or send 0) and a foreground command is stopped after 300 seconds, while a background command has no deadline. A positive timeout is milliseconds on the REST API and seconds in the SDKs. When the deadline is reached the command exits 124 and timed_out is true. A command that is still running when a template snapshot is taken is part of that snapshot unless the template defines a start command that replaces it.

handle = sandbox.run_cmd(command="python -m http.server 8080", background=True)
print(handle.pid)
finished = handle.wait()
print(finished.exit_code, finished.timed_out)
handle.kill()  # or sandbox.command.kill(handle.pid, signal="TERM")

const handle = await sandbox.runCmd('python -m http.server 8080', { background: true });
console.log(handle.pid);
const finished = await handle.wait();
console.log(finished.exitCode, finished.timedOut);
await handle.kill();

gravixlayer runtime exec "$RT" --background --timeout 0 -- python -m http.server 8080

curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/commands/run" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"python","args":["-m","http.server","8080"],"background":true}'

Method	Path	Result
GET	`/v1/agents/runtime/{runtime_id}/commands`	Running and recently finished commands
GET	`/v1/agents/runtime/{runtime_id}/commands/{pid}`	One command
GET	`/v1/agents/runtime/{runtime_id}/commands/{pid}/stream`	Live output until the command exits
DELETE	`/v1/agents/runtime/{runtime_id}/commands/{pid}?signal=KILL`	Stop the command. `signal` may be `KILL` (the default), `TERM`, `INT`, or `HUP`. Any other value is HTTP 400. A command that has already exited returns its final state

A live stream is text/event-stream. Each event is one JSON object, and every stream ends with exactly one end or error event:

`type`	Fields
`start`	`pid`
`stdout`	`data`
`stderr`	`data`
`ping`	Sent about every 15 seconds while the command is still running
`end`	`exit_code`, `duration_ms`, `timed_out`, and `error` when the command could not complete normally
`error`	`message`. The stream broke before the command finished

Closing a foreground stream stops its command. Closing a stream that follows a background command leaves the command running. After an error event, a background command may still be running, so wait() raises and you can attach again. A runtime runs up to 100 commands at once; beyond that, starting another is HTTP 429. Finished commands stay attachable for 10 minutes, and the 32 most recent exits remain listed until then. Output callbacks passed with background follow the command in the background. If following stops early, because the stream breaks or a callback raises, on_error / onError receives the error and handle.error keeps it. The command keeps running, so you can call wait() to attach again. Stopping with handle.disconnect() is not an error.

Exit code	Meaning
`0`	The command finished successfully
`124`	The deadline killed the command (`timed_out` is true)
`126`	The file exists but is not executable
`127`	The command was not found
`128` + signal number	The command died from a signal. `137` is `KILL`, `143` is `TERM`

A non-zero exit is a normal 200 response. It is not an API error.

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. Default `/workspace`.
`timeout`	integer	No	Deadline. Seconds in the Python SDK and CLI, milliseconds on the REST API. Omitted or `0`: 300 seconds for a foreground command, no deadline for a background command.
`environment`	object	No	Per-command environment variables.
`background`	boolean	No	Return as soon as the command is running. Default `false`.
`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.
`on_error`	callable(Exception)	No	With `background`, called if following the output fails. The command keeps running.

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
`timed_out`	boolean	`True` when the deadline killed the command
`error`	string	API-level error (if any)

Getting Started

Runtime

Support

Basic Usage

Install Packages

Run Shell Scripts

With Environment Variables

Streaming Output

Background commands

Parameters

Response

​Basic Usage

​Install Packages

​Run Shell Scripts

​With Environment Variables

​Streaming Output

​Background commands

​Parameters

​Response

Basic Usage

Install Packages

Run Shell Scripts

With Environment Variables

Streaming Output

Background commands

Parameters

Response