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.
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
Discover projects
List projects to find one to create an environment from:
Use -o json for machine-readable output:
Discover environment classes
Environment classes define the compute resources (CPU, memory) for your environment. List available classes:
ona environment list-classes
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>
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)
ona environment get "$ENV_ID" -o json
List environments
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>
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>
ona environment ssh <environment-id> -- ls -la
Clean up
Stop an environment to preserve its state:
ona environment stop <environment-id>
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')
