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

# Runner infrastructure

> Runners provision and manage your environments and agents. Deploy in your own AWS or GCP account.

Runners are the infrastructure layer that provisions and manages your [environments](https://ona.com/docs/ona/environments/overview.md) and [agents](https://ona.com/docs/ona/agents/codex.md). Every environment you launch and every agent task you run executes on a runner.

## What a runner handles

A runner handles everything that touches your code:

* **Environment provisioning:** creates isolated VMs from your [Dev Container](https://ona.com/docs/ona/configuration/devcontainer/overview.md) configuration
* **Source code access:** clones repositories using credentials stored on the runner, not the management plane
* **Secret injection:** delivers [secrets](https://ona.com/docs/ona/configuration/secrets/overview.md) into environments at startup
* **Agent execution:** runs [Codex Agent](https://ona.com/docs/ona/agents/codex.md) tasks inside the same isolated environments developers use
* **Build and test execution:** runs [prebuilds](https://ona.com/docs/ona/projects/prebuilds.md), [tasks, and services](https://ona.com/docs/ona/configuration/tasks-and-services/overview.md) defined in your project

## How runners fit into the architecture

Ona uses a two-plane architecture:

| | Management Plane | Runners |
| - | - | - |
| **Hosted by** | Ona | Your VPC |
| **Handles** | Authentication, org settings, guardrails, coordination | Environment provisioning, code access, secret injection, agent execution |
| **Touches your code** | No | Yes |

The management plane coordinates. Runners execute. This separation exists for three reasons:

1. **Data sovereignty.** Source code and SCM credentials stay on runners, not the management plane. With a runner in your VPC, sensitive assets never leave your infrastructure.
2. **Compliance.** [Guardrails](https://ona.com/docs/ona/guardrails/overview.md) are defined on the management plane and enforced at the runner level. [Audit logs](https://ona.com/docs/ona/audit-logs/overview.md) track every action.
3. **Multi-region, multi-cloud.** Deploy runners in different regions and cloud providers. Each runner supports multiple environment classes with different compute specs.

For a deeper look at data flow between planes, see the [Architecture overview](https://ona.com/docs/ona/understanding/architecture.md).

## Deployment options

### AWS

> [!NOTE]
>
> Available on the Enterprise plan. [Contact sales](https://ona.com/contact/sales) to learn more.

Deploy runners as ECS services in your own AWS VPC. Environments run as EC2 instances. Deployment is automated via CloudFormation templates.

* Private networking with AWS PrivateLink
* Custom domains with your own SSL/TLS certificates
* Fine-grained IAM permission boundaries
* HTTP proxy and custom CA support

Setup takes 30-60 minutes. See [AWS Runner overview](https://ona.com/docs/ona/runners/aws/overview.md) and [Setup guide](https://ona.com/docs/ona/runners/aws/setup.md).

### GCP

> [!NOTE]
>
> Available on the Enterprise plan. [Contact sales](https://ona.com/contact/sales) to learn more.

Deploy runners in your Google Cloud VPC. Environments run as Compute Engine instances. Deployment is automated via Terraform modules.

* External or internal load balancer configurations
* Private Google Artifact Registry access
* Full control over networking and security

Setup takes 30-60 minutes. See [GCP Runner overview](https://ona.com/docs/ona/runners/gcp/overview.md) and [Setup guide](https://ona.com/docs/ona/runners/gcp/setup.md).

## Choosing a deployment option

| | AWS / GCP (your VPC) |
| - | - |
| **Setup time** | 30-60 minutes |
| **Infrastructure** | Managed by you |
| **Data residency** | Your VPC |
| **Network control** | Full (PrivateLink, internal LB, VPN) |
| **Compliance** | Your controls + Ona guardrails |
| **Best for** | Enterprise, regulated industries |

Organizations can run multiple runners across regions and cloud providers to support distributed teams and compliance requirements.

## Capabilities across all deployment options

All runners support these features regardless of where they run:

* [Prebuilds](https://ona.com/docs/ona/projects/prebuilds.md) for fast environment startup
* [Codex Agent](https://ona.com/docs/ona/agents/codex.md) for agent-driven development
* Environment classes with configurable compute (CPU, memory, storage)
* [Dual disk environments](https://ona.com/docs/ona/runners/dual-disk.md) for resilient Enterprise environment storage
* Dev Container caching for faster rebuilds
* [Custom metrics pipeline](https://ona.com/docs/ona/runners/monitoring-and-metrics.md) for operational visibility
* Runner sharing across organizations

## Next steps

* [AWS Setup](https://ona.com/docs/ona/runners/aws/setup.md): deploy a runner in your AWS account
* [GCP Setup](https://ona.com/docs/ona/runners/gcp/setup.md): deploy a runner in your GCP project
* [Architecture overview](https://ona.com/docs/ona/understanding/architecture.md): how the management plane and runners interact
* [Capacity planning](https://ona.com/docs/ona/runners/aws/capacity-planning.md): plan infrastructure requirements for runners in your VPC


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.