Overview

A runtime is a hardware-isolated sandbox: a dedicated microVM where your application or agent can execute code, run shell commands, and manage files without sharing a kernel with other tenants. Use runtimes for coding agents, data analysis, evaluations, interpreters, and tool hosting.

What you get

Capability	What it does
Code	`run_code` / `runCode` for Python and JavaScript
Commands	`run_cmd` / `runCmd` for shell and package installs
Files	Read, write, list, upload, download (`sandbox.file`)
Git	Clone, commit, push, branch (`sandbox.git`)
Access	SSH and web terminal
Web services	HTTPS URLs for guest HTTP ports on `*.service.gravixlayer.ai` — see Web Services
Secrets	Create secrets under Identity providers; attach them so keys arrive as env vars on execution
Network	Attach Network Policies to allow or deny outbound destinations
Templates	System base images or Templates
Snapshots	Named checkpoints of a running runtime — Snapshots

Why sandboxes

Agents generate code and commands you cannot fully predict. A runtime keeps that work inside an isolated boundary so it does not touch your host credentials or local files. Each runtime has its own CPU, memory, and disk. It stays up until you terminate it (unless you set a timeout).

Client defaults

Install gravixlayer (Python) or gravixlayer (TypeScript). Set GRAVIXLAYER_API_KEY. Cloud and region belong on the client. create() uses the base-small template unless you pass another template or a snapshot.

from gravixlayer import GravixLayer

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

import { GravixLayer } from 'gravixlayer';

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

You can also set GRAVIXLAYER_CLOUD and GRAVIXLAYER_REGION. The SDKs fill cloud and region into the create body from the client, so the REST examples show them explicitly; omit them and the API falls back to the platform default. Only AWS / us-east-1 is available today. Azure and GCP are coming soon — see Multi-Cloud Support.

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"

print(sandbox.run_code(code="print('hello')").text)
print(sandbox.run_cmd(command="python", args=["--version"]).stdout)

sandbox.file.write("/workspace/hello.txt", "hi\n")
print(sandbox.file.read("/workspace/hello.txt").content)

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"

console.log((await sandbox.runCode("print('hello')")).text);
console.log((await sandbox.runCmd('python', { args: ['--version'] })).stdout);

await sandbox.file.write('/workspace/hello.txt', 'hi\n');
console.log((await sandbox.file.read('/workspace/hello.txt')).content);

await sandbox.kill();

# Requires: GRAVIXLAYER_API_KEY, jq
# Defaults: template=base-small, cloud=aws, region=us-east-1

RT=$(gravixlayer runtime create --wait --output json | jq -r '.runtime_id')

echo 'print("hello")' > /tmp/hello.py
gravixlayer runtime run "$RT" /tmp/hello.py

gravixlayer runtime exec "$RT" python --version

gravixlayer runtime files write "$RT" /workspace/hello.txt "hi
"
gravixlayer runtime files cat "$RT" /workspace/hello.txt

gravixlayer runtime kill "$RT" -y

