ona-dev-environment

Ona Dev Environment

Programmatically create and manage Ona (formerly Gitpod) cloud dev environments from Cowork using a Personal Access Token. Each environment is a containerized workspace defined by devcontainer.json, started from a Git repository URL, and reachable via VS Code in the browser, SSH, or any local IDE. The skill also exposes Project- and Prebuild-based fast-start workflows and an idle-cleanup script suitable for a recurring scheduled task.

Quick start

1. Create a PAT at https://app.ona.com/settings/personal-access-tokens (Read & Write).
2. Set the env var: export ONA_TOKEN=<token> (Linux/macOS) or setx ONA_TOKEN "<token>" (Windows PowerShell).
3. Spin up an environment from a repo URL:

python scripts/create_environment.py https://github.com/owner/repo

The script prints the environment ID, polls until ENVIRONMENT_PHASE_RUNNING, then emits the editor URL, SSH URL, and exposed port URLs.

Authentication

The Ona API uses bearer-token auth over HTTPS. The PAT belongs to one user account and inherits that user's permissions; access level (read-only vs. read & write) is fixed at creation time.

Where	Value
Header	Authorization: Bearer $ONA_TOKEN
Env var	ONA_TOKEN
Override host	ONA_HOST (defaults to https://app.gitpod.io; app.ona.com also works)
Storage	Never commit a PAT. Use OS keychain, env file outside git, or CI secret.
Rotation	30 / 60 / 90-day expirations supported. Revoke unused tokens.

If ONA_TOKEN is missing, every script in scripts/ exits with a clear error pointing to the PAT settings page. Never paste a PAT into the chat — set it in the shell before invoking the skill, or store it via OS-level secret tooling. See references/pat-setup.md for the full walkthrough.

API surface

All operations hit the Connect-RPC endpoint at https://app.gitpod.io/api/<service>/<method> with Content-Type: application/json and a JSON body.

Operation	Service.Method	Script
Verify token	IdentityService/GetAuthenticatedIdentity	scripts/whoami.py
List machine classes	EnvironmentService/ListEnvironmentClasses	scripts/list_classes.py
Create environment (repo URL)	EnvironmentService/CreateEnvironment	scripts/create_environment.py
Create environment (project)	EnvironmentService/CreateEnvironmentFromProject	scripts/create_from_project.py
Get environment	EnvironmentService/GetEnvironment	scripts/get_environment.py
List environments	EnvironmentService/ListEnvironments	scripts/list_environments.py
Start environment	EnvironmentService/StartEnvironment	scripts/start_environment.py
Stop environment	EnvironmentService/StopEnvironment	scripts/stop_environment.py
Delete environment	EnvironmentService/DeleteEnvironment	scripts/delete_environment.py
List projects	ProjectService/ListProjects	scripts/list_projects.py
Create prebuild	PrebuildService/CreatePrebuild	scripts/create_prebuild.py
List prebuilds	PrebuildService/ListPrebuilds	scripts/list_prebuilds.py
Idle-env cleanup (composite)	ListEnvironments + Stop / Delete	scripts/cleanup_idle_envs.py

Full request and response schemas live in references/api-reference.md.

Operations

Run scripts from the skill directory. All scripts are pure Python 3 stdlib (no pip install required) and read ONA_TOKEN from the environment.

Create an environment from a repo URL

python scripts/create_environment.py <git-repo-url> \
  [--class-id <env-class-id>] \
  [--branch <name>] \
  [--port 3000] [--port 8080:Web] \
  [--timeout 7200s] \
  [--name "my-env"] \
  [--no-wait]

Defaults: picks the first available environment class via ListEnvironmentClasses if --class-id is omitted, clones the repo's default branch, exposes no extra ports, uses Ona's default disconnect timeout. With --no-wait, the script returns the env ID immediately; otherwise it polls every 5 s until the env reaches ENVIRONMENT_PHASE_RUNNING or fails.

Create an environment from a Project (repeat-use)

When the same repo + devcontainer + class is created again and again, define a Project once at https://app.ona.com/projects, then:

python scripts/list_projects.py
python scripts/create_from_project.py <project-id> [--name NAME] [--no-wait]

This is the recommended pattern for team workspaces and PR-review envs because it pairs naturally with prebuilds.

Inspect, start, stop, delete

python scripts/list_environments.py                     # all envs the token can see
python scripts/get_environment.py <env-id>              # full status JSON + URLs
python scripts/start_environment.py <env-id>            # resume a stopped env
python scripts/stop_environment.py <env-id>             # stop without deleting
python scripts/delete_environment.py <env-id> --force   # destroy permanently

delete_environment.py requires --force to skip the interactive yes confirmation.

List available machine classes

python scripts/list_classes.py

Prebuilds (fast environment startup)

Prebuilds are pre-warmed environment snapshots. With one available, CreateEnvironment skips the devcontainer build phase and starts in ~10 s instead of ~80 s.

python scripts/create_prebuild.py <project-id> <class-id> [--ref main]
python scripts/list_prebuilds.py [--project-id ID] [--class-id ID]

Trigger a prebuild on every push to main from CI; see examples/prebuild-cycle.md for a GitHub Actions snippet.

Cleanup of idle environments

Walks every environment, finds any RUNNING env whose last activity signal is older than --idle-hours (default 24), and stops or deletes it.

# Preview what would happen — safe, no API writes
python scripts/cleanup_idle_envs.py --dry-run

# Stop everything idle >24 h (default)
python scripts/cleanup_idle_envs.py

# Aggressive: delete envs idle >72 h
python scripts/cleanup_idle_envs.py --idle-hours 72 --action delete

Wire it as a Cowork scheduled task to run weekly:

1. Ensure ONA_TOKEN is set in the user environment so the scheduled task inherits it.
2. From Cowork, create a scheduled task that runs python <skill-path>/scripts/cleanup_idle_envs.py weekly.
3. Or call the mcp__scheduled-tasks__create_scheduled_task tool with a prompt like "Run python <skill-path>/scripts/cleanup_idle_envs.py and report what was stopped" on a weekly schedule.

Common workflows

Open a PR's branch in a fresh environment

python scripts/create_environment.py \
  https://github.com/owner/repo \
  --branch feature/payments-v2 \
  --port 3000:Web \
  --port 5432:Postgres

Spin up a temporary environment, run a script, tear down

ENV_ID=$(python scripts/create_environment.py https://github.com/owner/repo --no-wait)
python scripts/delete_environment.py "$ENV_ID" --force

Reuse a PAT across multiple Cowork sessions

Add ONA_TOKEN=… to the user's shell profile (~/.bashrc, ~/.zshrc, or PowerShell $PROFILE). The skill picks it up automatically every time. Never bake the PAT into a script file inside this skill folder.

Common pitfalls

• UNAUTHENTICATED 401. Token expired, was revoked, or env var is empty. Re-issue at https://app.ona.com/settings/personal-access-tokens.
• PERMISSION_DENIED 403 on create. PAT was created with read-only access. Create a Read & Write token.
• ListEnvironmentClasses returns an empty array. The user's organization has no runners attached. Pick a class ID by hand from the Ona web UI and pass --class-id.
• Environment stuck in ENVIRONMENT_PHASE_STARTING for >5 min. Inspect status.failureMessage in get_environment.py output — usually a devcontainer.json build failure.
• Timeout disconnected validation error. Allowed values: 0s (disabled) or >= 1800s. 1–1799 s is rejected.
• Prebuild not picked up. Confirm the prebuild's (projectId, environmentClass, ref) exactly match the create call's coordinates and that it's in PHASE_AVAILABLE. Stale prebuilds expire after about an hour.
• Cleanup task deletes envs you wanted. Run --dry-run first. Activity signal updates only every 5 minutes, so freshly-created envs may still appear idle for a few minutes.

Security

• The PAT grants the same access as the user account. Treat it as a password.
• The skill never writes the token to disk. Scripts only read it from ONA_TOKEN.
• Audit logs at https://app.ona.com record every API call by token ID.
• Revoke leaked tokens immediately at https://app.ona.com/settings/personal-access-tokens.
• The cleanup_idle_envs.py cleanup script is destructive — always run --dry-run first when changing thresholds.

Reference

• references/api-reference.md — every endpoint, request body, response shape, and curl equivalent.
• references/pat-setup.md — PAT creation walkthrough and storage options.
• examples/create-from-github.md — annotated end-to-end run from a GitHub repo.
• examples/prebuild-cycle.md — prebuild → fast-start workflow with CI snippet.
• scripts/ona_client.py — shared HTTP client (also exposes find_ona_cli / run_ona_cli helpers when the local ona binary is on PATH).
• install.ps1 — one-shot Windows installer that copies the skill into the Cowork skills folder. Re-run with -Force to upgrade or -Uninstall to remove.

Official docs: https://ona.com/docs/api-reference and https://ona.com/docs/ona/integrations/personal-access-token.