---
name: setup-osworld
description: "Provision and verify an OSWorld-V2 checkout after clone. Use when the user asks for OSWorld-V2 setup, installation, onboarding, AWS provider setup, Docker provider setup, mocked website server setup, GitLab server setup, gated task download, or a final runnable export block. The skill should install/configure the selected supported infrastructure where possible, ask for user confirmation or credentials when required, and report what is fully configured versus still blocked."
---

# Setup OSWorld

Use this skill to make a cloned OSWorld-V2 checkout runnable, not merely to
list environment variables. Provision every selected component that can be
configured safely from the current machine, and ask the user whenever an action
requires credentials, paid resources, DNS changes, SSH keys, secrets, or a
destructive/cloud operation.

## Required Version Argument

Require `--version 2` or `--version 2.1` in the skill invocation before any setup
commands, package installation, downloads, checkout changes or provisioning.
There is no default. If missing, ask the user to supply the argument and wait.
Reject unsupported values or conflicting duplicate values; ask for correction.
An explicitly supplied argument earlier in the same setup session remains valid.
Do not infer it from the current checkout, README, or a bare benchmark tag.

These are arguments to this skill's instruction workflow, not a shell command
or new flags for the Python download scripts.

```text
$setup-osworld --version 2.1
$setup-osworld --version 2 --benchmark-release osworld-v2-2026.08.08
$setup-osworld --version 2 --benchmark-release osworld-v2-2026.06.24
```

| Argument | Release selection | Behavior |
| --- | --- | --- |
| `--version 2.1` | `osworld-v2.1` | Use the osworld-v2.1 manifest and references. An optional `--benchmark-release` must equal `osworld-v2.1`. |
| `--version 2` | `osworld-v2-2026.08.08` or `osworld-v2-2026.06.24` | Require `--benchmark-release`; ask and wait if omitted. Use that historical manifest and matching checkout. |

Resolve the selected manifest before proceeding. Reject a version/release
mismatch, `main`, `latest`, or an unsupported release rather than silently
falling back. Preserve user changes when checking out the selected code; use a
separate checkout when necessary. Keep the skill and its references accessible
from the original checkout; resolve runtime code and manifests in the target
checkout. Carry the resolved version and release through
all later steps, including final exports and verification.

## Supported Scope

Supported provider setup:

- `aws`: fully provision required AWS network resources with AWS CLI, then
  export the values OSWorld needs.
- `docker`: install/verify Docker and KVM where possible, then verify the
  Docker provider can run.

Unsupported provider setup for now:

- `vmware`, `virtualbox`, `azure`, `gcp`, `aliyun`, and `volcengine`.

For unsupported providers, load `references/unsupported-providers.md`, state
that this skill does not automate them yet, and ask whether the user wants AWS
or Docker instead.

Optional service setup:

- OSWorld-web mocked website server, using `Task-Web/OSWorld-web`.
- GitLab server, using `Task-Web/gitlab`.
- Gated task class download from Hugging Face.
- Version-pinned task asset download from gated Hugging Face storage.
- Task-scoped proxy setup following upstream OSWorld section 2.3, plus optional
  host-side proxy or HF mirror setup.

## Start With Intake

First satisfy the required version argument above. Then ask before doing
infrastructure work unless the user has already supplied the answers.

Ask for:

- provider: `aws` or `docker`
- whether to use existing AWS resources or create new ones
- AWS region, VPC/subnet preference, and whether AWS charges are acceptable
- whether to set up OSWorld-web, and on existing server or new AWS EC2 host
- website domain mode: existing wildcard domain, `nip.io`, or user-provided
  host suffix
- whether to set up GitLab, and whether it must be a separate server/domain
- whether to download gated tasks and complete assets for the selected release
- whether task-scoped proxy, host-side proxy, or HF mirror is needed
- whether to run real smoke tests that create/start resources

If the user says "do it unattended", still stop for any cloud spend, DNS,
GitHub private-repo authorization, generated secret disclosure, or destructive
operation.

## Versioned References

Use only the column matching the required `--version` argument.

| Reference | osworld-v2.1 | Historical 2.0 releases |
| --- | --- | --- |
| Migration from OSWorld 1.0 | `docs/MIGRATING_v2.1_FROM_OSWORLD_V1.md` | `docs/MIGRATING_FROM_OSWORLD_V1.md` |
| Public evaluation | `docs/PUBLIC_EVALUATION_GUIDELINE_v2.1.md` | `docs/PUBLIC_EVALUATION_GUIDELINE.md` |
| Tasks and assets | `evaluation_examples/task_class/README_v2.1.md` | `references/tasks.md` |
| Websites | `references/website_v2.1.md` | `references/website.md` |

