Basic Execution
POST /v1/agents/runtime/{runtime_id}/code/run
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_code(code="import math\nprint(math.sqrt(81))")
print(result.text) # 9.0
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.runCode('import math\nprint(math.sqrt(81))');
console.log(result.text); // 9.0
await sandbox.kill();
cat > /tmp/sqrt.py <<'EOF'
import math
print(math.sqrt(81))
EOF
gravixlayer runtime run "$RT" /tmp/sqrt.py --timeout 300
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/code/run" \
-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "import math\nprint(math.sqrt(81))",
"language": "python",
"timeout": 300
}' | jq .
Error Handling
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_code(code="raise ValueError('example')")
if not result.success and result.error:
print(result.error.name) # ValueError
print(result.error.value) # example
print(result.error.traceback) # Full traceback
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.runCode("raise ValueError('example')");
if (!result.success && result.error && typeof result.error !== 'string') {
console.log(result.error.name); // ValueError
console.log(result.error.value); // example
console.log(result.error.traceback); // Full traceback
}
await sandbox.kill();
cat > /tmp/raise.py <<'EOF'
raise ValueError("example")
EOF
gravixlayer runtime run "$RT" /tmp/raise.py --timeout 300 --output json | jq .
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/code/run" \
-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "raise ValueError('\''example'\'')",
"language": "python",
"timeout": 300
}' | jq .
With Code Context
Preserve variables across multiplerun_code calls:
gravixlayer runtime run does not accept --context-id. Create contexts with code-context, then run with context via Python or cURL.from gravixlayer import GravixLayer
client = GravixLayer() # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create() # defaults to template="base-small"
ctx = client.runtime.create_context(sandbox.runtime_id)
client.runtime.run_code(sandbox.runtime_id, code="x = 42", context_id=ctx.context_id)
result = client.runtime.run_code(sandbox.runtime_id, code="print(x + 1)", context_id=ctx.context_id)
print(result.text) # 43
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 ctx = await sandbox.createContext();
await sandbox.runCode('x = 42', { contextId: ctx.contextId });
const result = await sandbox.runCode('print(x + 1)', { contextId: ctx.contextId });
console.log(result.text); // 43
await sandbox.kill();
CTX=$(gravixlayer runtime code-context create "$RT" --language python --output json | jq -r '.context_id')
echo "$CTX"
# Context-bound runs: use Python or cURL with context_id (no --context-id on runtime run).
CTX=$(curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/code/contexts" \
-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"language": "python"}' | jq -r '.id // .context_id')
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/code/run" \
-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"code\": \"x = 42\", \"language\": \"python\", \"context_id\": \"$CTX\"}" | jq .
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/code/run" \
-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"code\": \"print(x + 1)\", \"language\": \"python\", \"context_id\": \"$CTX\"}" | jq .
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Python source code to execute |
language | string | No | "python" (default) or "javascript" |
context_id | string | No | Reuse a persistent code context |
environment | object | No | Per-execution environment variables |
timeout | integer | No | Execution timeout in seconds |
Response
| Field | Type | Description |
|---|---|---|
text | string | Combined stdout output |
success | boolean | True if no execution error |
error | object | Error details (name, value, traceback) |
results | list | Structured execution results |
logs | object | stdout and stderr as lists of strings |