SDK Usage

Create and manage runtimes (sandboxes) with the Gravix Layer Python or TypeScript SDK, the CLI, or the REST API.

Install

pip install gravixlayer

npm install gravixlayer

Authenticate

Create an API key in the console, then set it in your environment:

export GRAVIXLAYER_API_KEY="your-api-key"

Or pass it when constructing the client:

from gravixlayer import GravixLayer

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

import { GravixLayer } from 'gravixlayer';

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

Create the key in the Quickstart. It is shown once.

Cloud, region, and template

The SDK places runtimes on AWS / us-east-1 and uses the base-small template. Set cloud and region on the client, not on runtime.create().

from gravixlayer import GravixLayer

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

sandbox = client.runtime.create()  # defaults to template="base-small"
# sandbox = client.runtime.create(template="base-medium")

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' });

const sandbox = await client.runtime.create(); // defaults to template="base-small"
// const sandbox = await client.runtime.create({ template: 'base-medium' });

Environment overrides: GRAVIXLAYER_CLOUD and GRAVIXLAYER_REGION. AWS us-east-1 (Virginia) and ap-south-1 (Mumbai) are available today; Azure and GCP are coming soon. The REST API still sends cloud and region in the create body. The SDKs fill those fields from the client so your application code stays small.

Create and run a sandbox

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.runtime_id, sandbox.status)

result = sandbox.run_code(code="print(2 + 2)")
print(result.text)  # 4

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(sandbox.runtimeId, sandbox.status);

const result = await sandbox.runCode('print(2 + 2)');
console.log(result.text); // 4

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 "$RT"

# Inline code — or pass a local script path instead of --code
gravixlayer runtime run "$RT" --code 'print(2 + 2)'

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(2 + 2)","language":"python"}'
echo

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

More create options: Create Runtime.

Run code

Every run_code / runCode call returns structured output (text, success, and optional error details).

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
print(result.success)  # True

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
console.log(result.success); // true

await sandbox.kill();

# Requires: GRAVIXLAYER_API_KEY, jq

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

printf 'import math\nprint(math.sqrt(81))\n' > /tmp/sqrt.py
gravixlayer runtime run "$RT" /tmp/sqrt.py

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":"import math\nprint(math.sqrt(81))","language":"python"}'
echo

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

JavaScript and persistent contexts: Run Code.

Run commands

Use run_cmd / runCmd for shell commands. Pass a single string, or a command plus args.

from gravixlayer import GravixLayer

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

out = sandbox.run_cmd(command="ls -la /workspace")
print(out.stdout)
print(out.exit_code)

out = sandbox.run_cmd(command="python", args=["--version"])
print(out.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"

let out = await sandbox.runCmd('ls -la /workspace');
console.log(out.stdout);
console.log(out.exitCode);

out = await sandbox.runCmd('python', { args: ['--version'] });
console.log(out.stdout);

await sandbox.kill();

# Requires: GRAVIXLAYER_API_KEY, jq

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

gravixlayer runtime exec "$RT" ls -la /workspace
gravixlayer runtime exec "$RT" python --version

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/commands/run" "${AUTH[@]}" \
  -d '{"command":"ls -la /workspace"}'
echo

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

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

Install packages and scripts: Run Command.

Read and write files

Use sandbox.file (not files).

from gravixlayer import GravixLayer

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

sandbox.file.write("/workspace/hello.txt", "Hello from Gravix Layer\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"

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

await sandbox.kill();

# Requires: GRAVIXLAYER_API_KEY, jq

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

gravixlayer runtime files write "$RT" /workspace/hello.txt "Hello from Gravix Layer
"
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/files/write" "${AUTH[@]}" \
  -d '{"path":"/workspace/hello.txt","content":"Hello from Gravix Layer\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"

Full file API: Write File, Read File.

List and clean up

from gravixlayer import GravixLayer

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

for sandbox in client.runtime.list(limit=10).runtimes:
    print(sandbox.runtime_id, sandbox.status)

sandbox = client.runtime.create()  # defaults to template="base-small"
sandbox.kill()

import { GravixLayer } from 'gravixlayer';

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

const page = await client.runtime.list({ limit: 10 });
for (const sandbox of page.runtimes) {
  console.log(sandbox.runtimeId, sandbox.status);
}

const sandbox = await client.runtime.create(); // defaults to template="base-small"
await sandbox.kill();

gravixlayer runtime list --limit 10 --output json | jq .

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

# Requires: GRAVIXLAYER_API_KEY, jq
API="https://api.gravixlayer.ai/v1"

curl -sS "$API/agents/runtime?limit=10" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

RT=$(curl -sS -X POST "$API/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"base-small","cloud":"aws","region":"us-east-1"}' | jq -r '.runtime_id')

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

Language notes

	Python	TypeScript
Client	`GravixLayer()` — defaults to `cloud="aws"`, `region="us-east-1"`	`new GravixLayer()` — same defaults
Placement	`GravixLayer(cloud="aws", region="us-east-1")`	`new GravixLayer({ cloud: 'aws', region: 'us-east-1' })`
Resource	`client.runtime`	`client.runtime`
Files	`sandbox.file`	`sandbox.file`
Create	`client.runtime.create()` — defaults to `template="base-small"`	`await client.runtime.create()` — same default
Run code	`sandbox.run_code(code="...")`	`await sandbox.runCode('...')`
Run cmd	`sandbox.run_cmd(command="...")`	`await sandbox.runCmd('...')`
Id	`sandbox.runtime_id`	`sandbox.runtimeId`
Network policies	`client.network_policies`	`client.networkPolicies`
Identity	`client.identity.providers`	`client.identity.providers`

Always call kill() when you are finished.

What’s next

Quickstart

Secrets, network policies, and a fuller walkthrough

CLI Usage

Install the CLI and manage sandboxes from your terminal

Snapshots

Checkpoint a runtime and create more from it

Templates

Base sizes and custom template builds

How a runtime works

Lifecycle, defaults, and what is inside a sandbox

Getting Started

Runtime

Support

Install

Authenticate

Cloud, region, and template

Create and run a sandbox

Run code

Run commands

Read and write files

List and clean up

Language notes

What’s next

Quickstart

CLI Usage

Snapshots

Templates

How a runtime works

​Install

​Authenticate

​Cloud, region, and template

​Create and run a sandbox

​Run code

​Run commands

​Read and write files

​List and clean up

​Language notes

​What’s next

Quickstart

CLI Usage

Snapshots

Templates

How a runtime works

Install

Authenticate

Cloud, region, and template

Create and run a sandbox

Run code

Run commands

Read and write files

List and clean up

Language notes

What’s next