Agent environments

Use the Ona CLI to create, manage, and run commands in environments from external AI agents such as Claude Code, Cursor, or custom scripts. This guide covers the full lifecycle: discover resources, create an environment, execute commands, and clean up.

Prerequisites

Ona CLI installed
Authenticated via ona login
At least one runner available in your organization

Discover projects

List projects to find one to create an environment from:

ona project list

Use -o json for machine-readable output:

ona project list -o json

Discover environment classes

Environment classes define the compute resources (CPU, memory) for your environment. List available classes:

ona environment list-classes

Filter by runner:

ona environment list-classes --runner <runner-id>

Create an environment

From a project

The simplest way. The project already has a repository URL, environment class, and configuration:

ona environment create <project-id>

From a context URL

Create directly from a repository URL. Requires an environment class:

ona environment create <repo-url> --class-id <class-id>

Both creation methods support --inactivity-timeout to set a custom auto-stop timeout. See auto-stop timeout for details and examples.

Non-blocking creation

Use --dont-wait to return the environment ID immediately without waiting for it to start:

ENV_ID=$(ona environment create <project-id> --dont-wait)

Then poll for readiness:

ona environment get "$ENV_ID" -o json

List environments

ona environment list

Filter to JSON for parsing:

ona environment list -o json

Run commands

Execute commands inside a running environment using exec:

ona environment exec <environment-id> -- <command>

The command runs inside the environment’s dev container via the EnvironmentOps API (not SSH). The CLI waits for the command to complete and prints stdout/stderr.

Examples

# Run a build
ona environment exec <environment-id> -- make build

# Run tests with a longer timeout
ona environment exec <environment-id> --timeout 300 -- npm test

# Run in a specific directory
ona environment exec <environment-id> --working-dir /workspace/myproject -- cargo test

# Get structured output for parsing
ona environment exec <environment-id> -o json -- echo hello

Exit codes

The CLI exits with the same exit code as the remote command. A non-zero exit code means the command failed.

Flags

Flag	Default	Description
`--timeout`	`120`	Command timeout in seconds
`--working-dir`	workspace folder	Working directory inside the environment
`-o json`	table	Output format (json, yaml, table)

SSH access

For interactive sessions or when you need a persistent shell:

ona environment ssh <environment-id>

Run a single command over SSH:

ona environment ssh <environment-id> -- ls -la

See the CLI reference for SSH setup details.

Clean up

Stop an environment to preserve its state:

ona environment stop <environment-id>

Delete an environment permanently:

ona environment delete <environment-id>

Full workflow example

End-to-end script that creates an environment, runs a command, and cleans up:

#!/bin/bash
set -euo pipefail

# Create environment from a project, wait for it to start
ENV_ID=$(ona environment create <project-id> --dont-wait)
echo "Created environment: $ENV_ID"

# Wait for the environment to be running
ona environment start "$ENV_ID"

# Run commands
ona environment exec "$ENV_ID" -- npm install
ona environment exec "$ENV_ID" --timeout 300 -- npm test

# Clean up
ona environment delete "$ENV_ID"
echo "Done"

JSON workflow for agents

Agents that parse structured output can use -o json throughout:

# Create and capture the environment ID (--dont-wait prints the ID directly)
ENV_ID=$(ona environment create <project-id> --dont-wait)

# Check status
STATUS=$(ona environment get "$ENV_ID" -o json | jq -r '.[0].phase')

# Run a command and parse the result
RESULT=$(ona environment exec "$ENV_ID" -o json -- echo hello)
EXIT_CODE=$(echo "$RESULT" | jq -r '.[0].exit_code')
STDOUT=$(echo "$RESULT" | jq -r '.[0].stdout')

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Using environments from external agents

Prerequisites

Discover projects

Discover environment classes

Create an environment

From a project

From a context URL

Non-blocking creation

List environments

Run commands

Examples

Exit codes

Flags

SSH access

Clean up

Full workflow example

JSON workflow for agents

​Prerequisites

​Discover projects

​Discover environment classes

​Create an environment

​From a project

​From a context URL

​Non-blocking creation

​List environments

​Run commands

​Examples

​Exit codes

​Flags

​SSH access

​Clean up

​Full workflow example

​JSON workflow for agents

Prerequisites

Discover projects

Discover environment classes

Create an environment

From a project

From a context URL

Non-blocking creation

List environments

Run commands

Examples

Exit codes

Flags

SSH access

Clean up

Full workflow example

JSON workflow for agents