GravixLayer Python SDK
Official Python client for GravixLayer. Create isolated cloud runtimes, run code and commands in them, build reusable images, and deploy agents.
pip install gravixlayer
export GRAVIXLAYER_API_KEY="your-api-key"
from gravixlayer import GravixLayer
client = GravixLayer()
sandbox = client.runtime.create() # defaults to template="base-small"
result = sandbox.run_code(code="print('Hello from GravixLayer')")
print(result.text)
sandbox.kill()
Cloud and region default to aws / us-east-1. Override with
GRAVIXLAYER_CLOUD / GRAVIXLAYER_REGION, or pass them to the client.
Docs: docs.gravixlayer.ai · Examples: examples/
Configuration
from gravixlayer import GravixLayer
client = GravixLayer(
api_key="your-api-key", # or GRAVIXLAYER_API_KEY
base_url="https://api.gravixlayer.ai",
cloud="aws",
region="us-east-1",
)
| Option | Default | |
|---|---|---|
api_key |
GRAVIXLAYER_API_KEY |
Required. |
base_url |
GRAVIXLAYER_BASE_URL, then https://api.gravixlayer.ai |
|
cloud |
GRAVIXLAYER_CLOUD, then aws |
Runtimes and template builds. |
region |
GRAVIXLAYER_REGION, then us-east-1 |
Runtimes and template builds. |
timeout |
60 |
Per request, in seconds. |
max_retries |
3 |
Transient failures only. |
Construct the client once and reuse it. Call client.warmup() at startup if
you want TCP and TLS paid before the first request that matters. HTTP/1.1 is
the default; pass http2=True for multiplexing under high concurrency.
Runtimes
A sandbox is an isolated virtual machine that boots from a template. It runs until you stop it, or until a timeout you set expires.
sandbox = client.runtime.create(
template="base-small",
env_vars={"APP_ENV": "staging"},
timeout=600,
)
Use a context manager when you want it stopped automatically:
from gravixlayer import Runtime
with Runtime.create(template="base-small") as sandbox:
print(sandbox.run_code("print(2 + 2)").text)
Code and commands
result = sandbox.run_code("print(sum(range(100)))")
print(result.text)
# Pass args when any part comes from user input — nothing in the list is
# interpreted by a shell.
sandbox.run_cmd("python", args=["--version"])
Guest egress is deny-by-default. Installing a package or reaching the internet needs a network policy.
Files
sandbox.file.write("/workspace/note.txt", "hello\n")
text = sandbox.file.read("/workspace/note.txt").content
Also: list, upload, download, write_many, move, copy, find,
replace, watch, delete. See
examples/runtimes/07_file_operations.py.
State, ports, git, SSH
# Interpreter state that survives between run_code calls.
ctx = client.runtime.create_context(sandbox.runtime_id)
client.runtime.run_code(sandbox.runtime_id, "x = 1", context_id=ctx.context_id)
# Publish a guest port on https://*.service.gravixlayer.ai
with sandbox.service(8000) as api:
print(api.web_url)
api.get("/items")
sandbox.git.clone("https://github.com/org/repo.git", "/workspace/repo", depth=1)
ssh = sandbox.enable_ssh()
print(ssh.connect_cmd)
Templates
Build an image once so runtimes start with everything already installed.
Placement follows the client (aws / us-east-1 unless you override it).
from gravixlayer import TemplateBuilder
template = (
TemplateBuilder("data-science", "Pandas and friends")
.from_image("python:3.12-slim")
.vcpu(2)
.memory(2048)
.apt_install("git")
.pip_install("pandas", "matplotlib")
.start_cmd("python -m http.server 8080")
.ready_cmd(TemplateBuilder.wait_for_port(8080), timeout_secs=300)
)
status = client.templates.build_and_wait(template)
sandbox = client.runtime.create(template=status.template_id)
Snapshots
client.snapshots.create(sandbox.runtime_id, "ready-to-work", kind="cold")
restored = client.runtime.create(snapshot="ready-to-work")
A cold snapshot stores the filesystem; a hot snapshot stores memory too, so
the restored sandbox resumes mid-process.
Agents
agent = client.agents.deploy(source="./my-agent", name="my-agent", is_public=True)
reply = client.agents.invoke(agent.agent_id, input={"prompt": "hello"})
Network policies
A sandbox starts fail-closed. Grant access explicitly:
policy = client.network_policies.create(
name="model-access",
egress_mode="allowlist",
rules=[{"destination": "api.example.com", "port": 443, "protocol": "tcp"}],
)
sandbox = client.runtime.create(
template="base-small",
network_policy_ids=[policy.id],
)
Attaching several policies applies the most restrictive of them, so adding one can only narrow access.
Secrets
provider = client.identity.providers.create(
"Model API",
secrets=[{"key": "MODEL_API_KEY", "value": "..."}],
)
sandbox = client.runtime.create(
template="base-small",
providers=[provider.id],
)
Values are write-only. What comes back is masked.
Async
import asyncio
from gravixlayer import AsyncGravixLayer
async def main():
async with AsyncGravixLayer() as client:
sandbox = await client.runtime.create(template="base-small")
result = await client.runtime.run_code(
sandbox.runtime_id, "print('hello')"
)
print(result.stdout_text)
await client.runtime.kill(sandbox.runtime_id)
asyncio.run(main())
Errors
from gravixlayer import GravixLayerError, GravixLayerRateLimitError
try:
client.runtime.create(template="base-small")
except GravixLayerRateLimitError as exc:
print(exc.retry_after_seconds)
except GravixLayerError as exc:
print(exc) # product line, e.g. "CPU quota exceeded. …"
print(exc.status) # 403
print(exc.code) # quota_exceeded
Connection failures and 429 / 502 / 503 / 504 are retried automatically. HTTP 403 (quota or permission) is not retried.
Examples
Runnable scripts for every surface live in examples/. Start with examples/README.md.
Development
pip install -e ".[test]"
pytest tests/unit_tests
See tests/README.md for layout and live integration tests.
Support
License
Apache License 2.0 — see LICENSE. Copyright 2026 Gravix Layer.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file gravixlayer-0.1.96.tar.gz.
File metadata
- Download URL: gravixlayer-0.1.96.tar.gz
- Upload date:
- Size: 351.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7a56239e7940de9785fb6d6a8ca97a64c9b900d0a057626d2de7064f920aece3
|
|
| MD5 |
9d6c6f977a595fb744e9153a6f6fb806
|
|
| BLAKE2b-256 |
d779403633b4f58b6135d10435cc53609901acb753ed0050bd4749cbce5766ee
|
File details
Details for the file gravixlayer-0.1.96-py3-none-any.whl.
File metadata
- Download URL: gravixlayer-0.1.96-py3-none-any.whl
- Upload date:
- Size: 166.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b17dd89c74c035f7a1d4fa2b4e6dafbef8cf47dc300f768ad467a60163d0e4ce
|
|
| MD5 |
a3ba171fa81af1043e0acf898b892364
|
|
| BLAKE2b-256 |
81c2d8cbcec2cf5c5680bb3af895af30267f45f3b7e9a9463e348b1a853b6659
|
