> ## 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.

# Overview

> How Gravix Layer runtimes work — isolated sandboxes for code, shell, files, and secrets

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.

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#EEF2FF','primaryTextColor':'#1E1B4B','primaryBorderColor':'#5B4CDB','lineColor':'#6366F1','secondaryColor':'#ECFDF5','secondaryBorderColor':'#00AD69','tertiaryColor':'#F5F3FF'}}}%%
flowchart TB
  subgraph App["Your application / Agent"]
    SDK[Gravix Layer SDK / API]
  end

  SDK -->|create · run_code · run_cmd| RT

  subgraph RT["Runtime sandbox"]
    FS[Filesystem]
    PY[Python / JS]
    SH[Shell]
    GIT[Git]
  end

  SP[Identity providers] -.->|attach| RT
```

## What you get

| Capability    | What it does                                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Code**      | `run_code` for Python and JavaScript                                                                                   |
| **Commands**  | `run_cmd` for shell and package installs                                                                               |
| **Files**     | Read, write, list, upload, download                                                                                    |
| **Git**       | Clone, commit, push, branch                                                                                            |
| **Access**    | SSH and web terminal                                                                                                   |
| **Secrets**   | Attach [Identity providers](/documentation/agentruntime/getting-started/secrets); keys arrive as env vars on execution |
| **Templates** | Base images or [custom templates](/documentation/agentruntime/templates)                                               |

## 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).

## Basic usage

```python theme={null}
from gravixlayer import GravixLayer

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

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

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

runtime.kill()
```

## With secrets

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

runtime = client.runtime.create(
    template="python-3.14-base-small",
    providers=[provider.id],
)

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

runtime.kill()
client.identity.providers.delete(provider.id)
```

See [Secrets](/documentation/agentruntime/getting-started/secrets).

## Templates

| Template                  | vCPU | Memory | Disk |
| ------------------------- | ---- | ------ | ---- |
| `python-3.14-base-small`  | 1    | 1 GB   | 2 GB |
| `python-3.14-base-medium` | 1    | 2 GB   | 4 GB |
| `python-3.14-base-large`  | 2    | 4 GB   | 8 GB |

## Lifecycle

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#EEF2FF','primaryTextColor':'#1E1B4B','primaryBorderColor':'#5B4CDB','lineColor':'#6366F1','actorBkg':'#EEF2FF','actorBorder':'#5B4CDB','actorTextColor':'#1E1B4B','signalColor':'#6366F1','signalTextColor':'#1E1B4B'}}}%%
sequenceDiagram
  participant App as Your application / Agent
  participant API as Gravix Layer
  participant RT as Runtime sandbox

  App->>API: runtime.create
  API->>RT: boot microVM (~50ms)
  App->>RT: run_code / run_cmd / files
  App->>API: runtime.kill
  API->>RT: tear down
```

1. **Create** from a template (optionally attach Identity providers).
2. **Execute** code and commands; attached secrets inject per execution.
3. **Terminate** with `runtime.kill()` when finished.

## Next

<CardGroup cols={3}>
  <Card title="Create Runtime" icon="play" href="/documentation/agentruntime/sandbox-management/create-sandbox">
    Parameters and response fields
  </Card>

  <Card title="Quickstart" icon="rocket" href="/documentation/agentruntime/getting-started/quickstart">
    First sandbox end to end
  </Card>

  <Card title="Secrets" icon="key" href="/documentation/agentruntime/getting-started/secrets">
    Inject credentials safely
  </Card>
</CardGroup>