> ## 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.

# Using environments from external agents

> Manage Ona environments from external AI agents like Claude Code or Cursor using the Ona CLI.

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](/ona/integrations/cli)
* Authenticated via `ona login`
* At least one [runner](/ona/runners/ona-cloud) available in your organization

## Discover projects

List projects to find one to create an environment from:

```bash theme={null}
ona project list
```

Use `-o json` for machine-readable output:

```bash theme={null}
ona project list -o json
```

## Discover environment classes

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

```bash theme={null}
ona environment list-classes
```

Filter by runner:

```bash theme={null}
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:

```bash theme={null}
ona environment create <project-id>
```

### From a context URL

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

```bash theme={null}
ona environment create <repo-url> --class-id <class-id>
```

Both creation methods support `--inactivity-timeout` to set a custom auto-stop timeout. See [environment timeout](/ona/organizations/policies/environment-timeout) for details and examples.

### Non-blocking creation

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

```bash theme={null}
ENV_ID=$(ona environment create <project-id> --dont-wait)
```

Then poll for readiness:

```bash theme={null}
ona environment get "$ENV_ID" -o json
```

## List environments

```bash theme={null}
ona environment list
```

Filter to JSON for parsing:

```bash theme={null}
ona environment list -o json
```

## Run commands

Execute commands inside a running environment using `exec`:

```bash theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
ona environment ssh <environment-id>
```

Run a single command over SSH:

```bash theme={null}
ona environment ssh <environment-id> -- ls -la
```

See the [CLI reference](/ona/reference/cli) for SSH setup details.

## Clean up

Stop an environment to preserve its state:

```bash theme={null}
ona environment stop <environment-id>
```

Delete an environment permanently:

```bash theme={null}
ona environment delete <environment-id>
```

## Full workflow example

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

```bash theme={null}
#!/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:

```bash theme={null}
# 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')
```