Documentation Reference

API Reference

Complete method signatures for the Python SDK, REST management API, and webhook event schema.

Python SDK

Install with pip install runta-sdk. All objects are importable from the top-level runta module.

Policy

Represents a compiled governance policy loaded from YAML or constructed in code.

Policy class
class Policy:
  # Load from YAML file
  @classmethod
  def from_yaml(cls, path: str) -> Policy: ...
 
  # Build programmatically
  def __init__(
    self,
    memory_mb: int = 512,
    cpu_seconds: int = 30,
    egress_allow: list[str] = (),
    audit_retention_days: int = 90,
  ) -> None: ...

sandbox()

Context manager that wraps an agent invocation in an enforced sandbox. On exit the audit log is committed and the sandbox is torn down.

sandbox()
def sandbox(
  policy: Policy,
  run_id: str | None = None,
  labels: dict[str, str] = {},
) -> SandboxContext: ...
 
# Usage:
with runta.sandbox(policy=policy, labels={"env": "prod"}) as sb:
  result = agent.run(...)

AuditLog

Returned by sb.audit_log() after the sandbox exits. All entries are hash-chained and verifiable.

AuditLog class
class AuditLog:
  run_id: str
  egress_blocked: int
  quota_events: int
  tool_calls: int
  output_tokens: int
 
  def summary(self) -> dict: ...
  def export_jsonl(self, path: str) -> None: ...
  def verify_chain(self) -> bool: ...

REST Management API

Base URL: https://api.runtahq.com/v1. All requests require an Authorization: Bearer <api_key> header.

Runs

MethodPathDescription
GET/runsList runs with optional filter by label or date range
GET/runs/{id}Retrieve a single run record including audit log URL
DELETE/runs/{id}Revoke a run's stored audit log after retention period

Policies

MethodPathDescription
GET/policiesList all saved policy versions in the workspace
POST/policiesUpload a new policy YAML, returns a policy_id
GET/policies/{id}Retrieve a specific policy version

Webhook events

Runta emits signed webhook payloads for key sandbox lifecycle events. Verify with the X-Runta-Signature header using your webhook secret.

  • sandbox.started - run_id, policy_id, labels, timestamp
  • egress.blocked - run_id, destination, rule, timestamp
  • quota.exceeded - run_id, resource, limit, actual, timestamp
  • sandbox.completed - run_id, duration_ms, tool_calls, audit_log_url

Need something not covered here?

Runta supports custom policy extensions and SIEM integrations. Contact the engineering team.

Contact us Back to quickstart