From ona-dev-environment
Spin up, manage, and connect to remote containerized dev environments on Ona (formerly Gitpod) via Personal Access Token (PAT). Use when the user asks to create, start, stop, list, retrieve, or delete an Ona / Gitpod cloud dev environment from a Git repository or Project, mentions "Ona environment", "spin up Ona", "Ona PAT", "remote dev container on Ona", "cloud devcontainer", "launch a workspace from a repo URL", wants to manage Ona prebuilds for fast environment startup, set up an idle-env cleanup task, or programmatically open a containerized cloud workspace from Cowork. Do NOT use for GitHub Codespaces, local Docker / Compose, local VS Code Dev Containers, Coder, JetBrains Space, or k8s dev clusters — those are different platforms with different APIs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ona-dev-environment:ona-dev-environmentThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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 scri...
examples/create-from-github.mdexamples/prebuild-cycle.mdreferences/api-reference.mdreferences/pat-setup.mdscripts/cleanup_idle_envs.pyscripts/create_environment.pyscripts/create_from_project.pyscripts/create_prebuild.pyscripts/delete_environment.pyscripts/get_environment.pyscripts/list_classes.pyscripts/list_environments.pyscripts/list_prebuilds.pyscripts/list_projects.pyscripts/ona_client.pyscripts/start_environment.pyscripts/stop_environment.pyscripts/whoami.pyProgrammatically 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.
export ONA_TOKEN=<token> (Linux/macOS) or setx ONA_TOKEN "<token>" (Windows PowerShell).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.
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.
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.
Run scripts from the skill directory. All scripts are pure Python 3 stdlib (no pip install required) and read ONA_TOKEN from the environment.
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.
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.
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.
python scripts/list_classes.py
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.
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:
ONA_TOKEN is set in the user environment so the scheduled task inherits it.python <skill-path>/scripts/cleanup_idle_envs.py weekly.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.python scripts/create_environment.py \
https://github.com/owner/repo \
--branch feature/payments-v2 \
--port 3000:Web \
--port 5432:Postgres
ENV_ID=$(python scripts/create_environment.py https://github.com/owner/repo --no-wait)
python scripts/delete_environment.py "$ENV_ID" --force
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.
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_PHASE_STARTING for >5 min. Inspect status.failureMessage in get_environment.py output — usually a devcontainer.json build failure.disconnected validation error. Allowed values: 0s (disabled) or >= 1800s. 1–1799 s is rejected.(projectId, environmentClass, ref) exactly match the create call's coordinates and that it's in PHASE_AVAILABLE. Stale prebuilds expire after about an hour.--dry-run first. Activity signal updates only every 5 minutes, so freshly-created envs may still appear idle for a few minutes.ONA_TOKEN.cleanup_idle_envs.py cleanup script is destructive — always run --dry-run first when changing thresholds.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.
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub dobeu-tech-eco/ona-dev-environment --plugin ona-dev-environment