# Requires: GRAVIXLAYER_API_KEY, jq
API="https://api.gravixlayer.ai/v1"
AUTH=(-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json")

RT=$(curl -sS -X POST "$API/agents/runtime" "${AUTH[@]}" \
  -d '{"template":"base-small","cloud":"aws","region":"us-east-1"}' | jq -r '.runtime_id')

for i in $(seq 1 60); do
  STATUS=$(curl -sS "$API/agents/runtime/$RT" -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" | jq -r '.status')
  [ "$STATUS" = "running" ] && break
  sleep 2
done

curl -sS -X POST "$API/agents/runtime/$RT/code/run" "${AUTH[@]}" \
  -d '{"code":"print('\''hello'\'')","language":"python"}'
echo

curl -sS -X POST "$API/agents/runtime/$RT/commands/run" "${AUTH[@]}" \
  -d '{"command":"python","args":["--version"]}'
echo

curl -sS -X POST "$API/agents/runtime/$RT/files/write" "${AUTH[@]}" \
  -d '{"path":"/workspace/hello.txt","content":"hi\n"}'
echo

curl -sS -X POST "$API/agents/runtime/$RT/files/read" "${AUTH[@]}" \
  -d '{"path":"/workspace/hello.txt"}'
echo

curl -sS -X DELETE "$API/agents/runtime/$RT" -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

With secrets

from gravixlayer import GravixLayer

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

provider = client.identity.providers.create(
    name="OpenAI",
    provider_type="api_key",
    secrets=[{"key": "OPENAI_API_KEY", "value": "sk-..."}],
)

sandbox = client.runtime.create(providers=[provider.id])  # defaults to template="base-small"

print(sandbox.run_code(
    code="import os; print('set' if os.environ.get('OPENAI_API_KEY') else 'missing')"
).text)

sandbox.kill()
client.identity.providers.delete(provider.id)

import { GravixLayer } from 'gravixlayer';

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

const provider = await client.identity.providers.create('OpenAI', {
  providerType: 'api_key',
  secrets: [{ key: 'OPENAI_API_KEY', value: 'sk-...' }],
});

const sandbox = await client.runtime.create({ providers: [provider.id] }); // defaults to template="base-small"

console.log(
  (
    await sandbox.runCode(
      "import os; print('set' if os.environ.get('OPENAI_API_KEY') else 'missing')",
    )
  ).text,
);

await sandbox.kill();
await client.identity.providers.delete(provider.id);

# Requires: GRAVIXLAYER_API_KEY, jq

PROVIDER_ID=$(gravixlayer provider create "OpenAI" --type api_key \
  --secret "OPENAI_API_KEY=sk-..." \
  --output json | jq -r '.id // .provider.id')

RT=$(gravixlayer runtime create --provider "$PROVIDER_ID" --wait --output json | jq -r '.runtime_id')

echo 'import os; print("set" if os.environ.get("OPENAI_API_KEY") else "missing")' > /tmp/check_key.py
gravixlayer runtime run "$RT" /tmp/check_key.py

gravixlayer runtime kill "$RT" -y
gravixlayer provider delete "$PROVIDER_ID" -y

# Requires: GRAVIXLAYER_API_KEY, jq
API="https://api.gravixlayer.ai/v1"
AUTH=(-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json")

PROVIDER_ID=$(curl -sS -X POST "$API/identity/providers" "${AUTH[@]}" \
  -d '{
    "name": "OpenAI",
    "provider_type": "api_key",
    "secrets": [{"key": "OPENAI_API_KEY", "value": "sk-..."}]
  }' | jq -r '.id // .provider.id')

RT=$(curl -sS -X POST "$API/agents/runtime" "${AUTH[@]}" \
  -d "{\"template\":\"base-small\",\"cloud\":\"aws\",\"region\":\"us-east-1\",\"providers\":[\"$PROVIDER_ID\"]}" \
  | jq -r '.runtime_id')

for i in $(seq 1 60); do
  STATUS=$(curl -sS "$API/agents/runtime/$RT" -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" | jq -r '.status')
  [ "$STATUS" = "running" ] && break
  sleep 2
done

curl -sS -X POST "$API/agents/runtime/$RT/code/run" "${AUTH[@]}" \
  -d '{"code":"import os; print(\"set\" if os.environ.get(\"OPENAI_API_KEY\") else \"missing\")","language":"python"}'
echo

curl -sS -X DELETE "$API/agents/runtime/$RT" -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
curl -sS -X DELETE "$API/identity/providers/$PROVIDER_ID" -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

See Identity Providers.

Sandbox isolation does not protect against context injection. Prefer host-side tools for high-value credentials; see Security best practices.

Templates

Template	vCPU	Memory	Disk
`base-small`	1	1 GB	4 GB
`base-medium`	2	2 GB	6 GB
`base-large`	4	4 GB	8 GB

See Templates for toolchain details and custom builds.

Lifecycle

Create from a template or a snapshot (optionally attach secrets and network policies).
Execute code and commands; attached secrets inject per execution.
Snapshot (optional) to save a named checkpoint, then start more runtimes from it.
Terminate with sandbox.kill() when finished.

Create Runtime

Parameters and response fields

Web Services

HTTPS URLs for guest HTTP ports

Identity Providers

Inject credentials safely

Network Policies

Control outbound access

Getting Started

Runtime

Support

What you get

Why sandboxes

Client defaults

Basic usage

With secrets

Templates

Lifecycle

Next

Create Runtime

Web Services

Identity Providers

Network Policies

​What you get

​Why sandboxes

​Client defaults

​Basic usage

​With secrets

​Templates

​Lifecycle

​Next

Create Runtime

Web Services

Identity Providers

Network Policies

What you get

Why sandboxes

Client defaults

Basic usage

With secrets

Templates

Lifecycle

Next