uv pip install git+https://github.com/facebookresearch/openapps.git
- Pre-requisite: install uv (a much faster pip):
pip install uv(or from source)
- Install packages:
uv sync - Activate environment:
source .venv/bin/activate - Install
playwright install chromium
Optionally install for onlineshop (off by default)
Onlineshop java + spacy configuration
- Prepare Java, Webshop data and spacy model:
chmod +x setup.shand./setup.shfor Linux X64 or Mac ARM64 systems - Designate Java path:
source setup_javapath.shfor Linux X64 or Mac ARM64 systems - Check
java -versiongives youjava version "21.0.1" - Build search engine indexes:
chmod +x setup_pyserini.shand./setup_pyserini.sh
Congratulations! The onlineshop is ready to be used. Remember in future, always run source setup_javapath.sh to configure Java path before launching onlineshop-related tasks.
Map planning usage
Prerequisite: Java 21.
- Note. By default it is turned off (see
config/apps/maps/default.yaml); if turned on, wait for ~30 seconds for the planner to run in the backend.
- Navigate to map:
cd src/web_agent_playground/playground_server/map_app/ - Grant access and download necessary files:
chmod +x setup_planner.shand./setup_planner.sh
Finally, launch with
uv run launch.py use_wandb=False apps.onlineshop.enable=True
Simply run:
uv run launch.py Each app can be modified with variables available in config/apps. You can override any of these via command line:
uv run launch.py app.todo.title='Super Todo'OpenApps comes with pre-defined variations that can affect the content and appearance of apps. For example, to launch apps with dark mode:
export APPEARANCE="dark_theme"
uv run launch.py apps/calendar/appearance=$APPEARANCE apps/maps/appearance=$APPEARANCE apps/start_page/appearance=$APPEARANCE apps/messenger/appearance=$APPEARANCETo launch the apps with adversarial content:
export CONTENT="adversarial_descriptions"
uv run launch.py apps/calendar/content=$CONTENT apps/maps/content=$CONTENT apps/start_page/content=$CONTENT apps/messenger/content=$CONTENT apps/todo/content=$CONTENT apps/pop_ups=$CONTENTOptions:
- content:
default, long_descriptions, german, misleading_descriptions - appearance:
default, dark_theme, black_and_white, challenging_font
To launch popups, set apps/pop_ups=adversarial_descriptions.
You can see the specific variables for each defined in the individual apps. For example, config/apps/maps/appearance/dark_theme.yaml.
Launch an agent to perform a task:
uv run launch_agent.py
To see the agent solving the task live:
uv run launch_agent.py browsergym_env_args.headless=False
You can specify the agent of your choice with the agent= argument. For example agent=dummy is a simple agent that clicks randomly on any buttons, great for exploration!
Learn more about launching with OpenAI, Claude, and VLLM models such as UI-Tars in our docs.
launch thousands of app variations to study agent behaviors in parallel
To launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps:
uv run launch_sweep.py
- Note each deployment of OpenApps can have different appearance and content
- Note each task is launched in an isolated environment to ensure reproducible results.
Run all tests via:
uv run -m pytest tests/Our apps are built on top of several excellent frameworks:
- FastHTML framework and examples which allowed us to build fully functional apps in Python, the language most familiar to AI researchers.
- Browser Gym and AgentLab:
- Spacy: for natural language processing
- Open Street Maps: https://www.openstreetmap.org/copyright for our Maps apps.
- (and for the optional webshop) we rely on WebShop developed by Princeton
Some icons are have been designed using resources from Flaticon.com
uv sync --extra dev
To build docs:
mkdocs build
mkdocs serve
this will launch docs available at https://facebookresearch.github.io/OpenApps/
Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory.
Copyright © Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.
