> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Usage

> Install the Python SDK, authenticate, and manage sandboxes programmatically

Create and manage runtimes (sandboxes) with the Gravix Layer Python SDK.

## Install

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install gravixlayer
```

## Authenticate

Create an API key in the [console](https://app.gravixlayer.ai), then set it in your environment:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export GRAVIXLAYER_API_KEY="your-api-key"
```

Or pass it when constructing the client:

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from gravixlayer import GravixLayer

client = GravixLayer(api_key="your-api-key")
```

See [API Keys](/documentation/agentruntime/getting-started/api-keys) for details.

## Create and run a sandbox

A **runtime** is an isolated sandbox. Create one, run code, then terminate it.

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from gravixlayer import GravixLayer

# Uses GRAVIXLAYER_API_KEY from the environment
client = GravixLayer()

runtime = client.runtime.create(template="base-small")
print(runtime.runtime_id, runtime.status)

# Run Python inside the sandbox
result = runtime.run_code(code="print(2 + 2)")
print(result.text)  # 4

runtime.kill()
```

More create options: [Create Runtime](/documentation/agentruntime/sandbox-management/create-sandbox).

## Run code

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(template="base-small")

result = runtime.run_code(code="import math\nprint(math.sqrt(81))")
print(result.text)     # 9.0
print(result.success)  # True

runtime.kill()
```

JavaScript and persistent contexts: [Run Code](/documentation/agentruntime/code-execution/run-python).

## Run commands

Use `run_cmd` for shell commands. Pass a single string, or `command` + `args`.

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(template="base-small")

# Single string
out = runtime.run_cmd(command="ls -la /workspace")
print(out.stdout)
print(out.exit_code)

# command + args (safer for dynamic values)
out = runtime.run_cmd(command="python", args=["--version"])
print(out.stdout)

runtime.kill()
```

Install packages and scripts: [Run Command](/documentation/agentruntime/command-execution/run-command).

## Read and write files

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(template="base-small")

runtime.file.write("/workspace/hello.txt", "Hello from Gravix Layer\n")
print(runtime.file.read("/workspace/hello.txt").content)

runtime.kill()
```

Full file API: [Write File](/documentation/agentruntime/file-operations/write-file), [Read File](/documentation/agentruntime/file-operations/read-file).

## List and clean up

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from gravixlayer import GravixLayer

client = GravixLayer()

# List running sandboxes
for r in client.runtime.list(limit=10).runtimes:
    print(r.runtime_id, r.status)

# Always terminate when finished
runtime = client.runtime.create(template="base-small")
runtime.kill()
```

## What’s next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/documentation/agentruntime/getting-started/quickstart">
    Secrets, network policies, and a fuller walkthrough
  </Card>

  <Card title="CLI Usage" icon="terminal" href="/documentation/agentruntime/cli-usage">
    Install the CLI and manage sandboxes from your terminal
  </Card>

  <Card title="Templates" icon="box" href="/documentation/agentruntime/templates">
    Base sizes and custom template builds
  </Card>

  <Card title="Runtime overview" icon="server" href="/documentation/agentruntime/overview">
    What a runtime sandbox can do
  </Card>
</CardGroup>