Read the selected release manifest for exact component references. Historical
examples may show a different date or an obsolete hosted suffix: use the selected
historical manifest's tags and verify an existing deployment before adopting it.
Do not edit the preserved historical reference files while executing setup.

## Workflow by Version

1. **Checkout and documentation.**
   - `2.1`: use code tag `osworld-v2.1` and the osworld-v2.1 evaluation/migration guides.
   - `2`: use `osworld_code.tag` from the selected date manifest and the
     historical evaluation/migration guides. Do not run from an osworld-v2.1 checkout.
   - In both cases, use `docs/PROVIDER_SETUP.md` only for shared prerequisites;
     the selected manifest controls release-specific values.
2. **Dependencies.** Read `references/common.md` for tool checks.
   - `2.1`: run `uv sync --frozen`; use `uv sync --frozen --extra full` only
     when the optional stack is needed.
   - `2`: install from the selected historical checkout's lockfile with
     `uv sync --frozen` (and `--extra full` if requested). If that checkout
     cannot support the command, report the actual failure; do not borrow the
     osworld-v2.1 lockfile or silently update dependencies.
3. **Provider.** Load exactly one of `references/provider-aws.md`,
   `references/provider-docker.md`, or `references/unsupported-providers.md`.
   - `2.1`: use the osworld-v2.1 manifest's AMI or Docker artifact and runtime references.
   - `2`: use the selected historical manifest's provider image references.
   - Check actual provider configuration against the selected manifest before
     launch. A common reference's example image must not override the manifest.
4. **Websites.**
   - `2.1`: load `references/website_v2.1.md`; deploy website tag `osworld-v2.1` with
     its pinned submodules, or verify an existing deployment matches it.
   - `2`: load `references/website.md`; use `website_code.tag` from the selected
     historical manifest, including its pinned submodules. Do not reuse an old
     hosted suffix solely because it appears in an example.
5. **GitLab and proxy.** Read `references/gitlab.md` and/or `references/proxy.md`
   only when requested. These service procedures are shared; configure them for
   the tasks and website host of the selected release.
6. **Tasks and assets.**
   - `2.1`: load `evaluation_examples/task_class/README_v2.1.md`; both downloaders receive
     `--benchmark-release osworld-v2.1`. Use the full gated asset snapshot; the public
     asset repository is not its replacement.
   - `2`: load `references/tasks.md`; available downloaders receive the explicitly
     selected date release, replacing generic or differently dated examples.
     `v2026.06.24` does not contain `download_osworld_v2_assets.py`. For that
     checkout, use `uv run python` with `huggingface_hub.snapshot_download`:
     read `assets.repository`, `assets.repo_type` and `assets.tag` from the
     selected historical manifest and pass them as `repo_id`, `repo_type` and
     `revision`, with `local_dir` set to a fresh complete asset directory.
     Require gated access, download the full snapshot without allow/ignore
     filters, and export its absolute path as `OSWORLD_FILE_BASE_URL`. Do not
     copy a newer downloader into the historical checkout or fall back to main.
   - Never download floating `main` content or mix task and asset releases.
7. **Verification.** Load `references/verify.md`. For either version, verify code,
   website, tasks, assets and provider references against its manifest, check the
   expected task count, and run only the authorized smoke tests. Use the task
   hash source specified by that manifest: osworld-v2.1 keeps the regenerated list in
   this code repository; historical releases retain their recorded sources.
8. **Final outputs.** Report the selected `--version`, exact benchmark release,
   component refs and actual verification results. Export
   `OSWORLD_BENCHMARK_RELEASE` as `osworld-v2.1` or the selected date release, respectively,
   alongside `OSWORLD_FILE_BASE_URL` and the chosen website suffix. Put secret
   exports in a chmod 600 local file. Report configured, skipped and blocked
   components separately; never imply that a different version was tested.

## Operating Rules

- Use `uv`, `uvx`, and `uv run python`; do not rely on bare `python` or `pip`.
- Prefer existing repo docs and current provider code over memory.
- Do not stop at "set this variable"; if the user selected a supported setup,
  create or verify the backing resource that makes the variable valid.
- Use AWS CLI for AWS resources. Do not hand-wave AWS console steps unless the
  user chose manual setup.
- Use Docker Compose for OSWorld-web and GitLab exactly as their READMEs
  describe, with `HOST_SUFFIX`, `GITLAB_URL`, and `GITLAB_PRIVATE_TOKEN`
  backed by reachable services.
- Keep model/API-key setup separate from provider/runtime setup unless the user
  asks to run an agent or evaluator.
- Never commit secrets, `.env` files, generated private keys, or setup export
  files.
- If an external private repository is inaccessible, report the exact blocker
  and ask the user to authorize GitHub access instead of inventing commands.
- At the end, be explicit: "configured and verified", "configured but not
  smoke-tested", "not configured", or "blocked awaiting user action".