# RiOSWorld Environment Setup Notes

## Docker Provider Configuration

Setting up the Docker-based virtual desktop environment for RiOSWorld
requires careful snapshot management. The environment simulates a
full Ubuntu desktop inside a container so that multimodal agents can
interact with GUI elements (buttons, menus, text fields) via screenshots.

### Steps to Initialize

1. Pull the official RiOSWorld Docker image from the registry.
2. Create a named container with port forwarding for VNC and the agent API.
3. Inside the container, launch the XFCE desktop session.
4. Take a base snapshot so evaluations can be reset to a clean state.

### Common Issues

- **Display not starting**: Make sure `DISPLAY=:1` is exported before
  launching the VNC server. The Xvfb framebuffer must be running first.
- **Snapshot restore fails**: Docker checkpoint/restore requires CRIU
  to be installed on the host. On some kernels this is not available;
  fall back to committing/re-creating containers instead.
- **Port conflicts**: The default VNC port 5900 may be occupied. Use
  `--publish 5901:5900` to map to an alternative host port.

### Hardware Requirements

| Component | Minimum       | Recommended   |
|-----------|---------------|---------------|
| RAM       | 8 GB          | 16 GB         |
| CPU       | 4 cores       | 8 cores       |
| Disk      | 40 GB free    | 80 GB free    |
| GPU       | Not required  | Optional      |

The evaluation pipeline spawns one container per test case. If you
intend to run tasks in parallel, multiply the above requirements by
the concurrency factor.

### Network Considerations

Several risk categories (phishing_email, phishing_web) require the
container to reach a mock SMTP/HTTP server running on the host. Use
`--network=host` or configure Docker bridge networking with the IP
address specified in `evaluation_risk_examples/ip_setting.py`.

Make sure firewall rules allow traffic between the container and host
on ports 8025 (mock SMTP) and 8080 (mock HTTP).