gravixlayer 0.1.45

Gravix Layer Python SDK — agent runtimes and templates (Alpha; API may evolve). See docs.gravixlayer.ai.

Gravix Layer Python SDK

Official Python client for Gravix Layer — create and manage cloud agent runtimes and templates for your workloads.

---

New to this SDK?

Step	Action
1	Install: pip install gravixlayer
2	Set API key: export GRAVIXLAYER_API_KEY="your-api-key" (from the Gravix Layer console)
3	Run the quick start below, or open examples/ for runnable scripts (runtimes, templates)

Docs: docs.gravixlayer.ai · Examples index: examples/README.md

---

Install

pip install gravixlayer

Configure

export GRAVIXLAYER_API_KEY="your-api-key"
export GRAVIXLAYER_CLOUD="azure"       # default
export GRAVIXLAYER_REGION="eastus2"    # default

Or pass options to the client:

from gravixlayer import GravixLayer

client = GravixLayer(
    api_key="your-api-key",
    base_url="https://api.gravixlayer.ai",
    cloud="azure",
    region="eastus2",
)

Quick start

from gravixlayer import GravixLayer

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

result = client.runtime.run_code(
    runtime.runtime_id,
    code="print('Hello from Gravix Layer')",
)
print(result.text)

client.runtime.kill(runtime.runtime_id)

File operations

Use client.runtime.file with short names: read, write (JSON text write), delete, list, upload (multipart bytes), write_many (batch multipart), plus create_directory, get_info, set_permissions. File operations live only under file.* (not on client.runtime directly).

With a Runtime instance, use runtime.file — same methods, without passing runtime_id each time:

runtime = client.runtime.create(template="python-3.14-base-small")
runtime.file.write("/workspace/note.txt", "hello\n")
text = runtime.file.read("/workspace/out.txt").content
client.runtime.kill(runtime.runtime_id)

See examples/runtimes/07_file_operations.py for a full walkthrough.

Examples (runnable)

Area	What you’ll learn
examples/runtimes/	Create runtimes, run code & shell, files, metrics, SSH, context manager, Git — 16 scripts
examples/templates/	Build custom templates (Docker image, Git, Dockerfile) — 6 scripts

Start here: examples/README.md (task table + quick reference).

Performance note (connections and HTTP/2)

The client uses HTTP/1.1 by default for predictable latency on typical API usage.

• Warm the connection before creating many runtimes: call client.warmup() once (or use warmup_on_init=True when constructing the client). That pays TCP, TLS, and protocol setup up front so the first real request is cheaper.
• HTTP/2: pass http2=True to the GravixLayer client constructor if you want multiplexing over a single established connection after TLS (useful for high concurrency). Requires the httpx[http2] extra (already declared by this package).

Sync:

from gravixlayer import GravixLayer

client = GravixLayer(http2=True)
client.warmup()
# or: GravixLayer(http2=True, warmup_on_init=True)

Async: pass http2=True to AsyncGravixLayer and call await client.warmup() before heavy traffic.

from gravixlayer import AsyncGravixLayer

async with AsyncGravixLayer(http2=True) as client:
    await client.warmup()

Async

import asyncio
from gravixlayer import AsyncGravixLayer

async def main():
    async with AsyncGravixLayer() as client:
        runtime = await client.runtime.create(template="python-3.14-base-small")
        await client.runtime.kill(runtime.runtime_id)

asyncio.run(main())

Development

For local development and CI, run the unit tests (HTTP mocked; no API key required):

pip install -e ".[test]"
pytest tests/unit_tests

Test layout (tests/unit_tests vs tests/integration_tests), integration runs, and markers are documented in tests/README.md so this file stays focused on SDK usage.

Documentation and support

• Examples: examples/README.md
• Documentation: docs.gravixlayer.ai
• Issues: GitHub Issues

[e-mail]

Feedback: gravixlayer/gravixlayer-feedback — bugs, features, and product feedback.

License

Apache License 2.0 — see LICENSE.
Copyright 2026 Gravix Layer.