How a runtime works

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. The Overview is the short start. This page is the model behind that call: what is inside a runtime, how long it stays up, and which defaults you can leave alone.

Create a runtime over HTTPS. Secrets and a network policy attach to that same microVM.

1Your sideApplication or agentGravix Layer SDK or the REST API

createrun_coderun_cmd

HTTPS

2RuntimeDedicated microVMNo shared kernel. Torn down on kill.

filesystempython · jsshellgit

Attached to the runtime

SecretsEnvironment variablesInjected on each execution

Network policyAllowlist or denylistWhat the runtime may reach

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. AWS us-east-1 (Virginia) and ap-south-1 (Mumbai) are 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')

gravixlayer runtime run "$RT" --code 'print("hello")'
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

Attach an Identity provider when you create the runtime. The next runtime run or runtime exec receives those keys as environment variables. An interactive shell does not.

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

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

gravixlayer runtime run "$RT" --code 'import os; print("set" if os.environ.get("OPENAI_API_KEY") else "missing")'

Create, attach, detach, and the security rules are on Identity Providers.

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

Templates

create() uses base-small unless you pass another template or a snapshot. Sizes and the toolchain are on Templates.

Lifecycle

Create a runtime, run work in it, snapshot if you want to reuse it, then terminate it.

1CreateFrom a template or a snapshot

2ExecuteCode, commands, and files

3SnapshotOptional named checkpoint

4TerminateKill it. Billing stops.

appsandbox = client.runtime.create()

oksandbox ready · ~25 ms · sbx_7f3a

appsandbox.run_code(code="print(2 + 2)")4

appsandbox.run_cmd(command="pip", args=["install", "pandas"])exit 0

appclient.snapshots.create(runtime_id=sandbox.runtime_id, name="deps")snap_a91c

appsandbox.kill()

oktorn down · billed 12.4 s

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