Proxy Guideline =============== OSWorld provides multiple proxy configuration options for users who need to access the internet through proxy servers, whether behind the 🇨🇳 `GFW `_ or for other network requirements. Quick Setup with DataImpulse (Recommended) ------------------------------------------- For users who prefer a ready-to-use proxy solution, we recommend using our pre-configured DataImpulse proxy infrastructure: 2.2 Proxy Setup ~~~~~~~~~~~~~~~~ 1. **Register at DataImpulse** Visit `DataImpulse `_ and create an account. 2. **Purchase a US Residential IP Package** Purchase a US residential IP package (approximately $1 per 1GB). DataImpulse offers pay-as-you-go pricing with no expiration dates. 3. **Configure Your Credentials** Configure your credentials in ``OSWorld/evaluation_examples/settings/proxy/dataimpulse.json``: .. code-block:: json [ { "host": "gw.dataimpulse.com", "port": 823, "username": "your_username", "password": "your_password", "protocol": "http", "provider": "dataimpulse", "type": "residential", "country": "US", "note": "Dataimpulse Residential Proxy" } ] 4. **Enable Proxy in OSWorld** We have set proxy to ``True`` in the config JSON files for those proxy-sensitive tasks. OSWorld will automatically wrap these tasks with a proxy when ``DesktopEnv``'s ``enable_proxy=True``, while other tasks will not be affected. We recommend using a proxy. If you don't need proxy at all, please set ``enable_proxy=False`` in the experiment's .py file: .. code-block:: python env = DesktopEnv( ... enable_proxy=False, ... ) .. note:: For detailed information about the DesktopEnv interface, please refer to :doc:`../user_guides/environment_explanation`. .. warning:: Disabling the proxy will cause some tasks under the Chrome domain to fail. Manual Proxy Configuration --------------------------- If you prefer to configure your own proxy server, you can follow the steps below. 1. Configure Your Proxy on the Host Machine ------------------------------------------- By default, proxy software usually listens only to the local loopback address (`127.0.0.1`), which cannot be reached from other machine (including the virtual machine). Hence, firstly make your local proxy software listen to the IP address of the VMWare network card, or simply `0.0.0.0` for all the IP addresses. The VMWare network card are usually named `vmnetX` like `vmnet8`. Make sure to use the IP address within the identical network segment. For example, `192.168.108.1/24` and `192.268.108.130/24` are within the same network segment, *i.e.*, the same subnet mask (24) and the same prefix (`192.168.108`, 24-bit length). Usually, different VM instances share the same network segment, and so, the effective host IPs are the same. After launching the VM, you can use .. code-block:: sh # run this command on host # change ws to fusion if you use VMWare Fusion vmrun -T ws getGuestIPAddress /path/to/vmx/file to get the IP of the VM. As for host IPs, on Ubuntu (Linux) machine, you can use `ip a` command to check the IP addresses of each network card. On Windows machine, you can use `ipconfig` command to check the IP addresses of each network card. Recognize the correct IP and note it for later use. Then you should configure the listening address of your proxy software: .. image:: /_static/assets/proxysetup.png If you cannot change the listening address of your proxy software, you can set up port forwarding. Suppose your proxy software is listening to 1080 port of localhost (`127.0.0.1`), and the effective host IP address is `192.168.108.1`. On Ubuntu (Linux), you can use `socat` to forward `192.168.108.1:1080` to `127.0.0.1:1080`: .. code-block:: sh socat TCP-LISTEN:1080,bind=192.168.108.1,fork TCP:127.0.0.1:1080 On Windows, if you have administrative privilege, you can simply run the following command in a `cmd` window with admin privilege. .. code-block:: dosbatch netsh interface portproxy add v4tov4 listenaddress=192.168.108.1 listenport=1080 connectaddress=127.0.0.1 connectport=1080 Or if you haven't got administrative privilege, you can use `ncat` bundled in `Nmap `__ to forward the port: .. code-block:: dosbatch ncat -k -l 192.168.108.1 1080 --sh-exec 'ncat 127.0.0.1 1080' 2. Configure in the VM Machine ------------------------------ For the Ubuntu Image ~~~~~~~~~~~~~~~~~~~~ Configuration by GUI ^^^^^^^^^^^^^^^^^^^^ Open system network setting in the VM. .. image:: /_static/assets/netsetting1.png .. image:: /_static/assets/netsetting3.png Then, click on "Network Proxy". .. image:: /_static/assets/netsetting4.png Set an appropriate proxy mode. Usually, use "Manual" mode, and set the correct IP addresses and ports. The IP address should be the host machine IP noted in the previous step. Then you can open a chrome page to check if the proxy works well. Configuration by Command Line ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If configuration by GUI is not suitable for you, you can instead execute the following commands in the VM to configure proxy on the Ubuntu image: .. code-block:: sh # run these command in the VM gsettings set org.gnome.system.proxy mode 'manual' gsettings set org.gnome.system.proxy.http host 'xxx.xxx.xxx.xxx' gsettings set org.gnome.system.proxy.http port xxxx gsettings set org.gnome.system.proxy.https host 'xxx.xxx.xxx.xxx' gsettings set org.gnome.system.proxy.https port xxxx gsettings set org.gnome.system.proxy.socks host 'xxx.xxx.xxx.xxx' gsettings set org.gnome.system.proxy.socks port xxxx If there isn't a physical or virtual screen available for you to direct operate on the VM, you can run these commands with the help of `vmrun`. For instance, .. code-block:: sh # run this command on host # change ws to fusion if you use VMWare Fusion vmrun -T ws runProgramInGuest /path/to/vmx/file /usr/bin/gsettings set org.gnome.system.proxy mode 'manual' For Window Image ~~~~~~~~~~~~~~~~ Configuration by GUI ^^^^^^^^^^^^^^^^^^^^ Open system network setting in the VM. .. image:: /_static/assets/winnetsetting1.png .. image:: /_static/assets/winnetsetting2.png Then, click on "Proxy". .. image:: /_static/assets/winnetsetting3.png Switch on "Use a proxy server" and type in the correct proxy configurations. .. image:: /_static/assets/winnetsetting4.png Finally, remember to click on "Save". Note that only HTTP proxy is supported. Subsequently, you can open a chrome page to check if the proxy works well. 3. Create a New Snapshot ------------------------ After modifying the virtual machine, remember to create a new snapshot and start from this new snapshot at experiments. .. code-block:: sh # change ws to fusion if you use VMWare Fusion vmrun -T ws snapshot /path/to/vmx/file snapshot_name .. code-block:: python # Modify snapshot_name in "desktop_env/envs/desktop_env.py", line 50 snapshot_name: str = "snapshot_name", 4. Modify chrome startup command -------------------------------- By searching `"--remote-debugging-port=1337"`, you can find all the places that involve Chrome startup commands, and add the parameter `--proxy-server=host_IP:port` .. code-block:: python # example # before "command": ["google-chrome", "--remote-debugging-port=1337"] # after (add proxy parameter) "command": ["google-chrome", "--remote-debugging-port=1337", "--proxy-server=192.168.108.1:1080"] Replace ``192.168.108.1:1080`` with your actual host IP and proxy port. See Also -------- - `DataImpulse Official Website `_ - Residential proxy service provider - :doc:`../user_guides/environment_explanation` - DesktopEnv interface documentation with enable_proxy parameter - :doc:`quickstart` - Quick start guide for OSWorld - :doc:`install_provider/index` - Provider-specific installation guides