From 8978ac6c082628144a5778ff56adc6444579c5f4 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Wed, 5 Aug 2026 11:41:57 -0400
Subject: [PATCH 01/23] [Improvement] Theme & layout args, changes: - theme
 design vars - set default layout - set default theme - use design vars in
 todo app - update README - add theme & layout to appserver - retain
 appearance for legacy usage - add theme & layout to registry and session - 44
 tests passing

---
 config/apps/theme/bootstrap.yaml          |  21 ++++
 config/apps/theme/challenging_font.yaml   |  22 ++++
 config/apps/theme/dark.yaml               |  21 ++++
 config/apps/theme/default.yaml            |  23 +++++
 config/apps/theme/material.yaml           |  21 ++++
 config/apps/theme/mono.yaml               |  21 ++++
 config/apps/theme/solarized.yaml          |  21 ++++
 config/apps/todo/layout/default.yaml      |   3 +
 config/apps/todo/layout/kanban_board.yaml |   4 +
 src/open_apps/theme.py                    | 119 ++++++++++++++++++++++
 10 files changed, 276 insertions(+)
 create mode 100644 config/apps/theme/bootstrap.yaml
 create mode 100644 config/apps/theme/challenging_font.yaml
 create mode 100644 config/apps/theme/dark.yaml
 create mode 100644 config/apps/theme/default.yaml
 create mode 100644 config/apps/theme/material.yaml
 create mode 100644 config/apps/theme/mono.yaml
 create mode 100644 config/apps/theme/solarized.yaml
 create mode 100644 config/apps/todo/layout/default.yaml
 create mode 100644 config/apps/todo/layout/kanban_board.yaml
 create mode 100644 src/open_apps/theme.py

diff --git a/config/apps/theme/bootstrap.yaml b/config/apps/theme/bootstrap.yaml
new file mode 100644
index 00000000..cb2a8bfd
--- /dev/null
+++ b/config/apps/theme/bootstrap.yaml
@@ -0,0 +1,21 @@
+# @package apps.theme
+# Bootstrap 5 look approximated with design tokens (no Bootstrap CSS needed).
+name: bootstrap
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#f8f9fa"
+  color-fg: "#212529"
+  color-muted: "#6c757d"
+  color-border: "#dee2e6"
+  color-primary: "#0d6efd"
+  color-on-primary: "#ffffff"
+  color-accent: "#198754"
+  color-danger: "#dc3545"
+  color-neutral: "#6c757d"
+  color-btn-fg: "#ffffff"
+  font-family: "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif"
+  font-heading: "inherit"
+  font-size-base: "16px"
+  radius: "0.375rem"
+  space: "8px"
diff --git a/config/apps/theme/challenging_font.yaml b/config/apps/theme/challenging_font.yaml
new file mode 100644
index 00000000..9e1842b5
--- /dev/null
+++ b/config/apps/theme/challenging_font.yaml
@@ -0,0 +1,22 @@
+# @package apps.theme
+# Faithful port of the former todo `challenging_font` appearance variant:
+# the default palette rendered in a hard-to-read script face.
+name: challenging_font
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#f4f5f7"
+  color-fg: "#1a1a1a"
+  color-muted: "#6b7280"
+  color-border: "#dfe1e6"
+  color-primary: "#2563eb"
+  color-on-primary: "#ffffff"
+  color-accent: "#2563eb"
+  color-danger: "#b22222"
+  color-neutral: "#36454f"
+  color-btn-fg: "#ffffff"
+  font-family: "'Brush Script MT', cursive"
+  font-heading: "inherit"
+  font-size-base: "16px"
+  radius: "8px"
+  space: "8px"
diff --git a/config/apps/theme/dark.yaml b/config/apps/theme/dark.yaml
new file mode 100644
index 00000000..0f22dd41
--- /dev/null
+++ b/config/apps/theme/dark.yaml
@@ -0,0 +1,21 @@
+# @package apps.theme
+# Faithful port of the former todo `dark_theme` appearance variant.
+name: dark
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#000000"
+  color-fg: "#ffffff"
+  color-muted: "#9ca3af"
+  color-border: "#ffffff"
+  color-primary: "#000000"
+  color-on-primary: "#ffffff"
+  color-accent: "#ffffff"
+  color-danger: "#ffffff"
+  color-neutral: "#ffffff"
+  color-btn-fg: "#000000"
+  font-family: "'Times New Roman', serif"
+  font-heading: "inherit"
+  font-size-base: "16px"
+  radius: "8px"
+  space: "8px"
diff --git a/config/apps/theme/default.yaml b/config/apps/theme/default.yaml
new file mode 100644
index 00000000..e10a9381
--- /dev/null
+++ b/config/apps/theme/default.yaml
@@ -0,0 +1,23 @@
+# @package apps.theme
+# Shared design tokens. Selected globally with `apps/theme=<name>` or per app
+# with `apps.<app>.theme=<name>`. Every `tokens` entry becomes a CSS custom
+# property (`color-primary` -> `--color-primary`) consumed via `var(--...)`.
+name: default
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#f4f5f7"
+  color-fg: "#1a1a1a"
+  color-muted: "#6b7280"
+  color-border: "#dfe1e6"
+  color-primary: "#2563eb"     # add / primary action
+  color-on-primary: "#ffffff"
+  color-accent: "#2563eb"      # save action
+  color-danger: "#b22222"      # remove / destructive
+  color-neutral: "#36454f"     # edit / secondary
+  color-btn-fg: "#ffffff"      # text on edit/remove/save buttons
+  font-family: "'Times New Roman', serif"
+  font-heading: "inherit"
+  font-size-base: "16px"
+  radius: "8px"
+  space: "8px"
diff --git a/config/apps/theme/material.yaml b/config/apps/theme/material.yaml
new file mode 100644
index 00000000..46c16eef
--- /dev/null
+++ b/config/apps/theme/material.yaml
@@ -0,0 +1,21 @@
+# @package apps.theme
+# Material Design look approximated with design tokens (no MUI CSS needed).
+name: material
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#f5f5f5"
+  color-fg: "#212121"
+  color-muted: "#757575"
+  color-border: "#e0e0e0"
+  color-primary: "#6200ee"
+  color-on-primary: "#ffffff"
+  color-accent: "#03dac6"
+  color-danger: "#b00020"
+  color-neutral: "#757575"
+  color-btn-fg: "#ffffff"
+  font-family: "'Roboto', 'Helvetica Neue', sans-serif"
+  font-heading: "inherit"
+  font-size-base: "16px"
+  radius: "4px"
+  space: "8px"
diff --git a/config/apps/theme/mono.yaml b/config/apps/theme/mono.yaml
new file mode 100644
index 00000000..da0ec8b8
--- /dev/null
+++ b/config/apps/theme/mono.yaml
@@ -0,0 +1,21 @@
+# @package apps.theme
+# Faithful port of the former todo `black_and_white` appearance variant.
+name: mono
+import_url: ""
+tokens:
+  color-bg: "#000000"
+  color-surface: "#ffffff"
+  color-fg: "#000000"
+  color-muted: "#000000"
+  color-border: "#000000"
+  color-primary: "#000000"
+  color-on-primary: "#ffffff"
+  color-accent: "#000000"
+  color-danger: "#000000"
+  color-neutral: "#000000"
+  color-btn-fg: "#ffffff"
+  font-family: "'Times New Roman', serif"
+  font-heading: "inherit"
+  font-size-base: "16px"
+  radius: "8px"
+  space: "8px"
diff --git a/config/apps/theme/solarized.yaml b/config/apps/theme/solarized.yaml
new file mode 100644
index 00000000..c50333f8
--- /dev/null
+++ b/config/apps/theme/solarized.yaml
@@ -0,0 +1,21 @@
+# @package apps.theme
+# Solarized Light (Ethan Schoonover palette).
+name: solarized
+import_url: ""
+tokens:
+  color-bg: "#fdf6e3"
+  color-surface: "#eee8d5"
+  color-fg: "#657b83"
+  color-muted: "#93a1a1"
+  color-border: "#93a1a1"
+  color-primary: "#268bd2"
+  color-on-primary: "#fdf6e3"
+  color-accent: "#2aa198"
+  color-danger: "#dc322f"
+  color-neutral: "#586e75"
+  color-btn-fg: "#fdf6e3"
+  font-family: "'Inter', system-ui, sans-serif"
+  font-heading: "inherit"
+  font-size-base: "16px"
+  radius: "8px"
+  space: "8px"
diff --git a/config/apps/todo/layout/default.yaml b/config/apps/todo/layout/default.yaml
new file mode 100644
index 00000000..f00b4298
--- /dev/null
+++ b/config/apps/todo/layout/default.yaml
@@ -0,0 +1,3 @@
+# @package apps.todo
+# Structure only -- no colors/fonts (those come from the shared theme).
+layout: default
diff --git a/config/apps/todo/layout/kanban_board.yaml b/config/apps/todo/layout/kanban_board.yaml
new file mode 100644
index 00000000..0a0ddb80
--- /dev/null
+++ b/config/apps/todo/layout/kanban_board.yaml
@@ -0,0 +1,4 @@
+# @package apps.todo
+# Structure only -- colors/fonts come from the shared theme. Select with
+# `apps/todo/layout=kanban_board`.
+layout: kanban_board
diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
new file mode 100644
index 00000000..ef5e318c
--- /dev/null
+++ b/src/open_apps/theme.py
@@ -0,0 +1,119 @@
+"""
+Copyright (c) Meta Platforms, Inc. and affiliates.
+All rights reserved.
+This source code is licensed under the license found in the
+LICENSE file in the root directory of this source tree.
+
+Shared design-token theming for OpenApps.
+
+A *theme* is a set of design tokens (colors, typography, shape, spacing)
+defined once in ``config/apps/theme/<name>.yaml`` and shared across every
+app. Selecting a theme emits a ``:root { --token: value }`` block that all
+apps consume via ``var(--token)``. This decouples *look* (theme) from
+*structure* (each app's ``layout``).
+
+Selection is done with Hydra overrides:
+
+* ``apps/theme=solarized``      -> global default for every app
+* ``apps.todo.theme=solarized`` -> override a single app (falls back to
+  the global theme when the app's ``theme`` field is null/unset)
+
+A theme file looks like::
+
+    # @package apps.theme
+    name: solarized
+    import_url: ""          # optional external stylesheet escape hatch
+    tokens:
+      color-bg: "#fdf6e3"
+      color-fg: "#657b83"
+      color-primary: "#268bd2"
+      font-family: "'Inter', sans-serif"
+      radius: "8px"
+      ...
+
+The ``tokens`` mapping is open-ended: every ``key: value`` becomes the CSS
+custom property ``--key: value``, so apps can introduce new tokens without
+touching this module.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from fasthtml.common import Style
+
+# Repo-root/config/apps/theme -- this file lives at src/open_apps/theme.py.
+_THEME_DIR = Path(__file__).resolve().parents[2] / "config" / "apps" / "theme"
+
+_DEFAULT_THEME = "default"
+
+
+def _as_plain(value):
+    """Coerce an OmegaConf node (or anything mapping-like) to a plain dict."""
+    if value is None:
+        return {}
+    # OmegaConf DictConfig exposes ``items``; so does a plain dict.
+    if hasattr(value, "items"):
+        return {k: v for k, v in value.items()}
+    return dict(value)
+
+
+def load_theme(name: str) -> dict:
+    """Load a theme's tokens from ``config/apps/theme/<name>.yaml``.
+
+    Returns a dict with at least ``name``, ``tokens`` and ``import_url``.
+    Falls back to the default theme when ``name`` is unknown so a bad
+    override degrades gracefully instead of raising.
+    """
+    path = _THEME_DIR / f"{name}.yaml"
+    if not path.exists():
+        path = _THEME_DIR / f"{_DEFAULT_THEME}.yaml"
+    data = yaml.safe_load(path.read_text()) or {}
+    data.setdefault("name", name)
+    data.setdefault("tokens", {})
+    data.setdefault("import_url", "")
+    return data
+
+
+def resolve_theme(apps_config, app_name: str) -> dict:
+    """Resolve the effective theme for ``app_name``.
+
+    ``apps_config`` is the ``config.apps`` node handed to every app as
+    ``app.config``. Precedence: per-app ``apps.<app_name>.theme`` (a theme
+    name string) overrides the global ``apps.theme`` group; a null/unset
+    per-app value inherits the global theme.
+    """
+    app_cfg = getattr(apps_config, app_name, None)
+    per_app = getattr(app_cfg, "theme", None) if app_cfg is not None else None
+    if per_app:
+        return load_theme(str(per_app))
+
+    global_theme = getattr(apps_config, "theme", None)
+    if global_theme is not None:
+        theme = _as_plain(global_theme)
+        theme.setdefault("tokens", {})
+        theme["tokens"] = _as_plain(theme["tokens"])
+        return theme
+
+    return load_theme(_DEFAULT_THEME)
+
+
+def render_theme_tokens(theme: dict) -> Style:
+    """Build the ``:root`` CSS-variable block (plus optional import) for a theme.
+
+    ``theme`` is the dict returned by :func:`resolve_theme` / :func:`load_theme`.
+    """
+    tokens = _as_plain(theme.get("tokens", {}))
+    lines = "\n".join(f"  --{key}: {value};" for key, value in tokens.items())
+    import_url = (theme.get("import_url") or "").strip()
+    import_rule = f'@import url("{import_url}");\n' if import_url else ""
+    css = f"{import_rule}:root {{\n{lines}\n}}"
+    return Style(css)
+
+
+def theme_style(apps_config, app_name: str) -> Style:
+    """Convenience: resolve + render the token block for ``app_name`` in one call.
+
+    Call this per-request so live ``reconfigure`` theme swaps take effect.
+    """
+    return render_theme_tokens(resolve_theme(apps_config, app_name))

From dfc7042cc2339a7382727325fb50ad92b84c5f07 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Wed, 5 Aug 2026 14:02:50 -0400
Subject: [PATCH 02/23] adding missed files

---
 .../apps/todo/appearance/black_and_white.yaml |  11 -
 .../todo/appearance/challenging_font.yaml     |   9 -
 config/apps/todo/appearance/dark_theme.yaml   |  11 -
 config/apps/todo/appearance/default.yaml      |  10 -
 config/apps/todo/appearance/kanban_board.yaml |  12 -
 config/apps/todo/default.yaml                 |   6 +-
 config/config.yaml                            |   1 +
 config/config_parallel_tasks.yaml             |   2 +-
 src/open_apps/apps/todo_app/main.py           | 218 +++++++++---------
 src/open_apps/mcp/README.md                   |   4 +-
 src/open_apps/mcp/appserver.py                |  19 +-
 src/open_apps/mcp/registry.py                 |  10 +-
 src/open_apps/mcp/server.py                   |  16 +-
 src/open_apps/mcp/session.py                  |   4 +
 tests/test_mcp.py                             |  11 +-
 15 files changed, 168 insertions(+), 176 deletions(-)
 delete mode 100644 config/apps/todo/appearance/black_and_white.yaml
 delete mode 100644 config/apps/todo/appearance/challenging_font.yaml
 delete mode 100644 config/apps/todo/appearance/dark_theme.yaml
 delete mode 100644 config/apps/todo/appearance/default.yaml
 delete mode 100644 config/apps/todo/appearance/kanban_board.yaml

diff --git a/config/apps/todo/appearance/black_and_white.yaml b/config/apps/todo/appearance/black_and_white.yaml
deleted file mode 100644
index ca0a9ff6..00000000
--- a/config/apps/todo/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
-# @package apps.todo
-add_button_color: "#000000"
-background_color: "#000000"
-form_background_color: "#FFFFFF"
-remove_button_color: "#000000"
-edit_button_color: "#000000"
-save_button_color: "#000000"
-font_family: 'Times New Roman'
-base_font_size: '16px'
-font_color: "#000000"
-edit_remove_save_button_font_color: "#FFFFFF"
\ No newline at end of file
diff --git a/config/apps/todo/appearance/challenging_font.yaml b/config/apps/todo/appearance/challenging_font.yaml
deleted file mode 100644
index efa24740..00000000
--- a/config/apps/todo/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,9 +0,0 @@
-# @package apps.todo
-add_button_color: ""
-form_background_color: "light"
-remove_button_color: "#B22222"
-edit_button_color: "#36454F"
-save_button_color: ""
-font_family: 'Brush Script MT'
-base_font_size: '16px'
-font_color: ""
\ No newline at end of file
diff --git a/config/apps/todo/appearance/dark_theme.yaml b/config/apps/todo/appearance/dark_theme.yaml
deleted file mode 100644
index 1f1d4416..00000000
--- a/config/apps/todo/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
-# @package apps.todo
-add_button_color: "#000000"
-background_color: "#FFFFFF"
-form_background_color: "#000000"
-remove_button_color: "#FFFFFF"
-edit_button_color: "#FFFFFF"
-save_button_color: "#FFFFFF"
-font_family: 'Times New Roman'
-base_font_size: '16px'
-font_color: "#FFFFFF"
-edit_remove_save_button_font_color: "#000000"
\ No newline at end of file
diff --git a/config/apps/todo/appearance/default.yaml b/config/apps/todo/appearance/default.yaml
deleted file mode 100644
index d8b9bac2..00000000
--- a/config/apps/todo/appearance/default.yaml
+++ /dev/null
@@ -1,10 +0,0 @@
-# @package apps.todo
-layout: default
-add_button_color: ""
-form_background_color: "light"
-remove_button_color: "#B22222"
-edit_button_color: "#36454F"
-save_button_color: ""
-font_family: 'Times New Roman'
-base_font_size: '16px'
-font_color: ""
\ No newline at end of file
diff --git a/config/apps/todo/appearance/kanban_board.yaml b/config/apps/todo/appearance/kanban_board.yaml
deleted file mode 100644
index ebb7ba8a..00000000
--- a/config/apps/todo/appearance/kanban_board.yaml
+++ /dev/null
@@ -1,12 +0,0 @@
-# @package apps.todo
-layout: kanban_board
-add_button_color: ""
-background_color: "#ffffff"
-form_background_color: "#ebecf0"
-remove_button_color: "#B22222"
-edit_button_color: "#36454F"
-save_button_color: ""
-font_family: 'Times New Roman'
-base_font_size: '16px'
-font_color: ""
-edit_remove_save_button_font_color: ""
diff --git a/config/apps/todo/default.yaml b/config/apps/todo/default.yaml
index 5f53569c..b21eaea4 100644
--- a/config/apps/todo/default.yaml
+++ b/config/apps/todo/default.yaml
@@ -1,6 +1,10 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
 
 database_path: ${databases_dir}/todo.db
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.todo.theme=solarized`.
+theme: null
diff --git a/config/config.yaml b/config/config.yaml
index c2244879..ce712fec 100644
--- a/config/config.yaml
+++ b/config/config.yaml
@@ -4,6 +4,7 @@ defaults:
   - agent: default
   - tasks: all_tasks
   - browsergym_env_args: default
+  - apps/theme: default
   - apps/code_editor: default
   - apps/maps: default
   - apps/messenger: default
diff --git a/config/config_parallel_tasks.yaml b/config/config_parallel_tasks.yaml
index 31b8bb75..9b15da8f 100644
--- a/config/config_parallel_tasks.yaml
+++ b/config/config_parallel_tasks.yaml
@@ -36,7 +36,7 @@ parallel_tasks:
     - [
         "apps/start_page/appearance=dark_theme",
         "apps/calendar/appearance=dark_theme",
-        "apps/todo/appearance=dark_theme",
+        "apps.todo.theme=dark",
         "apps/messenger/appearance=dark_theme",
         "apps/maps/appearance=dark_theme",
         "apps/code_editor/appearance=dark_theme",
diff --git a/src/open_apps/apps/todo_app/main.py b/src/open_apps/apps/todo_app/main.py
index 7712b54f..a997cf1f 100644
--- a/src/open_apps/apps/todo_app/main.py
+++ b/src/open_apps/apps/todo_app/main.py
@@ -10,6 +10,7 @@
 from typing import List
 from src.open_apps.apps.start_page.helper import create_logo_header
 from src.open_apps.frontend import local_hdrs
+from src.open_apps.theme import theme_style
 
 
 @dataclass
@@ -21,11 +22,109 @@ class Todo:
 
 app, rt = fast_app(default_hdrs=False, hdrs=local_hdrs())
 logo_title_container = None
-styles = Style("")
+
+# Static, theme-agnostic component styles. All colors/fonts are design tokens
+# resolved per-request via `theme_style()` (see the `:root` block it emits), so
+# this block never needs rebuilding when the theme or app config changes.
+styles = Style("""
+    body {
+        font-family: var(--font-family);
+        font-size: var(--font-size-base);
+        color: var(--color-fg);
+        background-color: var(--color-bg);
+    }
+    .todo, .card, .group, .add-btn {
+        color: var(--color-fg);
+    }
+    a {
+        color: var(--color-fg);
+        text-decoration: none;
+    }
+    .todo-item, .todo-controls {
+        list-style-type: none;
+        color: var(--color-fg);
+    }
+    .todo-general {
+        background-color: var(--color-surface);
+    }
+    .todo-controls {
+        margin-left: 12px;
+    }
+    .todo-btn {
+        transform: scale(.7);
+        color: var(--color-fg);
+    }
+    .edit-btn {
+        background-color: var(--color-neutral);
+        border: 1px solid var(--color-neutral);
+        color: var(--color-btn-fg);
+    }
+    .remove-btn {
+        background-color: var(--color-danger);
+        border: 1px solid var(--color-danger);
+        color: var(--color-btn-fg);
+    }
+    .add-btn {
+        background-color: var(--color-primary);
+        color: var(--color-on-primary);
+    }
+    .save-btn {
+        background-color: var(--color-accent);
+        border: 1px solid var(--color-accent);
+        color: var(--color-btn-fg);
+    }
+    .kanban-board {
+        width: 100%;
+    }
+    .kanban-columns {
+        display: flex;
+        gap: 1rem;
+        align-items: flex-start;
+        margin-top: 1rem;
+        overflow-x: auto;
+        padding-bottom: 0.5rem;
+    }
+    .kanban-column {
+        flex: 0 0 450px;
+        min-width: 450px;
+        background-color: var(--color-surface);
+        border-radius: var(--radius);
+        padding: 0.5rem 0.75rem;
+        min-height: 120px;
+    }
+    .kanban-column-title {
+        margin-top: 0.25rem;
+    }
+    .kanban-card {
+        background-color: var(--color-bg);
+        border: 1px solid var(--color-border);
+        border-radius: var(--radius);
+        padding: 0.5rem 0.75rem;
+        margin-bottom: 0.5rem;
+    }
+    .kanban-card-title {
+        margin-bottom: 0.4rem;
+    }
+    .kanban-card-controls {
+        display: flex;
+        gap: 0.25rem;
+        flex-wrap: wrap;
+    }
+    .kanban-edit input {
+        margin-bottom: 0.4rem;
+    }
+    .kanban-add {
+        margin-top: 0.5rem;
+    }
+    .kanban-header-edit {
+        display: flex;
+        gap: 0.25rem;
+    }
+""")
 
 def set_environment(config):
     """Set environment variables for the todo app"""
-    global app, logo_title_container, styles
+    global app, logo_title_container
     app.config = config
     db = database(config.todo.database_path)
     global todos, kanban_status
@@ -49,111 +148,12 @@ def set_environment(config):
         current_file_path=__file__
     )
 
-    font_family = app.config.todo.font_family
-    font_size = app.config.todo.base_font_size
-    font_color = getattr(app.config.todo, "font_color", "blue")
-    edit_remove_save_button_font_color = getattr(app.config.todo, "edit_remove_save_button_font_color", "")
-    edit_button_color = app.config.todo.edit_button_color
-    remove_button_color = app.config.todo.remove_button_color
-    add_button_color = app.config.todo.add_button_color
-    save_button_color = app.config.todo.save_button_color
-    background_color = getattr(app.config.todo, "background_color", "")
-    form_background_color = getattr(app.config.todo, "form_background_color", "")
-    styles.children = [f"""
-        body {{
-            font-family: {font_family};
-            font-size: {font_size};
-            color: {font_color};
-            background-color: {background_color}
-        }}
-        .todo, .card, .group, .add-btn {{
-            background-color: {background_color}
-            color: {font_color};
-        }}
-        a {{
-            color: {font_color};
-            text-decoration: none;
-        }}
-        .todo-item, .todo-controls {{
-            list-style-type: none;
-            color: {font_color};
-        }}
-        .todo-general {{
-            background-color: {form_background_color}
-        }}
-        .todo-controls {{
-            margin-left: 12px;
-        }}
-        .todo-btn {{
-            transform: scale(.7);
-            color: {font_color};
-        }}
-        .edit-btn {{
-            background-color: {edit_button_color};
-            border: 1px solid {edit_button_color};
-            color: {edit_remove_save_button_font_color};
-        }}
-        .remove-btn {{
-            background-color: {remove_button_color};
-            border: 1px solid {remove_button_color};
-            color: {edit_remove_save_button_font_color};
-        }}
-        .add-btn {{
-            background-color: {add_button_color};
-        }}
-        .save-btn {{
-            background-color: {save_button_color};
-            border: 1px solid {save_button_color};
-            color: {edit_remove_save_button_font_color};
-        }}
-        .kanban-board {{
-            width: 100%;
-        }}
-        .kanban-columns {{
-            display: flex;
-            gap: 1rem;
-            align-items: flex-start;
-            margin-top: 1rem;
-            overflow-x: auto;
-            padding-bottom: 0.5rem;
-        }}
-        .kanban-column {{
-            flex: 0 0 450px;
-            min-width: 450px;
-            background-color: {form_background_color};
-            border-radius: 8px;
-            padding: 0.5rem 0.75rem;
-            min-height: 120px;
-        }}
-        .kanban-column-title {{
-            margin-top: 0.25rem;
-        }}
-        .kanban-card {{
-            background-color: {background_color};
-            border: 1px solid {edit_button_color};
-            border-radius: 6px;
-            padding: 0.5rem 0.75rem;
-            margin-bottom: 0.5rem;
-        }}
-        .kanban-card-title {{
-            margin-bottom: 0.4rem;
-        }}
-        .kanban-card-controls {{
-            display: flex;
-            gap: 0.25rem;
-            flex-wrap: wrap;
-        }}
-        .kanban-edit input {{
-            margin-bottom: 0.4rem;
-        }}
-        .kanban-add {{
-            margin-top: 0.5rem;
-        }}
-        .kanban-header-edit {{
-            display: flex;
-            gap: 0.25rem;
-        }}
-    """]
+
+def todo_theme():
+    """The active theme's `:root` token block, resolved per-request so live
+    `reconfigure` theme swaps take effect."""
+    return theme_style(app.config, "todo")
+
 
 id_curr = "current-todo"
 
@@ -340,7 +340,7 @@ def get():
             cls="contrast",
             style="margin-top: 1rem;",
         )
-        return Div(styles, logo_title_container, render_kanban_board(), home_button)
+        return Div(todo_theme(), styles, logo_title_container, render_kanban_board(), home_button)
     add = Form(
         Group(
             mk_input(),
@@ -349,11 +349,11 @@ def get():
         hx_post="/todo",  # Update this path
         target_id="todo-list",
         hx_swap="beforeend",
-        data_theme=app.config.todo.form_background_color,
     )
     card = (Card(Ul(*todos(), id="todo-list"), header=add, footer=Div(id=id_curr), cls="todo-general"),)
     home_button = A("Return to List of Apps", href="/", role="button", cls="contrast", style="margin-top: 1rem;")
     return Div(
+        todo_theme(),
         styles,
         logo_title_container,
         card,
diff --git a/src/open_apps/mcp/README.md b/src/open_apps/mcp/README.md
index 53ab3154..c676e163 100644
--- a/src/open_apps/mcp/README.md
+++ b/src/open_apps/mcp/README.md
@@ -45,9 +45,9 @@ the server is then ready for tool calls.
 | `load_task(key)` | Bind a task for scoring; returns its goal. Call `reset` after. |
 | `get_reward()` | Reward for the bound task (1.0 if complete, else 0.0). |
 | `set_goal(goal)` | Free-form goal, no automatic scoring. |
-| `reconfigure(appearance, content, seed, extras)` | Live variant/seed change. |
+| `reconfigure(theme, layout, appearance, content, seed, extras)` | Live variant/seed change. `theme` is the shared global design-token theme; `layout` is per-app structure; `appearance` is legacy (unmigrated apps). |
 | `list_apps()` | App keys actually registered (Java-aware). |
-| `list_variants(app, group)` | Variant stems for `appearance`/`content`. |
+| `list_variants(app, group)` | Variant stems for a group (`theme`/`layout`/`content`/`appearance`). |
 | `app_url(app=None)` | Absolute URL of an app's landing page. |
 
 **Actions** are BrowserGym action strings (full-resolution pixels):
diff --git a/src/open_apps/mcp/appserver.py b/src/open_apps/mcp/appserver.py
index 05c8e7db..3528b965 100644
--- a/src/open_apps/mcp/appserver.py
+++ b/src/open_apps/mcp/appserver.py
@@ -157,6 +157,8 @@ def reset(self) -> None:
     def reconfigure(
         self,
         *,
+        theme: str | None = None,
+        layout: str | None = None,
         appearance: str | None = None,
         content: str | None = None,
         seed: int | None = None,
@@ -166,12 +168,19 @@ def reconfigure(
 
         FastHTML routes read ``app.config`` per-request, so the live
         config update propagates without restarting the server. This
-        only swaps appearance/content/seed/extras + re-seeds sqlite; it
+        only swaps theme/layout/content/seed/extras + re-seeds sqlite; it
         cannot add or remove apps (the registered set is fixed at init).
 
         Args:
-            appearance: Variant yaml stem under
-                ``config/apps/<app>/appearance/`` for ``self.app_name``.
+            theme: Shared design-token theme stem under
+                ``config/apps/theme/`` (e.g. ``solarized``). Global: applies
+                to every app that renders design tokens.
+            layout: Per-app structure variant stem under
+                ``config/apps/<app>/layout/`` for ``self.app_name``
+                (e.g. ``kanban_board``).
+            appearance: Legacy per-app variant stem under
+                ``config/apps/<app>/appearance/`` for apps not yet migrated
+                to the theme/layout split.
             content: Variant yaml stem under
                 ``config/apps/<app>/content/`` for ``self.app_name``.
             seed: Fresh integer seed for the OpenApps content samplers.
@@ -181,6 +190,10 @@ def reconfigure(
         """
         cfg_dir = config_dir_for(self.app_name)
         overrides: list[str] = []
+        if theme is not None:
+            overrides.append(f"apps/theme={theme}")
+        if layout is not None:
+            overrides.append(f"apps/{cfg_dir}/layout={layout}")
         if appearance is not None:
             overrides.append(f"apps/{cfg_dir}/appearance={appearance}")
         if content is not None:
diff --git a/src/open_apps/mcp/registry.py b/src/open_apps/mcp/registry.py
index ef23462b..90e61e0e 100644
--- a/src/open_apps/mcp/registry.py
+++ b/src/open_apps/mcp/registry.py
@@ -48,14 +48,20 @@ def config_dir_for(app_name: str) -> str:
 
 
 def list_variants(app_name: str, group: str) -> list[str]:
-    """List Hydra variant yamls for an app's group (``appearance``/``content``).
+    """List Hydra variant yamls for a group (``theme``/``layout``/``content``/``appearance``).
 
     Returns a sorted list of variant stems (without ``.yaml``).
     ``"default"`` is forced to index 0 when present so it has a stable
     sampling identity. Returns ``["default"]`` if the group dir is
     missing.
+
+    ``theme`` is a *shared* group (``config/apps/theme/``) applying to every
+    app, so ``app_name`` is ignored for it; all other groups are per-app.
     """
-    group_dir = config_dir() / "apps" / config_dir_for(app_name) / group
+    if group == "theme":
+        group_dir = config_dir() / "apps" / "theme"
+    else:
+        group_dir = config_dir() / "apps" / config_dir_for(app_name) / group
     if not group_dir.is_dir():
         return ["default"]
     stems = sorted(p.stem for p in group_dir.glob("*.yaml"))
diff --git a/src/open_apps/mcp/server.py b/src/open_apps/mcp/server.py
index fbaf3caa..72ad63db 100644
--- a/src/open_apps/mcp/server.py
+++ b/src/open_apps/mcp/server.py
@@ -86,14 +86,26 @@ async def reset(seed: int | None = None):
 
 @mcp.tool()
 async def reconfigure(
+    theme: str | None = None,
+    layout: str | None = None,
     appearance: str | None = None,
     content: str | None = None,
     seed: int | None = None,
     extras: dict | None = None,
 ) -> str:
-    """Swap appearance/content variant and seed (live) and re-seed app state."""
+    """Swap theme/layout/content variant and seed (live) and re-seed app state.
+
+    `theme` is the shared design-token theme (global); `layout` is the per-app
+    structure; `appearance` is the legacy per-app variant for apps not yet
+    migrated to the theme/layout split.
+    """
     await _require().reconfigure(
-        appearance=appearance, content=content, seed=seed, extras=extras
+        theme=theme,
+        layout=layout,
+        appearance=appearance,
+        content=content,
+        seed=seed,
+        extras=extras,
     )
     return "reconfigured"
 
diff --git a/src/open_apps/mcp/session.py b/src/open_apps/mcp/session.py
index 3bc99dca..66058381 100644
--- a/src/open_apps/mcp/session.py
+++ b/src/open_apps/mcp/session.py
@@ -208,6 +208,8 @@ async def reset(self, *, seed: int | None = None, options: dict | None = None) -
     async def reconfigure(
         self,
         *,
+        theme: str | None = None,
+        layout: str | None = None,
         appearance: str | None = None,
         content: str | None = None,
         seed: int | None = None,
@@ -216,6 +218,8 @@ async def reconfigure(
         self._require_started()
         await asyncio.to_thread(
             self.appserver.reconfigure,
+            theme=theme,
+            layout=layout,
             appearance=appearance,
             content=content,
             seed=seed,
diff --git a/tests/test_mcp.py b/tests/test_mcp.py
index 51823e4a..b0beb908 100644
--- a/tests/test_mcp.py
+++ b/tests/test_mcp.py
@@ -103,9 +103,14 @@ def test_config_dir_for(self):
         assert registry.config_dir_for("todo") == "todo"
 
     def test_list_variants_default_first(self):
-        variants = registry.list_variants("todo", "appearance")
-        assert variants[0] == "default"
-        assert "dark_theme" in variants
+        # Per-app structure group.
+        layouts = registry.list_variants("todo", "layout")
+        assert layouts[0] == "default"
+        assert "kanban_board" in layouts
+        # Shared design-token theme group (app_name ignored).
+        themes = registry.list_variants("todo", "theme")
+        assert themes[0] == "default"
+        assert "solarized" in themes
 
 
 def _browsergym_calls(fn, *args):

From 46f18cbb37eeb15a80bf14f80bb389607e6b3c1e Mon Sep 17 00:00:00 2001
From: Smokey <aaronsmulktis@gmail.com>
Date: Tue, 11 Aug 2026 10:07:35 -0400
Subject: [PATCH 03/23] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/open_apps/theme.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index ef5e318c..fc254403 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -14,8 +14,8 @@
 
 Selection is done with Hydra overrides:
 
-* ``apps/theme=solarized``      -> global default for every app
-* ``apps.todo.theme=solarized`` -> override a single app (falls back to
+* ``+apps/theme=solarized``      -> global default for every app (requires adding the group if not in defaults)
+* ``apps.todo.theme=solarized``  -> override a single app (falls back to
   the global theme when the app's ``theme`` field is null/unset)
 
 A theme file looks like::

From 91585de5ef46196a7783595fc4ef2bfec5411040 Mon Sep 17 00:00:00 2001
From: Smokey <aaronsmulktis@gmail.com>
Date: Tue, 11 Aug 2026 10:07:49 -0400
Subject: [PATCH 04/23] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 config/apps/todo/layout/kanban_board.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/config/apps/todo/layout/kanban_board.yaml b/config/apps/todo/layout/kanban_board.yaml
index 0a0ddb80..8302e50a 100644
--- a/config/apps/todo/layout/kanban_board.yaml
+++ b/config/apps/todo/layout/kanban_board.yaml
@@ -1,4 +1,4 @@
 # @package apps.todo
 # Structure only -- colors/fonts come from the shared theme. Select with
-# `apps/todo/layout=kanban_board`.
+# `+apps/todo/layout=kanban_board` (or add `layout: default` to apps/todo/default.yaml defaults).
 layout: kanban_board

From 26599d7fbb6b810bde53ca6dd279c89e85b45e45 Mon Sep 17 00:00:00 2001
From: Smokey <aaronsmulktis@gmail.com>
Date: Tue, 11 Aug 2026 10:08:36 -0400
Subject: [PATCH 05/23] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/open_apps/theme.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index fc254403..a90205dc 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -90,6 +90,10 @@ def resolve_theme(apps_config, app_name: str) -> dict:
 
     global_theme = getattr(apps_config, "theme", None)
     if global_theme is not None:
+        # Allow global theme to be provided either as a composed config node
+        # (apps/theme=<name>) or as a plain string override (apps.theme=<name>). 
+        if isinstance(global_theme, str):
+            return load_theme(global_theme)
         theme = _as_plain(global_theme)
         theme.setdefault("tokens", {})
         theme["tokens"] = _as_plain(theme["tokens"])

From 3064f676bc0c29bed2e40359406faf9c0365ab3f Mon Sep 17 00:00:00 2001
From: Smokey <aaronsmulktis@gmail.com>
Date: Tue, 11 Aug 2026 10:09:42 -0400
Subject: [PATCH 06/23] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/open_apps/theme.py | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index a90205dc..54f60757 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -108,8 +108,23 @@ def render_theme_tokens(theme: dict) -> Style:
     ``theme`` is the dict returned by :func:`resolve_theme` / :func:`load_theme`.
     """
     tokens = _as_plain(theme.get("tokens", {}))
-    lines = "\n".join(f"  --{key}: {value};" for key, value in tokens.items())
+
+    safe_lines: list[str] = []
+    for key, value in tokens.items():
+        key = str(key)
+        # Allow only simple custom-property names to avoid broken CSS/injection.
+        if (not key) or any(not (c.isalnum() or c in "-_") for c in key):
+            continue
+        val = str(value).replace("\n", " ").replace("\r", " ")
+        safe_lines.append(f"  --{key}: {val};")
+
+    lines = "\n".join(safe_lines)
+
     import_url = (theme.get("import_url") or "").strip()
+    # Avoid breaking out of the quoted @import string.
+    if any(c in import_url for c in ('"', "'", "\n", "\r")):
+        import_url = ""
+
     import_rule = f'@import url("{import_url}");\n' if import_url else ""
     css = f"{import_rule}:root {{\n{lines}\n}}"
     return Style(css)

From 5b526c27e3e31230641c0a0a9a8a7e4efddbc48e Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Tue, 11 Aug 2026 10:23:11 -0400
Subject: [PATCH 07/23] [Tweak] add theme unit tests

---
 tests/test_theme.py | 160 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 tests/test_theme.py

diff --git a/tests/test_theme.py b/tests/test_theme.py
new file mode 100644
index 00000000..4dd6286b
--- /dev/null
+++ b/tests/test_theme.py
@@ -0,0 +1,160 @@
+"""
+Copyright (c) Meta Platforms, Inc. and affiliates.
+All rights reserved.
+This source code is licensed under the license found in the
+LICENSE file in the root directory of this source tree.
+"""
+
+"""
+Unit tests for shared design-token theming (open_apps.theme).
+
+Covers the two behaviours that are easy to regress when Hydra groups move
+around: theme *precedence* (per-app override beats the global group) and
+graceful *fallback* (an unknown theme name degrades to the default instead
+of raising).
+"""
+
+from fasthtml.common import to_xml
+from omegaconf import OmegaConf
+
+from open_apps.theme import (
+    load_theme,
+    render_theme_tokens,
+    resolve_theme,
+    theme_style,
+)
+
+
+def css(style) -> str:
+    """Render a ``Style`` FT element down to its CSS text."""
+    return to_xml(style)
+
+
+class TestLoadTheme:
+
+    def test_loads_known_theme(self):
+        theme = load_theme("solarized")
+        assert theme["name"] == "solarized"
+        assert theme["tokens"]["color-bg"] == "#fdf6e3"
+
+    def test_unknown_theme_falls_back_to_default(self):
+        theme = load_theme("does_not_exist")
+        default = load_theme("default")
+        assert theme["name"] == "default"
+        assert theme["tokens"] == default["tokens"]
+
+    def test_always_has_required_keys(self):
+        theme = load_theme("dark")
+        assert set(theme) >= {"name", "tokens", "import_url"}
+
+
+class TestResolveTheme:
+
+    def test_per_app_overrides_global(self):
+        cfg = OmegaConf.create(
+            {"theme": {"name": "dark", "tokens": {"color-bg": "#000000"}},
+             "todo": {"theme": "solarized"}}
+        )
+        assert resolve_theme(cfg, "todo")["name"] == "solarized"
+
+    def test_null_per_app_inherits_global(self):
+        cfg = OmegaConf.create(
+            {"theme": {"name": "dark", "tokens": {"color-bg": "#000000"}},
+             "todo": {"theme": None}}
+        )
+        theme = resolve_theme(cfg, "todo")
+        assert theme["name"] == "dark"
+        assert theme["tokens"]["color-bg"] == "#000000"
+
+    def test_unset_per_app_inherits_global(self):
+        cfg = OmegaConf.create(
+            {"theme": {"name": "dark", "tokens": {}}, "todo": {}}
+        )
+        assert resolve_theme(cfg, "todo")["name"] == "dark"
+
+    def test_global_as_plain_string(self):
+        """``apps.theme=solarized`` (dotted override) rather than a composed group."""
+        cfg = OmegaConf.create({"theme": "solarized", "todo": {}})
+        theme = resolve_theme(cfg, "todo")
+        assert theme["name"] == "solarized"
+        assert theme["tokens"]["color-bg"] == "#fdf6e3"
+
+    def test_no_theme_anywhere_falls_back_to_default(self):
+        cfg = OmegaConf.create({"todo": {}})
+        assert resolve_theme(cfg, "default_probe") == load_theme("default")
+
+    def test_unknown_app_falls_back_to_global(self):
+        cfg = OmegaConf.create({"theme": "solarized"})
+        assert resolve_theme(cfg, "no_such_app")["name"] == "solarized"
+
+    def test_unknown_per_app_name_degrades_to_default(self):
+        cfg = OmegaConf.create({"theme": "solarized", "todo": {"theme": "bogus"}})
+        # A bad per-app override must not raise, and must not silently
+        # inherit the global theme either -- it resolves to the default file.
+        assert resolve_theme(cfg, "todo")["tokens"] == load_theme("default")["tokens"]
+
+    def test_resolved_tokens_are_plain_dicts(self):
+        """Callers index tokens directly; OmegaConf nodes must be coerced."""
+        cfg = OmegaConf.create({"theme": {"name": "x", "tokens": {"radius": "4px"}}})
+        theme = resolve_theme(cfg, "todo")
+        assert isinstance(theme, dict) and isinstance(theme["tokens"], dict)
+        assert theme["tokens"]["radius"] == "4px"
+
+    def test_apps_config_isolated_per_app(self):
+        cfg = OmegaConf.create(
+            {"theme": "default",
+             "todo": {"theme": "solarized"},
+             "calendar": {}}
+        )
+        assert resolve_theme(cfg, "todo")["name"] == "solarized"
+        assert resolve_theme(cfg, "calendar")["name"] == "default"
+
+
+class TestRenderThemeTokens:
+
+    def test_tokens_become_custom_properties(self):
+        out = css(render_theme_tokens(
+            {"tokens": {"color-bg": "#fff", "radius": "8px"}}
+        ))
+        assert ":root {" in out
+        assert "--color-bg: #fff;" in out
+        assert "--radius: 8px;" in out
+
+    def test_empty_tokens_still_renders_valid_block(self):
+        out = css(render_theme_tokens({}))
+        assert ":root {" in out and "}" in out
+        assert "--" not in out
+
+    def test_unsafe_token_names_are_dropped(self):
+        out = css(render_theme_tokens(
+            {"tokens": {"ok-name": "1", "bad; }": "2", "": "3", "a b": "4"}}
+        ))
+        assert "--ok-name: 1;" in out
+        assert "bad" not in out and "a b" not in out
+
+    def test_newlines_in_values_are_flattened(self):
+        out = css(render_theme_tokens({"tokens": {"font-family": "a\nb\rc"}}))
+        assert "--font-family: a b c;" in out
+
+    def test_import_url_is_emitted(self):
+        out = css(render_theme_tokens(
+            {"import_url": "https://example.com/f.css", "tokens": {}}
+        ))
+        assert '@import url("https://example.com/f.css");' in out
+
+    def test_import_url_with_quotes_is_dropped(self):
+        out = css(render_theme_tokens(
+            {"import_url": 'https://x.test/f.css"); body{display:none', "tokens": {}}
+        ))
+        assert "@import" not in out
+
+    def test_missing_import_url_emits_no_rule(self):
+        assert "@import" not in css(render_theme_tokens({"tokens": {"a": "b"}}))
+
+
+class TestThemeStyle:
+
+    def test_resolves_and_renders_in_one_call(self):
+        cfg = OmegaConf.create({"theme": "default", "todo": {"theme": "solarized"}})
+        assert "--color-bg: #fdf6e3;" in css(theme_style(cfg, "todo"))
+        assert "--color-bg: #ffffff;" in css(theme_style(cfg, "calendar"))

From f96f7c98630715e3db05a51305bba0b5816b7f38 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Mon, 31 Aug 2026 16:05:14 -0400
Subject: [PATCH 08/23] [Feature] Make the shared theme visible in the
 appearance-based apps

Only todo renders from the design tokens in `open_apps.theme`; calendar,
messenger, maps, code editor, and the start page each build a `:root` block
of their own from `config/apps/<app>/appearance/`, so an `apps/theme=`
selection was invisible to them.

Add a bridge rather than rewrite five stylesheets: `legacy_theme_css()`
emits the theme's token block, aliases the legacy custom properties onto the
tokens they should follow, and adds the shared page chrome plus the few
per-app selectors whose colors are hard-coded. It returns "" on the `default`
theme, so a deployment that never selects one renders exactly as before.

Each app emits it after its own stylesheet and per-request, so `reconfigure`
theme swaps take effect. Also give every app a `theme: null` field (inherit
the global selection, override with `apps.<app>.theme=`), and extend
save_screenshots.py with a `theme_<stem>` variation per theme file.

Test plan: uv run -m pytest tests/ -> 724 passed, 7 skipped.
---
 config/apps/calendar/default.yaml             |   3 +
 config/apps/code_editor/default.yaml          |   6 +-
 config/apps/maps/default.yaml                 |   4 +
 config/apps/messenger/default.yaml            |   6 +-
 config/apps/start_page/default.yaml           |   4 +
 config/apps/todo/layout/kanban_board.yaml     |   2 +-
 src/open_apps/apps/calendar_app/main.py       |  16 ++-
 src/open_apps/apps/codeeditor_app/main.py     |  17 ++-
 src/open_apps/apps/map_app/main.py            |   4 +
 src/open_apps/apps/map_app/templates/map.html |   3 +
 src/open_apps/apps/messenger_app/main.py      |  13 ++
 src/open_apps/apps/start_page/helper.py       |   9 +-
 src/open_apps/apps/start_page/main.py         |  11 +-
 src/open_apps/theme.py                        | 128 +++++++++++++++++-
 tests/save_screenshots.py                     |  70 ++++++----
 15 files changed, 254 insertions(+), 42 deletions(-)

diff --git a/config/apps/calendar/default.yaml b/config/apps/calendar/default.yaml
index 420ab11f..f72c0b97 100644
--- a/config/apps/calendar/default.yaml
+++ b/config/apps/calendar/default.yaml
@@ -4,3 +4,6 @@ defaults:
 
 database_path: ${databases_dir}/calendar.db
 
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.calendar.theme=solarized`.
+theme: null
diff --git a/config/apps/code_editor/default.yaml b/config/apps/code_editor/default.yaml
index bf61aa66..eab65447 100644
--- a/config/apps/code_editor/default.yaml
+++ b/config/apps/code_editor/default.yaml
@@ -2,4 +2,8 @@ defaults:
   - content: default
   - appearance: default
 
-database_path: ${databases_dir}/codeeditor
\ No newline at end of file
+database_path: ${databases_dir}/codeeditor
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.code_editor.theme=solarized`.
+theme: null
diff --git a/config/apps/maps/default.yaml b/config/apps/maps/default.yaml
index e6a466af..556829f9 100644
--- a/config/apps/maps/default.yaml
+++ b/config/apps/maps/default.yaml
@@ -4,3 +4,7 @@ defaults:
 
 database_path: ${databases_dir}/maps.db
 otp_url: 'http://localhost:8080/'
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.maps.theme=solarized`.
+theme: null
diff --git a/config/apps/messenger/default.yaml b/config/apps/messenger/default.yaml
index d5793271..3d80d5e2 100644
--- a/config/apps/messenger/default.yaml
+++ b/config/apps/messenger/default.yaml
@@ -2,4 +2,8 @@ defaults:
   - content: default
   - appearance: default
   
-database_path: ${databases_dir}/messenger.db
\ No newline at end of file
+database_path: ${databases_dir}/messenger.db
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.messenger.theme=solarized`.
+theme: null
diff --git a/config/apps/start_page/default.yaml b/config/apps/start_page/default.yaml
index c461049f..666a8292 100644
--- a/config/apps/start_page/default.yaml
+++ b/config/apps/start_page/default.yaml
@@ -1,3 +1,7 @@
 defaults:
   - content: default
   - appearance: default
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.start_page.theme=solarized`.
+theme: null
diff --git a/config/apps/todo/layout/kanban_board.yaml b/config/apps/todo/layout/kanban_board.yaml
index 8302e50a..0a0ddb80 100644
--- a/config/apps/todo/layout/kanban_board.yaml
+++ b/config/apps/todo/layout/kanban_board.yaml
@@ -1,4 +1,4 @@
 # @package apps.todo
 # Structure only -- colors/fonts come from the shared theme. Select with
-# `+apps/todo/layout=kanban_board` (or add `layout: default` to apps/todo/default.yaml defaults).
+# `apps/todo/layout=kanban_board`.
 layout: kanban_board
diff --git a/src/open_apps/apps/calendar_app/main.py b/src/open_apps/apps/calendar_app/main.py
index 1b568f9b..0b702009 100644
--- a/src/open_apps/apps/calendar_app/main.py
+++ b/src/open_apps/apps/calendar_app/main.py
@@ -13,6 +13,7 @@
     HighlightJS, database, dataclass)
 from datetime import datetime, timedelta
 from src.open_apps.frontend import local_hdrs
+from src.open_apps.theme import legacy_theme_style
 import calendar
 import os
 import logging
@@ -237,6 +238,15 @@ def set_environment(config):
     )
 
 
+def calendar_theme():
+    """The active theme, mapped onto this app's `appearance` CSS variables.
+
+    Empty on the default theme. Rendered per-request (and after `styles`, which
+    it has to override) so live `reconfigure` theme swaps take effect.
+    """
+    return legacy_theme_style(app.config, "calendar")
+
+
 def update_db_from_hydra():
 
     for event in app.config.calendar.events:
@@ -595,6 +605,7 @@ def get(req):
         Title(app.config.start_page.apps.calendar.title),
         Container(
             styles,
+            calendar_theme(),
             error_div, 
             show_main_layout(today.year, today.month, view)
         ),
@@ -626,6 +637,7 @@ def get(
         Title(app.config.start_page.apps.calendar.title),
         Container(
             styles,
+            calendar_theme(),
             show_main_layout(year, month, view)
         )
     )
@@ -707,7 +719,8 @@ def get(id: int):
     return (
         Title(event.title),
         Container(
-            styles,  
+            styles,
+            calendar_theme(),
             logo_title_container,
             Article(
                 H3(event.title),
@@ -770,6 +783,7 @@ def get_input_attrs(field_name: str, defaults: dict) -> dict:
     return (Title("Creating a new event"),
             Container(
         styles,
+        calendar_theme(),
         logo_title_container,
         Form(
             H3("Create New Event"),
diff --git a/src/open_apps/apps/codeeditor_app/main.py b/src/open_apps/apps/codeeditor_app/main.py
index 5c3565a0..e458a226 100644
--- a/src/open_apps/apps/codeeditor_app/main.py
+++ b/src/open_apps/apps/codeeditor_app/main.py
@@ -12,6 +12,7 @@
 from starlette.responses import Response
 from src.open_apps.apps.start_page.helper import create_logo_header
 from src.open_apps.frontend import local_hdrs
+from src.open_apps.theme import legacy_theme_style
 
 # Global variables
 _base_hdrs_no_highlight = (
@@ -185,6 +186,16 @@ def set_environment(config):
         current_file_path=__file__
     )
 
+def codeeditor_theme():
+    """The active theme, mapped onto this app's `appearance` CSS variables.
+
+    Empty on the default theme. Rendered into the page body (not `app.hdrs`)
+    so it lands after `env_styles`, which it has to override, and so live
+    `reconfigure` theme swaps take effect.
+    """
+    return legacy_theme_style(app.config, "code_editor")
+
+
 def return_to_index():
     return A("Code Editor Index Page", href="/codeeditor", cls="btn btn-primary")
 
@@ -517,7 +528,7 @@ def index():
         ),
     )
     page = Div(cls="flex space-x-2")(side_bar, main_screen)
-    return Div(logo_title_container, page)
+    return Div(codeeditor_theme(), logo_title_container, page)
 
 
 @app.get("/codeeditor/{path:path}")
@@ -623,7 +634,7 @@ def get_folder(folder: str):
         ),
     )
     page = Div(cls="flex space-x-2")(side_bar, main_screen)
-    return Div(logo_title_container, page)
+    return Div(codeeditor_theme(), logo_title_container, page)
 
 def get_file(file: str):
     side_bar = create_sidebar(file)
@@ -946,7 +957,7 @@ def get_file(file: str):
         ),
     )
     page = Div(cls="flex space-x-2")(side_bar, main_screen)
-    return Div(logo_title_container, page)
+    return Div(codeeditor_theme(), logo_title_container, page)
 
 @app.post("/codeeditor/create_folder/{folder:path}")
 def create_folder(folder: str):
diff --git a/src/open_apps/apps/map_app/main.py b/src/open_apps/apps/map_app/main.py
index c4028dd4..ae231e1f 100644
--- a/src/open_apps/apps/map_app/main.py
+++ b/src/open_apps/apps/map_app/main.py
@@ -14,6 +14,7 @@
 from fasthtml.common import *
 import requests
 import json
+from src.open_apps.theme import legacy_theme_css
 from datetime import datetime, timezone
 import subprocess
 import time
@@ -122,6 +123,9 @@ async def map_page(request: Request):
             "calculate_button_hover_color": getattr(app.config.maps, "calculate_button_hover_color", "#2980b9"),
             "sidebar_background_color": getattr(app.config.maps, "sidebar_background_color", "#f8f9fa"),
             "allow_planning": app.config.maps.allow_planning,
+            # Resolved per-request so live `reconfigure` theme swaps take
+            # effect; empty string on the default theme.
+            "theme_css": legacy_theme_css(app.config, "maps"),
         },
     )
 
diff --git a/src/open_apps/apps/map_app/templates/map.html b/src/open_apps/apps/map_app/templates/map.html
index 0608c6aa..2bb54141 100644
--- a/src/open_apps/apps/map_app/templates/map.html
+++ b/src/open_apps/apps/map_app/templates/map.html
@@ -288,6 +288,9 @@
             background-color: #e3f2fd;
         }
     </style>
+    <!-- Shared design tokens (open_apps.theme). Empty unless a theme is
+         selected; must come last so it overrides the appearance config above. -->
+    <style>{{ theme_css|safe }}</style>
 </head>
 
 <body>
diff --git a/src/open_apps/apps/messenger_app/main.py b/src/open_apps/apps/messenger_app/main.py
index 44e992bf..cd7b6c15 100644
--- a/src/open_apps/apps/messenger_app/main.py
+++ b/src/open_apps/apps/messenger_app/main.py
@@ -12,6 +12,7 @@
 import json
 from src.open_apps.apps.start_page.helper import create_logo_header
 from open_apps.frontend import local_hdrs
+from open_apps.theme import legacy_theme_style
 
 
 @dataclass
@@ -377,6 +378,16 @@ def set_environment(config):
         current_file_path=__file__
     )
 
+def messenger_theme():
+    """The active theme, mapped onto this app's `appearance` CSS variables.
+
+    Empty on the default theme. Rendered into the page body (not `app.hdrs`)
+    so it lands after `env_styles`, which it has to override, and so live
+    `reconfigure` theme swaps take effect.
+    """
+    return legacy_theme_style(app.config, "messenger")
+
+
 def populate_database(config, db):
     """Adds chat history to database"""
     chat_history = config.messenger.chat_history
@@ -527,6 +538,7 @@ def index():
     )
 
     return Div(
+        messenger_theme(),
         logo_title_container,
         page
     )
@@ -633,6 +645,7 @@ def index(user_id: str):
     )
 
     return Div(
+        messenger_theme(),
         logo_title_container,
         page
     )
diff --git a/src/open_apps/apps/start_page/helper.py b/src/open_apps/apps/start_page/helper.py
index 203da42d..5b827044 100644
--- a/src/open_apps/apps/start_page/helper.py
+++ b/src/open_apps/apps/start_page/helper.py
@@ -300,14 +300,17 @@ def __init__(self, content):
     def __str__(self):
         return self.content
 
-def PageWrapper(title, *content, config=None):
+def PageWrapper(title, *content, config=None, theme_css=""):
     """
     Create a page wrapper with custom styling from configuration.
-    
+
     Args:
         title: Page title
         *content: Content elements
         config: Configuration dictionary with styling options
+        theme_css: Shared design-token CSS from ``open_apps.theme``. Emitted
+            last so it overrides the appearance-derived rules above it; empty
+            unless a non-default theme is selected.
     """
     # Set defaults if config is None
     if config is None:
@@ -547,6 +550,8 @@ def PageWrapper(title, *content, config=None):
             }}
             
             {custom_css}
+
+            {theme_css}
         </style>
         <script>
             function showModal(id) {{
diff --git a/src/open_apps/apps/start_page/main.py b/src/open_apps/apps/start_page/main.py
index 2f8fb3b6..b75fb778 100644
--- a/src/open_apps/apps/start_page/main.py
+++ b/src/open_apps/apps/start_page/main.py
@@ -34,6 +34,7 @@
         generate_random_colors,
     )
 from omegaconf import DictConfig, OmegaConf
+from open_apps.theme import legacy_theme_css
 
 # Define available apps and their route getters
 AVAILABLE_APPS = {
@@ -324,7 +325,15 @@ def get():
     )
     
     # Return the page with configuration
-    return PageWrapper("main-page", wrapper, footer(), config=config)
+    return PageWrapper(
+        "main-page",
+        wrapper,
+        footer(),
+        config=config,
+        # Resolved per-request so live `reconfigure` theme swaps take effect;
+        # empty string on the default theme.
+        theme_css=legacy_theme_css(app.config, "start_page"),
+    )
 
 
 @rt("/environment_variables")
diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index 54f60757..abe99f38 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -14,7 +14,8 @@
 
 Selection is done with Hydra overrides:
 
-* ``+apps/theme=solarized``      -> global default for every app (requires adding the group if not in defaults)
+* ``apps/theme=solarized``       -> global default for every app (the
+  ``apps/theme`` group is in ``config/config.yaml``'s defaults list)
 * ``apps.todo.theme=solarized``  -> override a single app (falls back to
   the global theme when the app's ``theme`` field is null/unset)
 
@@ -34,6 +35,11 @@
 The ``tokens`` mapping is open-ended: every ``key: value`` becomes the CSS
 custom property ``--key: value``, so apps can introduce new tokens without
 touching this module.
+
+Apps that have not been migrated to design tokens yet (everything except
+todo) still build their stylesheet from ``config/apps/<app>/appearance/``.
+:func:`legacy_theme_css` bridges the two worlds — see the comment on
+``_LEGACY_ALIASES`` below.
 """
 from __future__ import annotations
 
@@ -102,7 +108,7 @@ def resolve_theme(apps_config, app_name: str) -> dict:
     return load_theme(_DEFAULT_THEME)
 
 
-def render_theme_tokens(theme: dict) -> Style:
+def render_theme_css(theme: dict) -> str:
     """Build the ``:root`` CSS-variable block (plus optional import) for a theme.
 
     ``theme`` is the dict returned by :func:`resolve_theme` / :func:`load_theme`.
@@ -126,8 +132,12 @@ def render_theme_tokens(theme: dict) -> Style:
         import_url = ""
 
     import_rule = f'@import url("{import_url}");\n' if import_url else ""
-    css = f"{import_rule}:root {{\n{lines}\n}}"
-    return Style(css)
+    return f"{import_rule}:root {{\n{lines}\n}}"
+
+
+def render_theme_tokens(theme: dict) -> Style:
+    """:func:`render_theme_css` wrapped in a FastHTML ``Style`` element."""
+    return Style(render_theme_css(theme))
 
 
 def theme_style(apps_config, app_name: str) -> Style:
@@ -136,3 +146,113 @@ def theme_style(apps_config, app_name: str) -> Style:
     Call this per-request so live ``reconfigure`` theme swaps take effect.
     """
     return render_theme_tokens(resolve_theme(apps_config, app_name))
+
+
+# --------------------------------------------------------------------------
+# Bridge for apps that still render `config/apps/<app>/appearance/*.yaml`
+# --------------------------------------------------------------------------
+#
+# Only the todo app has been rewritten against design tokens. The other apps
+# build a `:root` block of their own from their `appearance` config and read
+# those names throughout their stylesheets, so a theme selection was invisible
+# to them. Rewriting five stylesheets is a much larger change than this one;
+# until then, re-point the legacy custom properties at the shared tokens.
+#
+# Keys are the legacy custom-property names those apps declare; values are the
+# token they should follow. `--font-family` needs no entry: the theme declares
+# that name itself, and the bridge block is emitted after the app's own
+# stylesheet, so the token value already wins.
+_LEGACY_ALIASES: dict[str, str] = {
+    # calendar
+    "primary": "color-primary",
+    "primary-hover": "color-accent",
+    "secondary": "color-neutral",
+    "background": "color-bg",
+    "text": "color-fg",
+    "error": "color-danger",
+    "border": "color-border",
+    "heading-font": "font-heading",
+    "base-font-size": "font-size-base",
+    "button-border-radius": "radius",
+    # messenger + code editor
+    "custom-font-family": "font-family",
+    "custom-font-size": "font-size-base",
+    "custom-font-color": "color-fg",
+    "custom-background-color": "color-bg",
+    "chat-font-family": "font-family",
+    "chat-font-size": "font-size-base",
+    "chat-font-color": "color-fg",
+    "chat-header-font-color": "color-muted",
+    "chat-primary-bubble-color": "color-primary",
+    "chat-secondary-bubble-color": "color-surface",
+    "chat-display-background-color": "color-bg",
+    "main-bg-color": "color-surface",
+}
+
+# The page chrome every app shares. Aliasing alone is not enough: an app only
+# picks up a token where its own CSS happens to use a variable, and several
+# paint the page from hard-coded values.
+_LEGACY_BASE_CSS = """
+html, body {
+  background-color: var(--color-bg);
+  color: var(--color-fg);
+  font-family: var(--font-family);
+}
+"""
+
+# Per-app selectors whose colors are hard-coded in the app's stylesheet (so no
+# alias can reach them) but which cover enough of the page that leaving them
+# unthemed reads as "the theme did nothing".
+_LEGACY_APP_CSS: dict[str, str] = {
+    "maps": """
+#sidebar { background: var(--color-surface); }
+#sidebar h2, #sidebar h3 { color: var(--color-fg); }
+.popup-list-item, .route-result, .saved-place { background: var(--color-surface); }
+""",
+    "code_editor": """
+.main-content { background-color: var(--color-surface); }
+textarea, textarea.styled-content { background-color: var(--color-surface); }
+""",
+    "messenger": """
+.bg-base-100, .bg-base-200 { background-color: var(--color-surface); }
+""",
+    "start_page": """
+#wrapper > .wrapper { background-color: var(--color-bg); }
+""",
+}
+
+
+def legacy_theme_css(apps_config, app_name: str) -> str:
+    """CSS that makes the active theme visible in an app built on ``appearance``.
+
+    Emits the theme's token block, the legacy-variable aliases, and the shared
+    page chrome. Returns ``""`` for the ``default`` theme: unmigrated apps are
+    still described entirely by their ``appearance`` config, so a deployment
+    that never selects a theme must render exactly as it did before.
+
+    Emit the result *after* the app's own stylesheet — the bridge relies on
+    document order, not specificity, to win.
+    """
+    theme = resolve_theme(apps_config, app_name)
+    if str(theme.get("name", _DEFAULT_THEME)) == _DEFAULT_THEME:
+        return ""
+
+    tokens = _as_plain(theme.get("tokens", {}))
+    aliases = "\n".join(
+        f"  --{legacy}: var(--{token});"
+        for legacy, token in _LEGACY_ALIASES.items()
+        if token in tokens
+    )
+    return "\n".join(
+        [
+            render_theme_css(theme),
+            f":root {{\n{aliases}\n}}",
+            _LEGACY_BASE_CSS,
+            _LEGACY_APP_CSS.get(app_name, ""),
+        ]
+    )
+
+
+def legacy_theme_style(apps_config, app_name: str) -> Style:
+    """:func:`legacy_theme_css` as a FastHTML ``Style`` (empty on the default theme)."""
+    return Style(legacy_theme_css(apps_config, app_name))
diff --git a/tests/save_screenshots.py b/tests/save_screenshots.py
index eceefba7..13f9eec9 100644
--- a/tests/save_screenshots.py
+++ b/tests/save_screenshots.py
@@ -61,36 +61,54 @@ class ComparisonResult:
 )
 
 
+THEME_DIR = REPO_ROOT / "config" / "apps" / "theme"
+
+# The todo app no longer has an `appearance` group -- it renders from the shared
+# design tokens, so its counterpart to an appearance variant is a theme name.
+# Everything else still composes `config/apps/<app>/appearance/`.
+APPEARANCE_APPS = ("start_page", "calendar", "messenger", "maps", "code_editor")
+CONTENT_APPS = ("start_page", "todo", "calendar", "messenger", "maps", "code_editor")
+TODO_THEME_FOR_APPEARANCE = {
+    "dark_theme": "dark",
+    "challenging_font": "challenging_font",
+}
+
+
+def available_themes() -> list[str]:
+    """Theme stems under ``config/apps/theme/``, default first."""
+    stems = sorted(path.stem for path in THEME_DIR.glob("*.yaml"))
+    return ["default"] + [stem for stem in stems if stem != "default"]
+
+
+def appearance_variation(name: str, onlineshop_overrides: list[str]) -> list[str]:
+    apps = list(APPEARANCE_APPS) + (["onlineshop"] if onlineshop_overrides else [])
+    return (
+        onlineshop_overrides
+        + [f"apps/{app_name}/appearance={name}" for app_name in apps]
+        + [f"apps.todo.theme={TODO_THEME_FOR_APPEARANCE[name]}"]
+    )
+
+
 def build_variation_overrides(include_onlineshop: bool) -> dict[str, list[str]]:
-    appearance_apps = [
-        "start_page",
-        "todo",
-        "calendar",
-        "messenger",
-        "maps",
-        "code_editor",
-    ]
-    content_apps = list(appearance_apps)
     onlineshop_overrides = ["apps.onlineshop.enable=True"] if include_onlineshop else []
+    content_apps = list(CONTENT_APPS) + (["onlineshop"] if include_onlineshop else [])
 
-    if include_onlineshop:
-        appearance_apps.append("onlineshop")
-        content_apps.append("onlineshop")
-
-    return {
+    variations = {
         "default": onlineshop_overrides,
-        "dark_theme": onlineshop_overrides
-        + [f"apps/{app_name}/appearance=dark_theme" for app_name in appearance_apps],
-        "challenging_font": onlineshop_overrides
-        + [
-            f"apps/{app_name}/appearance=challenging_font"
-            for app_name in appearance_apps
-        ],
+        "dark_theme": appearance_variation("dark_theme", onlineshop_overrides),
+        "challenging_font": appearance_variation(
+            "challenging_font", onlineshop_overrides
+        ),
         "german": onlineshop_overrides
         + [f"apps/{app_name}/content=german" for app_name in content_apps],
         "long_descriptions": onlineshop_overrides
         + [f"apps/{app_name}/content=long_descriptions" for app_name in content_apps],
     }
+    # One variation per shared theme, named `theme_<stem>`, so a single
+    # `apps/theme=` override can be captured across every app at once.
+    for theme in available_themes():
+        variations[f"theme_{theme}"] = onlineshop_overrides + [f"apps/theme={theme}"]
+    return variations
 
 
 def parse_args() -> argparse.Namespace:
@@ -122,13 +140,9 @@ def parse_args() -> argparse.Namespace:
         "--variation",
         dest="variations",
         nargs="*",
-        choices=[
-            "default",
-            "dark_theme",
-            "challenging_font",
-            "german",
-            "long_descriptions",
-        ],
+        # `theme_*` entries are opt-in: they are not part of the reference set,
+        # they exist so the docs gallery can be regenerated with one command.
+        choices=sorted(build_variation_overrides(include_onlineshop=False)),
         default=[
             "default",
             "dark_theme",

From 30978adc5cc2c26859cef632a95a2de2bfeab5b8 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Mon, 31 Aug 2026 20:02:01 -0400
Subject: [PATCH 09/23] [Fix] Default theme should be sans-serif, not Times New
 Roman

The default theme's font-family token was "'Times New Roman', serif", so
every app migrated to design tokens (todo, and the online shop) rendered in
the browser's serif while the appearance-based apps kept the Arial they had
always used. The two looked like different products side by side.

Point the token at the same sans stack the appearance configs used. Varying
the font deliberately is what the `mono` and `challenging_font` themes are for.

Test plan: uv run -m pytest tests/ -> 724 passed, 7 skipped.
---
 config/apps/theme/default.yaml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/config/apps/theme/default.yaml b/config/apps/theme/default.yaml
index e10a9381..99eb7a45 100644
--- a/config/apps/theme/default.yaml
+++ b/config/apps/theme/default.yaml
@@ -16,7 +16,11 @@ tokens:
   color-danger: "#b22222"      # remove / destructive
   color-neutral: "#36454f"     # edit / secondary
   color-btn-fg: "#ffffff"      # text on edit/remove/save buttons
-  font-family: "'Times New Roman', serif"
+  # Matches the sans-serif the appearance-based apps have always used
+  # (`font_family: 'Arial'`), so the `default` theme looks like the app did
+  # before it was migrated to tokens rather than falling back to the browser's
+  # serif. Pick `mono` or `challenging_font` to vary this deliberately.
+  font-family: "system-ui, -apple-system, 'Helvetica Neue', Arial, sans-serif"
   font-heading: "inherit"
   font-size-base: "16px"
   radius: "8px"

From baf487e0ef1b31b576afcb0cc5e038c88fc73460 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Tue, 1 Sep 2026 10:49:51 -0400
Subject: [PATCH 10/23] [Fix] Exclude internal-* docs from the mkdocs build

mkdocs renders every page it finds under docs/, not just the ones listed
in nav. docs/internal-*.md are untracked by design (.gitignore line 201),
but a plain `mkdocs build` was rendering them into site/ -- and inlining
their full text into site/search/search_index.json and their URLs into
site/sitemap.xml, both of which *are* tracked and both of which push to a
public remote.

The .gitignore rule covers the generated site/internal-* pages themselves
but cannot help with the two index files, since those are single tracked
blobs that mix internal and public content.
---
 mkdocs.yml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index a3db8a1f..392a268f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,6 +13,15 @@ theme:
 site_url: https://facebookresearch.github.io/OpenApps/
 repo_url: https://github.com/facebookresearch/OpenApps
 
+# `docs/internal-*.md` are untracked by design (.gitignore line 201), but mkdocs
+# builds every page it finds, not just the ones in `nav`. Without this, a plain
+# `mkdocs build` renders them into `site/` and -- worse -- inlines their full
+# text into `site/search/search_index.json` and their URLs into
+# `site/sitemap.xml`, both of which *are* tracked and both of which push to a
+# public remote.
+exclude_docs: |
+  internal-*.md
+
 nav:
   - Start: index.md
   - Manual Installation: installation.md

From 5c267afa5ebd86f26df440a661aabd44eea7860a Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Tue, 1 Sep 2026 10:50:20 -0400
Subject: [PATCH 11/23] [Improvement] Replace per-app appearance with a shared
 theme + per-app layout

Roll the theme/layout split out to every app and delete the `appearance`
group. Previously only todo rendered from design tokens; the other six
apps built their own `:root` block from `config/apps/<app>/appearance/`,
and `legacy_theme_css()` re-pointed those variables at the shared tokens
so a theme selection was at least partly visible. Both are now gone.

`appearance` was conflating three separate things, so each key moved to
where it belongs:

  * look      -> shared design tokens in `config/apps/theme/` (global)
  * structure -> per-app `config/apps/<app>/layout/`
  * behaviour -> plain keys in `config/apps/<app>/default.yaml`
                 (maps zoom/granularity/allow_planning, code editor
                 mode/highlight/sort_feature, shop enable/credit cards)

One `apps/theme=dark` now themes all seven apps; the dark variation in
`config_parallel_tasks.yaml` drops from six overrides to one.

Themes carry an app-agnostic `assets` block (`tone`, `icon_set`) for the
choices a CSS variable cannot reach -- the start page's raster icons, the
Leaflet tile layer, the CodeMirror stylesheet. Each app maps `tone` onto
its own concrete asset, so a shared theme file never has to grow a key
per app. Without it, `apps/theme=dark` would leave a bright OpenStreetMap
basemap and a light `eclipse` editor pane inside dark chrome.

Fixed along the way:

  * `apps.code_editor.theme` silently clobbered CodeMirror's theme. Both
    the per-app design-token override and CodeMirror's stylesheet were
    named `theme`, and the override won, so the editor initialised with
    `theme: 'None'`. CodeMirror's is now `editor_theme`.
  * `dark` and `mono` were unusable as global themes -- literal ports of
    todo's old local variant, `dark` had a white `color-bg` *and* a white
    `color-fg`, `mono` was black on black. Invisible while only todo read
    the tokens, broken the moment six more apps did.
  * `layers['{{ default_layer }}'].addTo(map)` threw a TypeError on an
    unknown layer name, aborting the rest of the script and leaving a
    blank map with no landmarks or sidebar wiring. Now falls back.
  * `font-size: "{{ base_font_size }}"` in map.html was quoted, so it was
    invalid CSS and the setting never applied.
  * A missing semicolon in map.html's `.search-btn` swallowed the next
    declaration.

Also adds a `colorblind` theme (generalised from the code editor's
`colorblind_access` variant), a greyscale `CartoDB Positron` basemap for
`mono`, and a test that every theme declares the same token vocabulary --
an app uses `var(--token)` without knowing which theme is active, so a
missing token renders as an empty value rather than a loud failure.

Note the reference screenshots need regenerating: `save_screenshots.py`
now captures `theme_*` and `layout_*` variations instead of the old
appearance names.

Test plan: `uv run -m pytest tests/` -> 732 passed, 7 skipped (was 724/7;
+8 new theme/asset tests). ruff unchanged at 292 pre-existing errors with
an identical rule histogram. Served all six routes under `dark` and
`mono` and checked the emitted CSS: correct tokens everywhere, no stale
variables, no unrendered Jinja placeholders; `broken_logos` confirmed
detaching icons from their labels.
---
 .../calendar/appearance/black_and_white.yaml  |  31 --
 .../calendar/appearance/challenging_font.yaml |  30 --
 .../apps/calendar/appearance/dark_theme.yaml  |  32 --
 config/apps/calendar/appearance/default.yaml  |  30 --
 config/apps/calendar/default.yaml             |   2 +-
 config/apps/calendar/layout/default.yaml      |  13 +
 .../appearance/black_and_white.yaml           |  26 --
 .../appearance/challenging_font.yaml          |  34 --
 .../appearance/colorblind_access.yaml         |  34 --
 .../code_editor/appearance/dark_theme.yaml    |  33 --
 .../apps/code_editor/appearance/default.yaml  |  34 --
 config/apps/code_editor/default.yaml          |  44 ++-
 config/apps/code_editor/layout/default.yaml   |   4 +
 .../apps/maps/appearance/black_and_white.yaml |  18 -
 .../maps/appearance/challenging_font.yaml     |  14 -
 config/apps/maps/appearance/dark_theme.yaml   |  18 -
 config/apps/maps/appearance/default.yaml      |  15 -
 config/apps/maps/default.yaml                 |  23 +-
 config/apps/maps/layout/default.yaml          |   4 +
 .../messenger/appearance/black_and_white.yaml |  14 -
 .../appearance/challenging_font.yaml          |  14 -
 .../apps/messenger/appearance/dark_theme.yaml |  13 -
 config/apps/messenger/appearance/default.yaml |  13 -
 config/apps/messenger/default.yaml            |   4 +-
 config/apps/messenger/layout/default.yaml     |   4 +
 .../appearance/black_and_white.yaml           |  17 -
 .../appearance/challenging_font.yaml          |  14 -
 .../onlineshop/appearance/dark_theme.yaml     |  17 -
 .../apps/onlineshop/appearance/default.yaml   |  14 -
 config/apps/onlineshop/default.yaml           |  19 +-
 config/apps/onlineshop/layout/default.yaml    |   4 +
 .../appearance/black_and_white.yaml           |  72 ----
 .../appearance/challenging_font.yaml          |  72 ----
 .../start_page/appearance/dark_theme.yaml     |  72 ----
 .../apps/start_page/appearance/default.yaml   |  72 ----
 config/apps/start_page/default.yaml           |   2 +-
 .../apps/start_page/layout/broken_logos.yaml  |   9 +
 .../clickable_logos.yaml                      |   6 +-
 .../broken_logos.yaml => layout/default.yaml} |  43 ++-
 config/apps/theme/bootstrap.yaml              |   7 +
 config/apps/theme/challenging_font.yaml       |  15 +-
 config/apps/theme/colorblind.yaml             |  31 ++
 config/apps/theme/dark.yaml                   |  39 ++-
 config/apps/theme/default.yaml                |  24 +-
 config/apps/theme/material.yaml               |   7 +
 config/apps/theme/mono.yaml                   |  21 +-
 config/apps/theme/solarized.yaml              |   7 +
 config/config_parallel_tasks.yaml             |  12 +-
 docs/index.md                                 |  69 +++-
 site/agents/index.html                        | 121 +++++++
 site/index.html                               | 120 ++++++-
 site/index.md                                 | 112 +++++-
 site/search/search_index.json                 |   2 +-
 site/sitemap.xml                              |  30 +-
 site/sitemap.xml.gz                           | Bin 249 -> 248 bytes
 site/tasks/index.html                         |  46 ++-
 src/open_apps/apps/calendar_app/main.py       | 321 +++++++++---------
 src/open_apps/apps/codeeditor_app/main.py     | 162 +++++----
 src/open_apps/apps/map_app/main.py            |  37 +-
 src/open_apps/apps/map_app/templates/map.html | 105 +++---
 src/open_apps/apps/messenger_app/main.py      | 159 ++++-----
 src/open_apps/apps/onlineshop_app/main.py     |   2 +-
 .../onlineshop_app/models/global_state.py     |   6 +-
 .../templates/html_generator.py               |  59 ++--
 src/open_apps/apps/start_page/helper.py       | 101 +++---
 src/open_apps/apps/start_page/main.py         |  69 +++-
 src/open_apps/mcp/README.md                   |   4 +-
 src/open_apps/mcp/appserver.py                |   8 +-
 src/open_apps/mcp/registry.py                 |   2 +-
 src/open_apps/mcp/server.py                   |   9 +-
 src/open_apps/mcp/session.py                  |   2 -
 src/open_apps/theme.py                        | 153 +++------
 tests/save_screenshots.py                     |  44 +--
 tests/test_apps.py                            |   6 +-
 tests/test_theme.py                           |  61 +++-
 75 files changed, 1395 insertions(+), 1512 deletions(-)
 delete mode 100644 config/apps/calendar/appearance/black_and_white.yaml
 delete mode 100644 config/apps/calendar/appearance/challenging_font.yaml
 delete mode 100644 config/apps/calendar/appearance/dark_theme.yaml
 delete mode 100644 config/apps/calendar/appearance/default.yaml
 create mode 100644 config/apps/calendar/layout/default.yaml
 delete mode 100644 config/apps/code_editor/appearance/black_and_white.yaml
 delete mode 100644 config/apps/code_editor/appearance/challenging_font.yaml
 delete mode 100644 config/apps/code_editor/appearance/colorblind_access.yaml
 delete mode 100644 config/apps/code_editor/appearance/dark_theme.yaml
 delete mode 100644 config/apps/code_editor/appearance/default.yaml
 create mode 100644 config/apps/code_editor/layout/default.yaml
 delete mode 100644 config/apps/maps/appearance/black_and_white.yaml
 delete mode 100644 config/apps/maps/appearance/challenging_font.yaml
 delete mode 100644 config/apps/maps/appearance/dark_theme.yaml
 delete mode 100644 config/apps/maps/appearance/default.yaml
 create mode 100644 config/apps/maps/layout/default.yaml
 delete mode 100644 config/apps/messenger/appearance/black_and_white.yaml
 delete mode 100644 config/apps/messenger/appearance/challenging_font.yaml
 delete mode 100644 config/apps/messenger/appearance/dark_theme.yaml
 delete mode 100644 config/apps/messenger/appearance/default.yaml
 create mode 100644 config/apps/messenger/layout/default.yaml
 delete mode 100644 config/apps/onlineshop/appearance/black_and_white.yaml
 delete mode 100644 config/apps/onlineshop/appearance/challenging_font.yaml
 delete mode 100644 config/apps/onlineshop/appearance/dark_theme.yaml
 delete mode 100644 config/apps/onlineshop/appearance/default.yaml
 create mode 100644 config/apps/onlineshop/layout/default.yaml
 delete mode 100644 config/apps/start_page/appearance/black_and_white.yaml
 delete mode 100644 config/apps/start_page/appearance/challenging_font.yaml
 delete mode 100644 config/apps/start_page/appearance/dark_theme.yaml
 delete mode 100644 config/apps/start_page/appearance/default.yaml
 create mode 100644 config/apps/start_page/layout/broken_logos.yaml
 rename config/apps/start_page/{appearance => layout}/clickable_logos.yaml (57%)
 rename config/apps/start_page/{appearance/broken_logos.yaml => layout/default.yaml} (64%)
 create mode 100644 config/apps/theme/colorblind.yaml

diff --git a/config/apps/calendar/appearance/black_and_white.yaml b/config/apps/calendar/appearance/black_and_white.yaml
deleted file mode 100644
index dc59e26b..00000000
--- a/config/apps/calendar/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,31 +0,0 @@
-# @package apps.calendar
-
-# UI styling configuration - Black and White Theme
-style:
-  # Color scheme (strictly black, white, and grays)
-  colors:
-    primary: '#ffffff'          # White for primary elements
-    primary_hover: '#dddddd'    # Light gray for hover states
-    secondary: '#aaaaaa'        # Medium gray for secondary elements
-    background: '#000000'       # Pure black background
-    text: '#ffffff'             # White text
-    error: '#ffffff'            # White for errors (with different styling)
-    border: '#444444'           # Dark gray borders
-
-  # Typography
-  typography:
-    font_family: 'Inter, system-ui, sans-serif'
-    heading_font: 'Inter, system-ui, sans-serif'
-    base_font_size: '16px'
-    heading_size: '2rem'        # Larger headings for clear hierarchy
-
-  # Button styles
-  buttons:
-    border_radius: '0px'        # Sharp corners for distinct elements
-    padding: '0.5rem 1rem'
-
-  # Layout
-  layout:
-    container_width: '92%'
-    spacing: '1.5rem'           # More spacing for clear separation
-
diff --git a/config/apps/calendar/appearance/challenging_font.yaml b/config/apps/calendar/appearance/challenging_font.yaml
deleted file mode 100644
index e2dc360b..00000000
--- a/config/apps/calendar/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,30 +0,0 @@
-# @package apps.calendar
-
-# UI styling configuration
-style:
-  # Color scheme
-  colors:
-    primary: '#1095c1'          # Primary color for buttons, links, etc.
-    primary_hover: '#0a6d8a'    # Hover state for primary elements
-    secondary: '#6c757d'        # Secondary color for less important elements
-    background: '#ffffff'       # Main background color
-    text: '#212529'             # Main text color
-    error: '#dc3545'            # Error messages color
-    border: '#ced4da'           # Border color
-
-  # Typography
-  typography:
-    font_family: 'Brush Script MT'   # Main font family 
-    heading_font: 'Brush Script MT'  # Font for headings
-    base_font_size: '16px'      # Base font size
-    heading_size: '1.5rem'      # Size for headings
-
-  # Button styles
-  buttons:
-    border_radius: '0.375rem'   # Border radius for buttons
-    padding: '0.5rem 1rem'      # Button padding
-
-  # Layout
-  layout:
-    container_width: '100%'     # Width of the main container
-    spacing: '1rem'             # Standard spacing between elements
diff --git a/config/apps/calendar/appearance/dark_theme.yaml b/config/apps/calendar/appearance/dark_theme.yaml
deleted file mode 100644
index bbf1e367..00000000
--- a/config/apps/calendar/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,32 +0,0 @@
-# @package apps.calendar
-
-
-# UI styling configuration - Dark Theme
-style:
-  # Color scheme
-  colors:
-    primary: '#bb86fc'          # Light purple
-    primary_hover: '#3700b3'    # Darker purple for hover states
-    secondary: '#03dac6'        # Teal secondary
-    background: '#121212'       # Very dark gray background
-    text: '#ffffff'             # White text
-    error: '#cf6679'            # Pink-red for errors
-    border: '#2d2d2d'           # Dark borders
-
-  # Typography
-  typography:
-    font_family: 'Inter, system-ui, sans-serif'  # Modern font
-    heading_font: 'Inter, system-ui, sans-serif' # Same font for consistency
-    base_font_size: '16px'                       # Standard size
-    heading_size: '1.75rem'                      # Slightly smaller headings for dark theme
-
-  # Button styles
-  buttons:
-    border_radius: '4px'        # More square buttons
-    padding: '0.5rem 1rem'      # Standard padding
-
-  # Layout
-  layout:
-    container_width: '95%'      # Wide container
-    spacing: '1rem'             # Standard spacing
-    
\ No newline at end of file
diff --git a/config/apps/calendar/appearance/default.yaml b/config/apps/calendar/appearance/default.yaml
deleted file mode 100644
index 747b0fab..00000000
--- a/config/apps/calendar/appearance/default.yaml
+++ /dev/null
@@ -1,30 +0,0 @@
-# @package apps.calendar
-
-# UI styling configuration
-style:
-  # Color scheme
-  colors:
-    primary: '#1095c1'          # Primary color for buttons, links, etc.
-    primary_hover: '#0a6d8a'    # Hover state for primary elements
-    secondary: '#6c757d'        # Secondary color for less important elements
-    background: '#ffffff'       # Main background color
-    text: '#212529'             # Main text color
-    error: '#dc3545'            # Error messages color
-    border: '#ced4da'           # Border color
-
-  # Typography
-  typography:
-    font_family: 'sans-serif'   # Main font family 
-    heading_font: 'sans-serif'  # Font for headings
-    base_font_size: '16px'      # Base font size
-    heading_size: '1.5rem'      # Size for headings
-
-  # Button styles
-  buttons:
-    border_radius: '0.375rem'   # Border radius for buttons
-    padding: '0.5rem 1rem'      # Button padding
-
-  # Layout
-  layout:
-    container_width: '100%'     # Width of the main container
-    spacing: '1rem'             # Standard spacing between elements
diff --git a/config/apps/calendar/default.yaml b/config/apps/calendar/default.yaml
index f72c0b97..71b5edc7 100644
--- a/config/apps/calendar/default.yaml
+++ b/config/apps/calendar/default.yaml
@@ -1,6 +1,6 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
 database_path: ${databases_dir}/calendar.db
 
diff --git a/config/apps/calendar/layout/default.yaml b/config/apps/calendar/layout/default.yaml
new file mode 100644
index 00000000..0b7faa01
--- /dev/null
+++ b/config/apps/calendar/layout/default.yaml
@@ -0,0 +1,13 @@
+# @package apps.calendar
+# Structure only -- colors, fonts and radii come from the shared theme
+# (`config/apps/theme/`). Select with `apps/calendar/layout=<name>`.
+layout: default
+
+# Width of #calendar-container. Narrower values letterbox the month grid,
+# which changes how much of it fits above the fold for an agent.
+container_width: '100%'
+# Vertical rhythm between the nav, grid and agenda blocks.
+spacing: '1rem'
+# Button hit area. Kept out of the theme because it changes click targets,
+# not appearance.
+button_padding: '0.5rem 1rem'
diff --git a/config/apps/code_editor/appearance/black_and_white.yaml b/config/apps/code_editor/appearance/black_and_white.yaml
deleted file mode 100644
index d96bed78..00000000
--- a/config/apps/code_editor/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,26 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Arial"
-fontcolor: "#000000"
-primary_button_color: "#ffffff"
-secondary_button_color: "#ffffff"
-danger_button_color: "#ffffff"
-textarea_background_color: "#ffffff"
-
-theme: "monokai"
-mode: "python"
-highlight: False
-sort_feature: True
-
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
\ No newline at end of file
diff --git a/config/apps/code_editor/appearance/challenging_font.yaml b/config/apps/code_editor/appearance/challenging_font.yaml
deleted file mode 100644
index 58c07ebb..00000000
--- a/config/apps/code_editor/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,34 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Brush Script MT"
-fontcolor: ""
-primary_button_color: "#ffffff"
-secondary_button_color: "#ffffff"
-danger_button_color: "#D0021B"
-textarea_background_color: "#ffffff"
-main_background_color: "#90D5FF"
-
-theme: "monokai"
-mode: "python"
-highlight: False
-sort_feature: True
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
-  - eclipse
-  - solarized
-  - seti
-  - night
-  - dracula
-  - twilight
-  - zenburn
-  - material
\ No newline at end of file
diff --git a/config/apps/code_editor/appearance/colorblind_access.yaml b/config/apps/code_editor/appearance/colorblind_access.yaml
deleted file mode 100644
index 0679e9ab..00000000
--- a/config/apps/code_editor/appearance/colorblind_access.yaml
+++ /dev/null
@@ -1,34 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Arial"
-fontcolor: ""
-primary_button_color: "#DC267F"
-secondary_button_color: "#DC267F"
-danger_button_color: "#FE6100"
-textarea_background_color: "#FFFFFF"
-main_background_color: "#648FFF"
-
-theme: "monokai"
-mode: "python"
-highlight: False
-sort_feature: True
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
-  - eclipse
-  - solarized
-  - seti
-  - night
-  - dracula
-  - twilight
-  - zenburn
-  - material
\ No newline at end of file
diff --git a/config/apps/code_editor/appearance/dark_theme.yaml b/config/apps/code_editor/appearance/dark_theme.yaml
deleted file mode 100644
index 0a436122..00000000
--- a/config/apps/code_editor/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,33 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Arial"
-fontcolor: ""
-primary_button_color: "#4A90E2"
-secondary_button_color: "#50E3C2"
-danger_button_color: "#D0021B"
-textarea_background_color: "#2d2d2d"
-
-theme: "monokai"
-mode: "python"
-highlight: False
-sort_feature: True
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
-  - eclipse
-  - solarized
-  - seti
-  - night
-  - dracula
-  - twilight
-  - zenburn
-  - material
diff --git a/config/apps/code_editor/appearance/default.yaml b/config/apps/code_editor/appearance/default.yaml
deleted file mode 100644
index c29d6834..00000000
--- a/config/apps/code_editor/appearance/default.yaml
+++ /dev/null
@@ -1,34 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Arial"
-fontcolor: ""
-primary_button_color: "#ffffff"
-secondary_button_color: "#ffffff"
-danger_button_color: "#D0021B"
-textarea_background_color: "#ffffff"
-main_background_color: "#90D5FF"
-
-theme: "eclipse"
-mode: "python"
-highlight: False
-sort_feature: True
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
-  - eclipse
-  - solarized
-  - seti
-  - night
-  - dracula
-  - twilight
-  - zenburn
-  - material
\ No newline at end of file
diff --git a/config/apps/code_editor/default.yaml b/config/apps/code_editor/default.yaml
index eab65447..bd93b384 100644
--- a/config/apps/code_editor/default.yaml
+++ b/config/apps/code_editor/default.yaml
@@ -1,9 +1,51 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
 database_path: ${databases_dir}/codeeditor
 
 # Per-app theme override. null = inherit the global `apps/theme` selection.
 # Override for just this app with `apps.code_editor.theme=solarized`.
+#
+# Note this is the *shared* theme, not CodeMirror's -- the syntax-highlighting
+# stylesheet is `editor_theme` below. The two were both called `theme` until
+# the appearance groups were removed, and the per-app override silently won,
+# leaving CodeMirror initialised with `theme: 'None'`.
 theme: null
+
+# --- Behaviour -------------------------------------------------------------
+
+# CodeMirror syntax-highlighting stylesheet, loaded by name from the CDN.
+# It is a whole stylesheet rather than a set of variables, so the shared
+# theme selects one via its `tone` (see `editor_theme_by_tone`).
+editor_theme: "eclipse"
+editor_theme_by_tone:
+  dark: "monokai"
+  mono: "eclipse"
+# Language mode the editor starts in.
+mode: "python"
+# Load CodeMirror at all. False renders a plain <textarea> -- a meaningfully
+# different observation for an agent, so it is behaviour, not appearance.
+highlight: False
+# Sort the mode/theme dropdowns alphabetically instead of config order.
+sort_feature: True
+
+list_of_modes:
+  - python
+  - javascript
+  - css
+  - yaml
+  - markdown
+  - shell
+  - clike
+  - go
+list_of_themes:
+  - monokai
+  - eclipse
+  - solarized
+  - seti
+  - night
+  - dracula
+  - twilight
+  - zenburn
+  - material
diff --git a/config/apps/code_editor/layout/default.yaml b/config/apps/code_editor/layout/default.yaml
new file mode 100644
index 00000000..4c82aff4
--- /dev/null
+++ b/config/apps/code_editor/layout/default.yaml
@@ -0,0 +1,4 @@
+# @package apps.code_editor
+# Structure only -- colors and fonts come from the shared theme
+# (`config/apps/theme/`). Select with `apps/code_editor/layout=<name>`.
+layout: default
diff --git a/config/apps/maps/appearance/black_and_white.yaml b/config/apps/maps/appearance/black_and_white.yaml
deleted file mode 100644
index e5930a10..00000000
--- a/config/apps/maps/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-# @package apps.maps
-
-enable_layer_control: True
-default_layer: 'CartoDB Dark'
-popup_display_rule: 'automatic'
-font_family: 'Arial'
-base_font_size: '16px'
-search_button_color: '#000000'
-delete_button_color: '#000000'
-return_button_color: '#000000'
-calculate_button_color: '#000000'
-delete_button_hover_color: '#000000'
-search_button_hover_color: '#000000'
-calculate_button_hover_color: '#000000'
-
-zoom: 12
-granularity: 'coarse'
-allow_planning: False
\ No newline at end of file
diff --git a/config/apps/maps/appearance/challenging_font.yaml b/config/apps/maps/appearance/challenging_font.yaml
deleted file mode 100644
index aac4307f..00000000
--- a/config/apps/maps/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.maps
-
-enable_layer_control: True
-default_layer: 'OpenStreetMap'
-popup_display_rule: 'automatic'
-font_family: 'Brush Script MT'
-base_font_size: '16px'
-search_button_color: '#e74c3c'
-delete_button_color: '#3498db'
-return_button_color: '#95a5a6'
-zoom: 12
-granularity: 'coarse'
-allow_planning: False
-calculate_button_color: '#e74c3c'
\ No newline at end of file
diff --git a/config/apps/maps/appearance/dark_theme.yaml b/config/apps/maps/appearance/dark_theme.yaml
deleted file mode 100644
index 15c74ede..00000000
--- a/config/apps/maps/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-# @package apps.maps
-
-enable_layer_control: True
-default_layer: 'CartoDB Dark'
-popup_display_rule: 'automatic'
-font_family: 'Comic Sans MS'
-base_font_size: '16px'
-search_button_color: '#bb86fc'
-delete_button_color: '#03dac6'
-return_button_color: '#000000'
-calculate_button_color: '#bb86fc'
-delete_button_hover_color: '#000000'
-search_button_hover_color: '#3700b3'
-calculate_button_hover_color: '#3700b3'
-sidebar_background_color: '#121212'
-zoom: 12
-granularity: 'coarse'
-allow_planning: False
\ No newline at end of file
diff --git a/config/apps/maps/appearance/default.yaml b/config/apps/maps/appearance/default.yaml
deleted file mode 100644
index 639de7ee..00000000
--- a/config/apps/maps/appearance/default.yaml
+++ /dev/null
@@ -1,15 +0,0 @@
-# @package apps.maps
-
-enable_layer_control: True
-default_layer: 'OpenStreetMap'
-popup_display_rule: 'automatic'
-font_family: 'Comic Sans MS'
-base_font_size: '16px'
-search_button_color: '#3498db'
-delete_button_color: '#e74c3c'
-return_button_color: '#95a5a6'
-zoom: 12
-granularity: 'coarse'
-allow_planning: False
-calculate_button_color: '#3498db'
-sidebar_background_color: '#f8f9fa'
\ No newline at end of file
diff --git a/config/apps/maps/default.yaml b/config/apps/maps/default.yaml
index 556829f9..7528a086 100644
--- a/config/apps/maps/default.yaml
+++ b/config/apps/maps/default.yaml
@@ -1,6 +1,6 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
 database_path: ${databases_dir}/maps.db
 otp_url: 'http://localhost:8080/'
@@ -8,3 +8,24 @@ otp_url: 'http://localhost:8080/'
 # Per-app theme override. null = inherit the global `apps/theme` selection.
 # Override for just this app with `apps.maps.theme=solarized`.
 theme: null
+
+# --- Behaviour -------------------------------------------------------------
+# Not layout and not theme: these change what the map *does*, not how it looks.
+
+# Show Leaflet's basemap switcher. Off hides the tile layer from the agent.
+enable_layer_control: True
+# Basemap used on page load. Tiles are raster images from a CDN, so no CSS
+# variable can recolor them -- the theme instead picks one via its `tone`
+# (see `layer_by_tone`). Must name a key defined in templates/map.html.
+default_layer: 'OpenStreetMap'
+# Basemap per theme tone; anything not listed falls back to `default_layer`.
+# This is what makes `apps/theme=dark` darken the map itself and not just
+# the sidebar around it.
+layer_by_tone:
+  dark: 'CartoDB Dark'
+  mono: 'CartoDB Positron'
+# 'automatic' places a styled marker on save; 'diy' leaves styling to the user.
+popup_display_rule: 'automatic'
+zoom: 12
+granularity: 'coarse'
+allow_planning: False
diff --git a/config/apps/maps/layout/default.yaml b/config/apps/maps/layout/default.yaml
new file mode 100644
index 00000000..d56c17cb
--- /dev/null
+++ b/config/apps/maps/layout/default.yaml
@@ -0,0 +1,4 @@
+# @package apps.maps
+# Structure only -- colors and fonts come from the shared theme
+# (`config/apps/theme/`). Select with `apps/maps/layout=<name>`.
+layout: default
diff --git a/config/apps/messenger/appearance/black_and_white.yaml b/config/apps/messenger/appearance/black_and_white.yaml
deleted file mode 100644
index 7ec2c8e5..00000000
--- a/config/apps/messenger/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.messenger
-
-
-font_size: 22
-font: "Inter"
-fontcolor: "black"
-chat_font_size: 16
-chat_font: "Inter"
-chat_fontcolor: "#000000"
-chat_header_fontcolor: "#000000"
-chat_primary_bubble_color: "#ffffff"
-chat_secondary_bubble_color: "#ffffff"
-chat_display_background_color: "#ffffff"
-background_color: "#f0f0f0"
\ No newline at end of file
diff --git a/config/apps/messenger/appearance/challenging_font.yaml b/config/apps/messenger/appearance/challenging_font.yaml
deleted file mode 100644
index 2995433d..00000000
--- a/config/apps/messenger/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.messenger
-
-
-font_size: 22
-font: "Brush Script MT"
-fontcolor: "black"
-chat_font_size: 16
-chat_font: "Brush Script MT"
-chat_fontcolor: "#1A1A1A"
-chat_header_fontcolor: "#333333"
-chat_primary_bubble_color: "#dcf8c6"
-chat_secondary_bubble_color: "#ffffff"
-chat_display_background_color: "#e5ddd5"
-background_color: "#f0f0f0"
\ No newline at end of file
diff --git a/config/apps/messenger/appearance/dark_theme.yaml b/config/apps/messenger/appearance/dark_theme.yaml
deleted file mode 100644
index 993ec117..00000000
--- a/config/apps/messenger/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-# @package apps.messenger
-
-font_size: 22
-font: "Inter"
-fontcolor: "#bb86fc"
-chat_font_size: 16
-chat_font: "Inter"
-chat_fontcolor: "#FFFFFF"
-chat_header_fontcolor: "white"
-chat_primary_bubble_color: "#bb86fc"
-chat_secondary_bubble_color: "#90EE90"
-chat_display_background_color: "#121212"
-background_color: "#121212"
\ No newline at end of file
diff --git a/config/apps/messenger/appearance/default.yaml b/config/apps/messenger/appearance/default.yaml
deleted file mode 100644
index 648937ae..00000000
--- a/config/apps/messenger/appearance/default.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-# @package apps.messenger
-
-font_size: 22
-font: "Inter"
-fontcolor: "black"
-chat_font_size: 16
-chat_font: "Inter"
-chat_fontcolor: "#1A1A1A"
-chat_header_fontcolor: "#333333"
-chat_primary_bubble_color: "#dcf8c6"
-chat_secondary_bubble_color: "#ffffff"
-chat_display_background_color: "#e5ddd5"
-background_color: "#f0f0f0"
\ No newline at end of file
diff --git a/config/apps/messenger/default.yaml b/config/apps/messenger/default.yaml
index 3d80d5e2..cb803ff5 100644
--- a/config/apps/messenger/default.yaml
+++ b/config/apps/messenger/default.yaml
@@ -1,7 +1,7 @@
 defaults:
   - content: default
-  - appearance: default
-  
+  - layout: default
+
 database_path: ${databases_dir}/messenger.db
 
 # Per-app theme override. null = inherit the global `apps/theme` selection.
diff --git a/config/apps/messenger/layout/default.yaml b/config/apps/messenger/layout/default.yaml
new file mode 100644
index 00000000..10ecaf61
--- /dev/null
+++ b/config/apps/messenger/layout/default.yaml
@@ -0,0 +1,4 @@
+# @package apps.messenger
+# Structure only -- colors and fonts come from the shared theme
+# (`config/apps/theme/`). Select with `apps/messenger/layout=<name>`.
+layout: default
diff --git a/config/apps/onlineshop/appearance/black_and_white.yaml b/config/apps/onlineshop/appearance/black_and_white.yaml
deleted file mode 100644
index 048f0d66..00000000
--- a/config/apps/onlineshop/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,17 +0,0 @@
-# @package apps.onlineshop
-
-allowed_credit_cards:
-  - 'Visa'
-  - 'MasterCard'
-  # - 'Amex'
-enable_credit_card_check: false
-enable: False
-
-
-font_family: 'Arial'
-base_font_size: '16px'
-font_color: '#000000'
-background_color: '#FFFFFF'
-button_background_color: '#FFFFFF'
-button_font_color: '#000000'
-highlight_font_color: '#000000'
\ No newline at end of file
diff --git a/config/apps/onlineshop/appearance/challenging_font.yaml b/config/apps/onlineshop/appearance/challenging_font.yaml
deleted file mode 100644
index be0dff65..00000000
--- a/config/apps/onlineshop/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.onlineshop
-
-allowed_credit_cards:
-  - 'Visa'
-  - 'MasterCard'
-  # - 'Amex'
-enable_credit_card_check: false
-enable: False
-
-
-font_family: 'Brush Script MT'
-base_font_size: '16px'
-font_color: '#333333'
-background_color: '#F0F8FF'
\ No newline at end of file
diff --git a/config/apps/onlineshop/appearance/dark_theme.yaml b/config/apps/onlineshop/appearance/dark_theme.yaml
deleted file mode 100644
index 986dc183..00000000
--- a/config/apps/onlineshop/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,17 +0,0 @@
-# @package apps.onlineshop
-
-allowed_credit_cards:
-  - 'Visa'
-  - 'MasterCard'
-  # - 'Amex'
-enable_credit_card_check: false
-enable: False
-
-
-font_family: 'Arial'
-base_font_size: '16px'
-font_color: '#bb86fc'
-background_color: '#121212'
-button_background_color: '#FFFFFF'
-button_font_color: '#3700b3'
-highlight_font_color: '#bb86fc'
\ No newline at end of file
diff --git a/config/apps/onlineshop/appearance/default.yaml b/config/apps/onlineshop/appearance/default.yaml
deleted file mode 100644
index e6634a3a..00000000
--- a/config/apps/onlineshop/appearance/default.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.onlineshop
-
-allowed_credit_cards:
-  - 'Visa'
-  - 'MasterCard'
-  # - 'Amex'
-enable_credit_card_check: false
-enable: False
-
-
-font_family: 'Arial'
-base_font_size: '16px'
-font_color: '#333333'
-background_color: '#F0F8FF'
\ No newline at end of file
diff --git a/config/apps/onlineshop/default.yaml b/config/apps/onlineshop/default.yaml
index 56f14ae6..ab108223 100644
--- a/config/apps/onlineshop/default.yaml
+++ b/config/apps/onlineshop/default.yaml
@@ -1,5 +1,20 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
-database_path: ${databases_dir}/onlineshop
\ No newline at end of file
+database_path: ${databases_dir}/onlineshop
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.onlineshop.theme=solarized`.
+theme: null
+
+# --- Behaviour -------------------------------------------------------------
+
+# Off by default: the shop needs OpenJDK 21 and a downloaded dataset
+# (see setup.sh), so it is opt-in with `apps.onlineshop.enable=True`.
+enable: False
+allowed_credit_cards:
+  - 'Visa'
+  - 'MasterCard'
+  # - 'Amex'
+enable_credit_card_check: false
diff --git a/config/apps/onlineshop/layout/default.yaml b/config/apps/onlineshop/layout/default.yaml
new file mode 100644
index 00000000..41253d70
--- /dev/null
+++ b/config/apps/onlineshop/layout/default.yaml
@@ -0,0 +1,4 @@
+# @package apps.onlineshop
+# Structure only -- colors and fonts come from the shared theme
+# (`config/apps/theme/`). Select with `apps/onlineshop/layout=<name>`.
+layout: default
diff --git a/config/apps/start_page/appearance/black_and_white.yaml b/config/apps/start_page/appearance/black_and_white.yaml
deleted file mode 100644
index d9944fb3..00000000
--- a/config/apps/start_page/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-# @package apps.start_page
-# Layout and styling
-style: 1                # Style number (1, 2, or 3) as per Story template
-size: "small"           # Size of items - "small", "medium", or "big"
-fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
-lightbox: false         # Enable lightbox effect for images
-random_tile_reoder: false  # Whether to shuffle the items
-wrapper_style: 1        # Wrapper style number
-wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
-wrapper_color: null     # Wrapper color number (1-7) or null
-wrapper_invert: false   # Whether to invert the wrapper color scheme
-
-# Font settings
-font_family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#1d1d1f"   # Dark gray text color like iOS
-heading_font: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-heading_color: "#1d1d1f" # Dark gray heading color
-
-# Item appearance - iPhone app style
-item_border_radius: 22  # Higher border radius for iOS rounded corners
-item_padding: 1.2       # Reduced padding for more compact look
-item_text_align: "center" # Text alignment - "left", "center", "right"
-item_hover_effect: true # Enable hover effect
-hover_shadow: true      # Enable shadow on hover
-hover_scale: true       # Enable subtle scale effect on hover like iOS
-hover_brightness: false # Disable brightness effect
-
-# Color scheme
-use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
-theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#ffffff"  # Light gray background like iOS
-app_background_colors:  # iOS-inspired gradient colors for app tiles
-  ["#2e2e2e", "#2e2e2e", "#2e2e2e", "#2e2e2e", "#2e2e2e", "#2e2e2e", "#2e2e2e"]
-use_random_colors: false # Generate random colors for items instead of using app_background_colors
-
-# Apps configuration
-icon_path: "/assets/icons/real_icons"
-bw_icon_path: "/assets/icons/real_icons_bw"
-apps:
-  todo:
-    icon: ${apps.start_page.bw_icon_path}/todo.png 
-    enabled: true
-    position: 1
-    clickable_logo: false
-  calendar:
-    icon: ${apps.start_page.bw_icon_path}/calendar.png
-    enabled: true
-    position: 2
-    clickable_logo: false
-  messages:
-    icon: ${apps.start_page.bw_icon_path}/messages.png
-    user_icon: ${apps.start_page.bw_icon_path}/user.png
-    group_icon: ${apps.start_page.bw_icon_path}/group.png
-    enabled: true
-    position: 3
-    clickable_logo: false
-  maps:
-    icon: ${apps.start_page.bw_icon_path}/maps.png
-    enabled: true
-    position: 4
-    clickable_logo: false
-  codeeditor:
-    icon: ${apps.start_page.bw_icon_path}/code.png
-    enabled: true
-    position: 5
-    clickable_logo: false
-  onlineshop:
-    icon: ${apps.start_page.bw_icon_path}/shop.png
-    enabled: true
-    position: 6
-    clickable_logo: false
\ No newline at end of file
diff --git a/config/apps/start_page/appearance/challenging_font.yaml b/config/apps/start_page/appearance/challenging_font.yaml
deleted file mode 100644
index 765146bd..00000000
--- a/config/apps/start_page/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-# @package apps.start_page
-# Layout and styling
-style: 1                # Style number (1, 2, or 3) as per Story template
-size: "small"           # Size of items - "small", "medium", or "big"
-fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
-lightbox: false         # Enable lightbox effect for images
-random_tile_reoder: false  # Whether to shuffle the items
-wrapper_style: 1        # Wrapper style number
-wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
-wrapper_color: null     # Wrapper color number (1-7) or null
-wrapper_invert: false   # Whether to invert the wrapper color scheme
-
-# Font settings
-font_family: "Brush Script MT"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#1d1d1f"   # Dark gray text color like iOS
-heading_font: "Brush Script MT"  # iOS-like font stack
-heading_color: "#1d1d1f" # Dark gray heading color
-
-# Item appearance - iPhone app style
-item_border_radius: 22  # Higher border radius for iOS rounded corners
-item_padding: 1.2       # Reduced padding for more compact look
-item_text_align: "center" # Text alignment - "left", "center", "right"
-item_hover_effect: true # Enable hover effect
-hover_shadow: true      # Enable shadow on hover
-hover_scale: true       # Enable subtle scale effect on hover like iOS
-hover_brightness: false # Disable brightness effect
-
-# Color scheme
-use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
-theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#f2f2f7"  # Light gray background like iOS
-app_background_colors:  # iOS-inspired gradient colors for app tiles
-  ["#007AFF", "#FF3B30", "#FF9500", "#FFCC02", "#34C759", "#5856D6", "#AF52DE"]
-use_random_colors: false # Generate random colors for items instead of using app_background_colors
-
-# Apps configuration
-icon_path: "/assets/icons/real_icons"
-bw_icon_path: "/assets/icons/real_icons_bw"
-apps:
-  todo:
-    icon: ${apps.start_page.icon_path}/todo.png 
-    enabled: true
-    position: 1
-    clickable_logo: false
-  calendar:
-    icon: ${apps.start_page.icon_path}/calendar.png
-    enabled: true
-    position: 2
-    clickable_logo: false
-  messages:
-    icon: ${apps.start_page.icon_path}/messages.png
-    user_icon: ${apps.start_page.bw_icon_path}/user.png
-    group_icon: ${apps.start_page.bw_icon_path}/group.png
-    enabled: true
-    position: 3
-    clickable_logo: false
-  maps:
-    icon: ${apps.start_page.icon_path}/maps.png
-    enabled: true
-    position: 4
-    clickable_logo: false
-  codeeditor:
-    icon: ${apps.start_page.icon_path}/code.png
-    enabled: true
-    position: 5
-    clickable_logo: false
-  onlineshop:
-    icon: ${apps.start_page.icon_path}/shop.png
-    enabled: true
-    position: 6
-    clickable_logo: false
\ No newline at end of file
diff --git a/config/apps/start_page/appearance/dark_theme.yaml b/config/apps/start_page/appearance/dark_theme.yaml
deleted file mode 100644
index 6dcb59b9..00000000
--- a/config/apps/start_page/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-# @package apps.start_page
-# Layout and styling
-style: 1                # Style number (1, 2, or 3) as per Story template
-size: "small"           # Size of items - "small", "medium", or "big"
-fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
-lightbox: false         # Enable lightbox effect for images
-random_tile_reoder: false  # Whether to shuffle the items
-wrapper_style: 1        # Wrapper style number
-wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
-wrapper_color: null     # Wrapper color number (1-7) or null
-wrapper_invert: false   # Whether to invert the wrapper color scheme
-
-# Font settings
-font_family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#ffffff"   # Text color like iOS
-heading_font: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-heading_color: "#f0f0f0" # close-to-white light heading color
-
-# Item appearance - iPhone app style
-item_border_radius: 22  # Higher border radius for iOS rounded corners
-item_padding: 1.2       # Reduced padding for more compact look
-item_text_align: "center" # Text alignment - "left", "center", "right"
-item_hover_effect: true # Enable hover effect
-hover_shadow: true      # Enable shadow on hover
-hover_scale: true       # Enable subtle scale effect on hover like iOS
-hover_brightness: false # Disable brightness effect
-
-# Color scheme
-use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
-theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#000000"  # Black background like iOS
-app_background_colors:  # grey background for apps
-  ["#636262", "#636262", "#636262", "#636262", "#636262", "#636262", "#636262"]
-use_random_colors: false # Generate random colors for items instead of using app_background_colors
-
-# Apps configuration
-icon_path: "/assets/icons/real_icons"
-bw_icon_path: "/assets/icons/real_icons_bw"
-apps:
-  todo:
-    icon: ${apps.start_page.bw_icon_path}/todo.png 
-    enabled: true
-    position: 1
-    clickable_logo: false
-  calendar:
-    icon: ${apps.start_page.bw_icon_path}/calendar.png
-    enabled: true
-    position: 2
-    clickable_logo: false
-  messages:
-    icon: ${apps.start_page.bw_icon_path}/messages.png
-    user_icon: ${apps.start_page.bw_icon_path}/user.png
-    group_icon: ${apps.start_page.bw_icon_path}/group.png
-    enabled: true
-    position: 3
-    clickable_logo: false
-  maps:
-    icon: ${apps.start_page.bw_icon_path}/maps.png
-    enabled: true
-    position: 4
-    clickable_logo: false
-  codeeditor:
-    icon: ${apps.start_page.bw_icon_path}/code.png
-    enabled: true
-    position: 5
-    clickable_logo: false
-  onlineshop:
-    icon: ${apps.start_page.bw_icon_path}/shop.png
-    enabled: true
-    position: 6
-    clickable_logo: false
\ No newline at end of file
diff --git a/config/apps/start_page/appearance/default.yaml b/config/apps/start_page/appearance/default.yaml
deleted file mode 100644
index 71ab0e9e..00000000
--- a/config/apps/start_page/appearance/default.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-# @package apps.start_page
-# Layout and styling
-style: 1                # Style number (1, 2, or 3) as per Story template
-size: "small"           # Size of items - "small", "medium", or "big"
-fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
-lightbox: false         # Enable lightbox effect for images
-random_tile_reoder: false  # Whether to shuffle the items
-wrapper_style: 1        # Wrapper style number
-wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
-wrapper_color: null     # Wrapper color number (1-7) or null
-wrapper_invert: false   # Whether to invert the wrapper color scheme
-
-# Font settings
-font_family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#1d1d1f"   # Dark gray text color like iOS
-heading_font: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-heading_color: "#1d1d1f" # Dark gray heading color
-
-# Item appearance - iPhone app style
-item_border_radius: 22  # Higher border radius for iOS rounded corners
-item_padding: 1.2       # Reduced padding for more compact look
-item_text_align: "center" # Text alignment - "left", "center", "right"
-item_hover_effect: true # Enable hover effect
-hover_shadow: true      # Enable shadow on hover
-hover_scale: true       # Enable subtle scale effect on hover like iOS
-hover_brightness: false # Disable brightness effect
-
-# Color scheme
-use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
-theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#f2f2f7"  # Light gray background like iOS
-app_background_colors:  # iOS-inspired gradient colors for app tiles
-  ["#007AFF", "#FF3B30", "#FF9500", "#FFCC02", "#34C759", "#5856D6", "#AF52DE"]
-use_random_colors: false # Generate random colors for items instead of using app_background_colors
-
-# Apps configuration
-icon_path: "/assets/icons/real_icons"
-bw_icon_path: "/assets/icons/real_icons_bw"
-apps:
-  todo:
-    icon: ${apps.start_page.icon_path}/todo.png 
-    enabled: true
-    position: 1
-    clickable_logo: false
-  calendar:
-    icon: ${apps.start_page.icon_path}/calendar.png
-    enabled: true
-    position: 2
-    clickable_logo: false
-  messages:
-    icon: ${apps.start_page.icon_path}/messages.png
-    user_icon: ${apps.start_page.bw_icon_path}/user.png
-    group_icon: ${apps.start_page.bw_icon_path}/group.png
-    enabled: true
-    position: 3
-    clickable_logo: false
-  maps:
-    icon: ${apps.start_page.icon_path}/maps.png
-    enabled: true
-    position: 4
-    clickable_logo: false
-  codeeditor:
-    icon: ${apps.start_page.icon_path}/code.png
-    enabled: true
-    position: 5
-    clickable_logo: false
-  onlineshop:
-    icon: ${apps.start_page.icon_path}/shop.png
-    enabled: true
-    position: 6
-    clickable_logo: false
\ No newline at end of file
diff --git a/config/apps/start_page/default.yaml b/config/apps/start_page/default.yaml
index 666a8292..69689a37 100644
--- a/config/apps/start_page/default.yaml
+++ b/config/apps/start_page/default.yaml
@@ -1,6 +1,6 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
 # Per-app theme override. null = inherit the global `apps/theme` selection.
 # Override for just this app with `apps.start_page.theme=solarized`.
diff --git a/config/apps/start_page/layout/broken_logos.yaml b/config/apps/start_page/layout/broken_logos.yaml
new file mode 100644
index 00000000..78011c14
--- /dev/null
+++ b/config/apps/start_page/layout/broken_logos.yaml
@@ -0,0 +1,9 @@
+# @package apps.start_page
+# Every icon is detached from its tile, so the picture no longer identifies
+# the app and the agent has to read the label. Structure, not appearance:
+# the palette and typography are whatever the active theme says.
+defaults:
+  - default
+
+layout: broken_logos
+shuffle_icons: true
diff --git a/config/apps/start_page/appearance/clickable_logos.yaml b/config/apps/start_page/layout/clickable_logos.yaml
similarity index 57%
rename from config/apps/start_page/appearance/clickable_logos.yaml
rename to config/apps/start_page/layout/clickable_logos.yaml
index 98fa7feb..19b76b9d 100644
--- a/config/apps/start_page/appearance/clickable_logos.yaml
+++ b/config/apps/start_page/layout/clickable_logos.yaml
@@ -1,6 +1,10 @@
 # @package apps.start_page
+# Each app's in-page logo header becomes a link back to the start page,
+# adding a navigation affordance that does not exist by default.
 defaults:
   - default
+
+layout: clickable_logos
 apps:
   todo:
     clickable_logo: true
@@ -13,4 +17,4 @@ apps:
   codeeditor:
     clickable_logo: true
   onlineshop:
-    clickable_logo: true
\ No newline at end of file
+    clickable_logo: true
diff --git a/config/apps/start_page/appearance/broken_logos.yaml b/config/apps/start_page/layout/default.yaml
similarity index 64%
rename from config/apps/start_page/appearance/broken_logos.yaml
rename to config/apps/start_page/layout/default.yaml
index 2f5d5a35..903e2936 100644
--- a/config/apps/start_page/appearance/broken_logos.yaml
+++ b/config/apps/start_page/layout/default.yaml
@@ -1,23 +1,21 @@
 # @package apps.start_page
-# Layout and styling
+# Structure only -- fonts and text colors come from the shared theme
+# (`config/apps/theme/`). Select with `apps/start_page/layout=<name>`.
+layout: default
+
+# Layout
 style: 1                # Style number (1, 2, or 3) as per Story template
 size: "small"           # Size of items - "small", "medium", or "big"
 fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
 lightbox: false         # Enable lightbox effect for images
 random_tile_reoder: false  # Whether to shuffle the items
+shuffle_icons: false    # Whether to detach each app's icon from its tile
 wrapper_style: 1        # Wrapper style number
 wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
 wrapper_color: null     # Wrapper color number (1-7) or null
 wrapper_invert: false   # Whether to invert the wrapper color scheme
 
-# Font settings
-font_family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#1d1d1f"   # Dark gray text color like iOS
-heading_font: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-heading_color: "#1d1d1f" # Dark gray heading color
-
-# Item appearance - iPhone app style
+# Item geometry - iPhone app style
 item_border_radius: 22  # Higher border radius for iOS rounded corners
 item_padding: 1.2       # Reduced padding for more compact look
 item_text_align: "center" # Text alignment - "left", "center", "right"
@@ -26,32 +24,42 @@ hover_shadow: true      # Enable shadow on hover
 hover_scale: true       # Enable subtle scale effect on hover like iOS
 hover_brightness: false # Disable brightness effect
 
-# Color scheme
+# Tile fills. These are the one piece of color the theme does not own: the
+# tiles are a deliberately saturated iOS-style palette that carries no
+# semantic meaning, so mapping it onto theme tokens would flatten six
+# distinguishable targets into one. Non-light themes collapse it to a single
+# fill instead (see `tile_fill_by_tone`).
 use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
 theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#f2f2f7"  # Light gray background like iOS
 app_background_colors:  # iOS-inspired gradient colors for app tiles
   ["#007AFF", "#FF3B30", "#FF9500", "#FFCC02", "#34C759", "#5856D6", "#AF52DE"]
 use_random_colors: false # Generate random colors for items instead of using app_background_colors
+tile_fill_by_tone:      # Single fill replacing the palette, by theme tone
+  dark: "#636262"
+  mono: "#2e2e2e"
 
-shuffle_icons: True
-
-# Apps configuration
+# Icon sets. The theme's `icon_set` asset picks between them: PNGs cannot be
+# recolored by a CSS variable, and the repo ships a hand-made greyscale set
+# that beats a `filter: grayscale()` approximation.
 icon_path: "/assets/icons/real_icons"
 bw_icon_path: "/assets/icons/real_icons_bw"
+
 apps:
   todo:
-    icon: ${apps.start_page.icon_path}/todo.png 
+    icon: ${apps.start_page.icon_path}/todo.png
+    bw_icon: ${apps.start_page.bw_icon_path}/todo.png
     enabled: true
     position: 1
     clickable_logo: false
   calendar:
     icon: ${apps.start_page.icon_path}/calendar.png
+    bw_icon: ${apps.start_page.bw_icon_path}/calendar.png
     enabled: true
     position: 2
     clickable_logo: false
   messages:
     icon: ${apps.start_page.icon_path}/messages.png
+    bw_icon: ${apps.start_page.bw_icon_path}/messages.png
     user_icon: ${apps.start_page.bw_icon_path}/user.png
     group_icon: ${apps.start_page.bw_icon_path}/group.png
     enabled: true
@@ -59,16 +67,19 @@ apps:
     clickable_logo: false
   maps:
     icon: ${apps.start_page.icon_path}/maps.png
+    bw_icon: ${apps.start_page.bw_icon_path}/maps.png
     enabled: true
     position: 4
     clickable_logo: false
   codeeditor:
     icon: ${apps.start_page.icon_path}/code.png
+    bw_icon: ${apps.start_page.bw_icon_path}/code.png
     enabled: true
     position: 5
     clickable_logo: false
   onlineshop:
     icon: ${apps.start_page.icon_path}/shop.png
+    bw_icon: ${apps.start_page.bw_icon_path}/shop.png
     enabled: true
     position: 6
-    clickable_logo: false
\ No newline at end of file
+    clickable_logo: false
diff --git a/config/apps/theme/bootstrap.yaml b/config/apps/theme/bootstrap.yaml
index cb2a8bfd..41a62ed5 100644
--- a/config/apps/theme/bootstrap.yaml
+++ b/config/apps/theme/bootstrap.yaml
@@ -9,6 +9,7 @@ tokens:
   color-muted: "#6c757d"
   color-border: "#dee2e6"
   color-primary: "#0d6efd"
+  color-primary-hover: "#0b5ed7"
   color-on-primary: "#ffffff"
   color-accent: "#198754"
   color-danger: "#dc3545"
@@ -16,6 +17,12 @@ tokens:
   color-btn-fg: "#ffffff"
   font-family: "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif"
   font-heading: "inherit"
+  font-mono: "SFMono-Regular, Menlo, Monaco, Consolas, monospace"
   font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
   radius: "0.375rem"
   space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/challenging_font.yaml b/config/apps/theme/challenging_font.yaml
index 9e1842b5..86a408ff 100644
--- a/config/apps/theme/challenging_font.yaml
+++ b/config/apps/theme/challenging_font.yaml
@@ -1,6 +1,7 @@
 # @package apps.theme
-# Faithful port of the former todo `challenging_font` appearance variant:
-# the default palette rendered in a hard-to-read script face.
+# The default palette rendered in a hard-to-read script face. Isolates
+# typography as a variation axis: identical colors and layout to `default`,
+# so any change in agent success is attributable to legibility alone.
 name: challenging_font
 import_url: ""
 tokens:
@@ -10,6 +11,7 @@ tokens:
   color-muted: "#6b7280"
   color-border: "#dfe1e6"
   color-primary: "#2563eb"
+  color-primary-hover: "#1d4ed8"
   color-on-primary: "#ffffff"
   color-accent: "#2563eb"
   color-danger: "#b22222"
@@ -17,6 +19,15 @@ tokens:
   color-btn-fg: "#ffffff"
   font-family: "'Brush Script MT', cursive"
   font-heading: "inherit"
+  # The editor stays monospace on purpose -- a script face in a code pane
+  # destroys column alignment, which is a different perturbation than the
+  # legibility one this theme is meant to isolate.
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
   font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
   radius: "8px"
   space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/colorblind.yaml b/config/apps/theme/colorblind.yaml
new file mode 100644
index 00000000..24e0a099
--- /dev/null
+++ b/config/apps/theme/colorblind.yaml
@@ -0,0 +1,31 @@
+# @package apps.theme
+# Colorblind-safe palette (IBM Design Library), generalised from the code
+# editor's former `colorblind_access` appearance variant so every app can use
+# it. Primary/danger stay distinguishable under deuteranopia and protanopia,
+# which is exactly the pair an agent has to tell apart (save vs delete).
+name: colorblind
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#648fff"        # IBM blue, as the editor variant used it
+  color-fg: "#000000"
+  color-muted: "#5a5a5a"
+  color-border: "#785ef0"
+  color-primary: "#dc267f"        # magenta
+  color-primary-hover: "#a81b62"
+  color-on-primary: "#ffffff"
+  color-accent: "#785ef0"         # violet
+  color-danger: "#fe6100"         # orange -- separable from magenta, unlike red
+  color-neutral: "#ffb000"        # amber
+  color-btn-fg: "#000000"
+  font-family: "system-ui, -apple-system, 'Helvetica Neue', Arial, sans-serif"
+  font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
+  radius: "8px"
+  space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/dark.yaml b/config/apps/theme/dark.yaml
index 0f22dd41..583c014e 100644
--- a/config/apps/theme/dark.yaml
+++ b/config/apps/theme/dark.yaml
@@ -1,21 +1,36 @@
 # @package apps.theme
-# Faithful port of the former todo `dark_theme` appearance variant.
+# Dark theme. The palette is the one the `dark_theme` appearance variant used
+# in calendar, messenger, maps and the code editor (Material dark: #121212
+# surface, #bb86fc primary, #03dac6 accent) -- that was four of the six apps,
+# so it is the reading that survives becoming a *shared* theme.
+#
+# It is deliberately not the old todo `dark_theme`, which was a white page with
+# a black card. That worked as one app's local variant but is not a dark theme:
+# its `color-bg` and `color-fg` were both white, which only rendered because
+# nothing outside todo consumed the tokens.
 name: dark
 import_url: ""
 tokens:
-  color-bg: "#ffffff"
-  color-surface: "#000000"
+  color-bg: "#121212"
+  color-surface: "#1e1e1e"
   color-fg: "#ffffff"
   color-muted: "#9ca3af"
-  color-border: "#ffffff"
-  color-primary: "#000000"
-  color-on-primary: "#ffffff"
-  color-accent: "#ffffff"
-  color-danger: "#ffffff"
-  color-neutral: "#ffffff"
-  color-btn-fg: "#000000"
-  font-family: "'Times New Roman', serif"
+  color-border: "#2d2d2d"
+  color-primary: "#bb86fc"
+  color-primary-hover: "#3700b3"
+  color-on-primary: "#000000"
+  color-accent: "#03dac6"
+  color-danger: "#cf6679"
+  color-neutral: "#4a4a4a"
+  color-btn-fg: "#ffffff"
+  font-family: "'Inter', system-ui, -apple-system, sans-serif"
   font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
   font-size-base: "16px"
-  radius: "8px"
+  font-size-sm: "14px"
+  font-size-heading: "1.75rem"
+  radius: "4px"
   space: "8px"
+assets:
+  tone: dark
+  icon_set: bw
diff --git a/config/apps/theme/default.yaml b/config/apps/theme/default.yaml
index 99eb7a45..efdd3c05 100644
--- a/config/apps/theme/default.yaml
+++ b/config/apps/theme/default.yaml
@@ -2,6 +2,10 @@
 # Shared design tokens. Selected globally with `apps/theme=<name>` or per app
 # with `apps.<app>.theme=<name>`. Every `tokens` entry becomes a CSS custom
 # property (`color-primary` -> `--color-primary`) consumed via `var(--...)`.
+#
+# This file is the canonical token vocabulary: every other theme declares the
+# same keys, so an app can use any of them without checking which theme is
+# active. `assets` covers the choices no CSS variable can reach.
 name: default
 import_url: ""
 tokens:
@@ -10,18 +14,28 @@ tokens:
   color-fg: "#1a1a1a"
   color-muted: "#6b7280"
   color-border: "#dfe1e6"
-  color-primary: "#2563eb"     # add / primary action
+  color-primary: "#2563eb"        # add / primary action
+  color-primary-hover: "#1d4ed8"
   color-on-primary: "#ffffff"
-  color-accent: "#2563eb"      # save action
-  color-danger: "#b22222"      # remove / destructive
-  color-neutral: "#36454f"     # edit / secondary
-  color-btn-fg: "#ffffff"      # text on edit/remove/save buttons
+  color-accent: "#2563eb"         # save action
+  color-danger: "#b22222"         # remove / destructive
+  color-neutral: "#36454f"        # edit / secondary
+  color-btn-fg: "#ffffff"         # text on edit/remove/save buttons
   # Matches the sans-serif the appearance-based apps have always used
   # (`font_family: 'Arial'`), so the `default` theme looks like the app did
   # before it was migrated to tokens rather than falling back to the browser's
   # serif. Pick `mono` or `challenging_font` to vary this deliberately.
   font-family: "system-ui, -apple-system, 'Helvetica Neue', Arial, sans-serif"
   font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
   font-size-base: "16px"
+  font-size-sm: "14px"            # chat bubbles, editor gutter, dense lists
+  font-size-heading: "1.5rem"
   radius: "8px"
   space: "8px"
+# Non-CSS choices. `tone` is app-agnostic: each app maps it onto its own
+# concrete asset (maps -> Leaflet tile layer, code editor -> CodeMirror
+# stylesheet, start page -> tile fill). `icon_set` picks a raster icon dir.
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/material.yaml b/config/apps/theme/material.yaml
index 46c16eef..f8c68dc5 100644
--- a/config/apps/theme/material.yaml
+++ b/config/apps/theme/material.yaml
@@ -9,6 +9,7 @@ tokens:
   color-muted: "#757575"
   color-border: "#e0e0e0"
   color-primary: "#6200ee"
+  color-primary-hover: "#3700b3"
   color-on-primary: "#ffffff"
   color-accent: "#03dac6"
   color-danger: "#b00020"
@@ -16,6 +17,12 @@ tokens:
   color-btn-fg: "#ffffff"
   font-family: "'Roboto', 'Helvetica Neue', sans-serif"
   font-heading: "inherit"
+  font-mono: "'Roboto Mono', ui-monospace, Menlo, Consolas, monospace"
   font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
   radius: "4px"
   space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/mono.yaml b/config/apps/theme/mono.yaml
index da0ec8b8..f6d8d8f3 100644
--- a/config/apps/theme/mono.yaml
+++ b/config/apps/theme/mono.yaml
@@ -1,21 +1,34 @@
 # @package apps.theme
-# Faithful port of the former todo `black_and_white` appearance variant.
+# Strict black-and-white: no hue anywhere, so an agent gets no color cue for
+# "primary action" vs "destructive action" and has to read the label.
+#
+# The old per-app `black_and_white` variants disagreed on polarity -- calendar
+# inverted the page (black background, white text) while messenger, maps,
+# onlineshop and the start page kept a white page with black ink. This takes
+# the majority reading: white page, black ink. Use `dark` for an inverted page.
 name: mono
 import_url: ""
 tokens:
-  color-bg: "#000000"
+  color-bg: "#ffffff"
   color-surface: "#ffffff"
   color-fg: "#000000"
   color-muted: "#000000"
   color-border: "#000000"
   color-primary: "#000000"
+  color-primary-hover: "#444444"
   color-on-primary: "#ffffff"
   color-accent: "#000000"
   color-danger: "#000000"
   color-neutral: "#000000"
   color-btn-fg: "#ffffff"
-  font-family: "'Times New Roman', serif"
+  font-family: "'Inter', system-ui, -apple-system, sans-serif"
   font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
   font-size-base: "16px"
-  radius: "8px"
+  font-size-sm: "14px"
+  font-size-heading: "2rem"
+  radius: "0px"                   # sharp corners: another cue removed
   space: "8px"
+assets:
+  tone: mono
+  icon_set: bw
diff --git a/config/apps/theme/solarized.yaml b/config/apps/theme/solarized.yaml
index c50333f8..f24445ba 100644
--- a/config/apps/theme/solarized.yaml
+++ b/config/apps/theme/solarized.yaml
@@ -9,6 +9,7 @@ tokens:
   color-muted: "#93a1a1"
   color-border: "#93a1a1"
   color-primary: "#268bd2"
+  color-primary-hover: "#1f6f9f"
   color-on-primary: "#fdf6e3"
   color-accent: "#2aa198"
   color-danger: "#dc322f"
@@ -16,6 +17,12 @@ tokens:
   color-btn-fg: "#fdf6e3"
   font-family: "'Inter', system-ui, sans-serif"
   font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
   font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
   radius: "8px"
   space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/config_parallel_tasks.yaml b/config/config_parallel_tasks.yaml
index 9b15da8f..0a436518 100644
--- a/config/config_parallel_tasks.yaml
+++ b/config/config_parallel_tasks.yaml
@@ -5,6 +5,7 @@ defaults:
   - agent: dummy
   - tasks: all_tasks
   - browsergym_env_args: default
+  - apps/theme: default
   - apps/code_editor: default
   - apps/maps: default
   - apps/messenger: default
@@ -33,14 +34,9 @@ parallel_tasks:
     - message_alice_about_badminton
   app_variations:
     - ["apps/start_page/content=default", "apps/calendar/content=default"]
-    - [
-        "apps/start_page/appearance=dark_theme",
-        "apps/calendar/appearance=dark_theme",
-        "apps.todo.theme=dark",
-        "apps/messenger/appearance=dark_theme",
-        "apps/maps/appearance=dark_theme",
-        "apps/code_editor/appearance=dark_theme",
-      ]
+    # One override now themes every app -- that is the point of the shared
+    # `apps/theme` group replacing the per-app `appearance` ones.
+    - ["apps/theme=dark"]
 
 # auto-populated by launch_parallel_agents.py
 task_name: null
diff --git a/docs/index.md b/docs/index.md
index 77b111ec..a338017d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -46,12 +46,19 @@ uv run launch.py 'apps.todo.init_todos=[["Call Mom", false]]'
 
 OpenApps also comes with pre-defined variations that can affect the content and appearance of apps.
 
-#### Appearance
+Appearance is split along two axes:
+
+* **Theme** -- *look*: colors, typography, shape. One shared set of design
+  tokens in `config/apps/theme/`, applied to **every** app at once.
+* **Layout** -- *structure*: how an individual app arranges itself. Per-app,
+  under `config/apps/<app>/layout/`.
+
+#### Theme
 
 /// tab | challenging font
 
     ::bash
-    export APPEARANCE=challenging_font
+    export THEME=challenging_font
 
 
 ![landing](images/landing-challenging-font.png)
@@ -59,25 +66,62 @@ OpenApps also comes with pre-defined variations that can affect the content and
 /// tab | dark theme
 
     ::bash
-    export APPEARANCE=dark_theme
+    export THEME=dark
 
 ![landing](images/landing-dark.png)
 ///
 /// tab | default
 
     ::bash
-    export APPEARANCE=default
+    export THEME=default
 
 ![landing](images/landing.png)
 
 ///
 
-Launch specific apps with selected appearance:
+A single override themes every app:
+```shell
+uv run launch.py apps/theme=$THEME
+```
+
+Or one app only, leaving the rest on the global theme:
+`uv run launch.py apps.calendar.theme=$THEME`.
+
+Shipped themes: `default`, `dark`, `mono`, `challenging_font`, `colorblind`,
+`solarized`, `material`, `bootstrap`. Adding one means adding a yaml file to
+`config/apps/theme/` -- no app code changes.
+
+A theme file is a set of design tokens plus a small `assets` block:
+
+```yaml
+# config/apps/theme/dark.yaml
+name: dark
+tokens:
+  color-bg: "#121212"       # -> --color-bg, consumed as var(--color-bg)
+  color-primary: "#bb86fc"
+  font-family: "'Inter', system-ui, sans-serif"
+  radius: "4px"
+assets:
+  tone: dark                # apps map this onto their own non-CSS assets
+  icon_set: bw
+```
+
+Every `tokens` entry becomes a CSS custom property. `assets` covers the
+choices a CSS variable cannot reach -- the start page's raster icons, the
+Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately
+app-agnostic: the theme says `tone: dark` and each app picks its own dark
+asset, so a theme file never has to know which apps exist.
+
+#### Layout
+
 ```shell
-uv run launch.py apps/start_page/appearance=$APPEARANCE
+uv run launch.py apps/todo/layout=kanban_board
+uv run launch.py apps/start_page/layout=broken_logos
 ```
 
-Or specific apps with: `apps/calendar/appearance=$APPEARANCE`.
+Available layouts: `todo` has `default` and `kanban_board`; `start_page` has
+`default`, `broken_logos` (icons detached from their tiles) and
+`clickable_logos`; the other apps currently have `default` only.
 
 #### Content
 
@@ -111,7 +155,11 @@ uv run launch.py apps/start_page/content=$CONTENT
 
 Or specific apps with: `apps/calendar/content=$CONTENT`.
 
-You can see the specific variables for each defined in the individual apps. For example, `config/apps/maps/appearance/dark_theme.yaml`.
+You can see the specific variables for each defined in the individual apps.
+For example, `config/apps/theme/dark.yaml` for the shared design tokens,
+`config/apps/start_page/layout/broken_logos.yaml` for a per-app structure
+variant, and `config/apps/maps/default.yaml` for behaviour (map zoom, tile
+layer, route planning) that is neither.
 
 Optional: to save screenshots of all apps with a specific variation for testing, we offer `tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/` to make this easy.
 
@@ -198,14 +246,13 @@ parallel_tasks:
   app_variations:
     - ["apps/start_page/content=default", "apps/calendar/content=german"]
     - [
-        "apps/start_page/appearance=dark_theme",
-        "apps/calendar/appearance=dark_theme",
+        "apps/theme=dark",
       ]
 ```
 
 You can modify the set of tasks or app variation by updating the `config_parallel_tasks.yaml`. We ensure:
 
-* Each deployment of OpenApps can have different appearance and content per app.
+* Each deployment of OpenApps can have a different theme (global), plus layout and content per app.
 * Each task is launched in an isolated environment for reproducible results.
 
 To run **every** task in the loaded tasks config (rather than listing a subset by
diff --git a/site/agents/index.html b/site/agents/index.html
index 41a4acaa..c5e1abbf 100644
--- a/site/agents/index.html
+++ b/site/agents/index.html
@@ -544,6 +544,93 @@ <h2 id="creating-your-own-agent">Creating Your Own Agent</h2>
 </li>
 </ol>
 <p>This allows you to build rich, custom agent implementations tailored to your specific requirements.</p>
+<h2 id="running-evals-on-a-cluster-slurm-vllm-wb">Running Evals on a Cluster (SLURM + vLLM + W&amp;B)</h2>
+<p>The workflow consists of two jobs:</p>
+<ol>
+<li>A persistent <strong>vLLM GPU job</strong> that serves the model on <code>:8000</code>.</li>
+<li>An <strong>eval CPU job</strong> (<code>sbatch scripts/conduct_slurm.sh</code>) that auto-discovers the vLLM node and runs the worker pool against it.</li>
+</ol>
+<h3 id="one-time-cluster-setup">One-time cluster setup</h3>
+<p>The repo needs to live on shared storage (e.g. <code>/example/dir/$USER</code>
+or <code>/storage/home/$USER</code>). On a login node:</p>
+<div class="codehilite"><pre><span></span><code><span class="c1"># Bring the repo over. Use rsync if you have uncommitted local changes (e.g.</span>
+<span class="c1"># scripts/conduct.sh) that aren&#39;t pushed yet:</span>
+rsync<span class="w"> </span>-av<span class="w"> </span>--exclude<span class="w"> </span>.venv<span class="w"> </span>/path/to/local/OpenApps/<span class="w"> </span>/example/dir/<span class="nv">$USER</span>/OpenApps/
+<span class="c1"># ...or clone it fresh:</span>
+<span class="c1">#   git clone &lt;repo-url&gt; /example/dir/$USER/OpenApps</span>
+
+<span class="nb">cd</span><span class="w"> </span>/example/dir/<span class="nv">$USER</span>/OpenApps
+
+<span class="c1"># Python env</span>
+curl<span class="w"> </span>-LsSf<span class="w"> </span>https://astral.sh/uv/install.sh<span class="w"> </span><span class="p">|</span><span class="w"> </span>sh<span class="w">   </span><span class="c1"># install uv if needed</span>
+uv<span class="w"> </span>sync
+
+<span class="c1"># Headless browser</span>
+uv<span class="w"> </span>run<span class="w"> </span>playwright<span class="w"> </span>install<span class="w"> </span>chromium
+uv<span class="w"> </span>run<span class="w"> </span>playwright<span class="w"> </span>install-deps<span class="w"> </span>chromium<span class="w">   </span><span class="c1"># system deps (may need sudo/module)</span>
+
+<span class="c1"># App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg)</span>
+./setup.sh
+
+<span class="c1"># Secrets — do NOT commit this file</span>
+cat<span class="w"> </span>&gt;<span class="w"> </span>.env<span class="w"> </span><span class="s">&lt;&lt;&#39;EOF&#39;</span>
+<span class="s">OPENAI_API_KEY=sk-...</span>
+<span class="s">WANDB_BASE_URL=...</span>
+<span class="s">WANDB_API_KEY=...</span>
+<span class="s">EOF</span>
+</code></pre></div>
+
+<p><code>launch_agent.py</code> calls <code>load_dotenv()</code>, so <code>.env</code> is picked up automatically.</p>
+<h3 id="1-launch-the-persistent-vllm-serve-job">1. Launch the persistent vLLM serve job</h3>
+<p>Give it a generous <code>--time</code> so it isn't killed mid-eval. For example, an
+interactive allocation:</p>
+<div class="codehilite"><pre><span></span><code>srun<span class="w"> </span>--account<span class="o">=</span>example_account<span class="w"> </span>--qos<span class="o">=</span>example_qos<span class="w"> </span>--partition<span class="o">=</span>example_partition<span class="w"> </span><span class="se">\ </span>--gpus-per-node<span class="o">=</span><span class="m">1</span><span class="w"> </span>--time<span class="o">=</span><span class="m">1440</span><span class="w"> </span>--pty<span class="w"> </span>bash
+<span class="c1"># then, on the GPU node:</span>
+vllm<span class="w"> </span>serve<span class="w"> </span>google/gemma-4-E2B-it<span class="w"> </span>--host<span class="w"> </span><span class="m">0</span>.0.0.0<span class="w"> </span>--port<span class="w"> </span><span class="m">8000</span>
+</code></pre></div>
+
+<p>Confirm it's healthy from its own node:</p>
+<div class="codehilite"><pre><span></span><code>srun<span class="w"> </span>--overlap<span class="w"> </span>--jobid<span class="o">=</span>&lt;vllm-job&gt;<span class="w"> </span>--pty<span class="w"> </span>curl<span class="w"> </span>-s<span class="w"> </span>http://localhost:8000/v1/models
+<span class="c1"># expect: ...google/gemma-4-E2B-it...</span>
+</code></pre></div>
+
+<h3 id="2-submit-the-eval-job">2. Submit the eval job</h3>
+<p><code>scripts/conduct_slurm.sh</code> requests a CPU allocation, finds the vLLM node, and
+runs <code>scripts/conduct.sh</code> pointed at it with <code>use_wandb=True</code>:</p>
+<div class="codehilite"><pre><span></span><code><span class="c1"># smoke test (1 run)</span>
+<span class="nv">AGENTS</span><span class="o">=</span>gemma-4-e2b-it<span class="w"> </span><span class="nv">COUNT</span><span class="o">=</span><span class="m">1</span><span class="w"> </span>sbatch<span class="w"> </span>scripts/conduct_slurm.sh
+
+<span class="c1"># larger sweep</span>
+<span class="nv">AGENTS</span><span class="o">=</span><span class="s2">&quot;gemma-4-e2b-it&quot;</span><span class="w"> </span><span class="nv">COUNT</span><span class="o">=</span><span class="m">20</span><span class="w"> </span><span class="nv">MAX_PARALLEL</span><span class="o">=</span><span class="m">4</span><span class="w"> </span>sbatch<span class="w"> </span>scripts/conduct_slurm.sh
+</code></pre></div>
+
+<p><strong>Discovery:</strong> the wrapper lists your running jobs (<code>squeue --me</code>), expands their
+nodelists, excludes the eval node itself, and probes each <code>http://&lt;node&gt;:8000/v1/models</code>,
+selecting the first one serving <code>google/gemma-4-E2B-it</code>. It probes by <em>serving the
+model</em>, so it doesn't matter how the vLLM job was started (e.g. a <code>bash</code>-named
+<code>srun --pty</code>).</p>
+<p><strong>Override:</strong> skip discovery by pinning the node:</p>
+<div class="codehilite"><pre><span></span><code><span class="nv">VLLM_HOST</span><span class="o">=</span>example_host<span class="w"> </span><span class="nv">AGENTS</span><span class="o">=</span>gemma-4-e2b-it<span class="w"> </span><span class="nv">COUNT</span><span class="o">=</span><span class="m">1</span><span class="w"> </span>sbatch<span class="w"> </span>scripts/conduct_slurm.sh
+</code></pre></div>
+
+<p>Other env overrides: <code>VLLM_MODEL</code>, <code>VLLM_PORT</code>, and <code>WANDB_MODE</code> (set
+<code>WANDB_MODE=offline</code> to skip online logging). Extra CLI args are forwarded
+verbatim to <code>launch_agent.py</code> as Hydra overrides.</p>
+<p><strong>Fallback if compute→compute <code>:8000</code> is firewalled:</strong> run the eval inside the
+vLLM job's own allocation and talk to it over localhost:</p>
+<div class="codehilite"><pre><span></span><code>srun<span class="w"> </span>--overlap<span class="w"> </span>--jobid<span class="o">=</span>&lt;vllm-job&gt;<span class="w"> </span><span class="se">\</span>
+<span class="w">  </span>env<span class="w"> </span><span class="nv">AGENTS</span><span class="o">=</span>gemma-4-e2b-it<span class="w"> </span><span class="nv">COUNT</span><span class="o">=</span><span class="m">1</span><span class="w"> </span><span class="nv">VLLM_HOST</span><span class="o">=</span>localhost<span class="w"> </span><span class="se">\</span>
+<span class="w">  </span>./scripts/conduct.sh<span class="w"> </span>agent.hostname<span class="o">=</span>localhost<span class="w"> </span><span class="nv">use_wandb</span><span class="o">=</span>True
+</code></pre></div>
+
+<h3 id="3-check-results">3. Check results</h3>
+<ul>
+<li>SLURM log: <code>slurm-&lt;jobid&gt;.out</code> — confirm discovery selected the vLLM node and
+  there are no "Connection error" messages.</li>
+<li>Per-run logs: <code>log_outputs/&lt;stamp&gt;/run-*.log</code> — confirm an action is produced.</li>
+<li>W&amp;B: a run should appear in <code>open_apps_${USER}</code> (i.e. <code>open_apps_aaronsmulktis</code>)
+  with the expected <code>group</code>/<code>job_type</code> and a logged <code>web_app_url</code>.</li>
+</ul>
   </div>
 </article>
                                 <div class="mx-auto flex flex-wrap h-16 w-full max-w-2xl items-center gap-2 px-4 md:px-0">
@@ -687,6 +774,40 @@ <h2 id="creating-your-own-agent">Creating Your Own Agent</h2>
         
 
         
+        <a href="#running-evals-on-a-cluster-slurm-vllm-wb"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="2">
+            Running Evals on a Cluster (SLURM + vLLM + W&amp;B)
+        </a>
+        
+        
+        <a href="#one-time-cluster-setup"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            One-time cluster setup
+        </a>
+        
+        <a href="#1-launch-the-persistent-vllm-serve-job"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            1. Launch the persistent vLLM serve job
+        </a>
+        
+        <a href="#2-submit-the-eval-job"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            2. Submit the eval job
+        </a>
+        
+        <a href="#3-check-results"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            3. Check results
+        </a>
+        
+        
+
+        
         
         
         
diff --git a/site/index.html b/site/index.html
index 6068c70c..0c0b2d7e 100644
--- a/site/index.html
+++ b/site/index.html
@@ -475,31 +475,68 @@ <h3 id="app-variations">App variations</h3>
 </code></pre></div>
 
 <p>OpenApps also comes with pre-defined variations that can affect the content and appearance of apps.</p>
-<h4 id="appearance">Appearance</h4>
+<p>Appearance is split along two axes:</p>
+<ul>
+<li><strong>Theme</strong> -- <em>look</em>: colors, typography, shape. One shared set of design
+  tokens in <code>config/apps/theme/</code>, applied to <strong>every</strong> app at once.</li>
+<li><strong>Layout</strong> -- <em>structure</em>: how an individual app arranges itself. Per-app,
+  under <code>config/apps/&lt;app&gt;/layout/</code>.</li>
+</ul>
+<h4 id="theme">Theme</h4>
 <div class="tabbed-set" data-tabs="1:3"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><label for="__tabbed_1_1">challenging font</label><div class="tabbed-content">
-<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">APPEARANCE</span><span class="o">=</span>challenging_font
+<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">THEME</span><span class="o">=</span>challenging_font
 </code></pre></div>
 
 <p><img alt="landing" src="images/landing-challenging-font.png" /></p>
 </div>
 <input id="__tabbed_1_2" name="__tabbed_1" type="radio" /><label for="__tabbed_1_2">dark theme</label><div class="tabbed-content">
-<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">APPEARANCE</span><span class="o">=</span>dark_theme
+<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">THEME</span><span class="o">=</span>dark
 </code></pre></div>
 
 <p><img alt="landing" src="images/landing-dark.png" /></p>
 </div>
 <input id="__tabbed_1_3" name="__tabbed_1" type="radio" /><label for="__tabbed_1_3">default</label><div class="tabbed-content">
-<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">APPEARANCE</span><span class="o">=</span>default
+<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">THEME</span><span class="o">=</span>default
 </code></pre></div>
 
 <p><img alt="landing" src="images/landing.png" /></p>
 </div>
 </div>
-<p>Launch specific apps with selected appearance:</p>
-<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/start_page/appearance<span class="o">=</span><span class="nv">$APPEARANCE</span>
+<p>A single override themes every app:</p>
+<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/theme<span class="o">=</span><span class="nv">$THEME</span>
+</code></pre></div>
+
+<p>Or one app only, leaving the rest on the global theme:
+<code>uv run launch.py apps.calendar.theme=$THEME</code>.</p>
+<p>Shipped themes: <code>default</code>, <code>dark</code>, <code>mono</code>, <code>challenging_font</code>, <code>colorblind</code>,
+<code>solarized</code>, <code>material</code>, <code>bootstrap</code>. Adding one means adding a yaml file to
+<code>config/apps/theme/</code> -- no app code changes.</p>
+<p>A theme file is a set of design tokens plus a small <code>assets</code> block:</p>
+<div class="codehilite"><pre><span></span><code><span class="c1"># config/apps/theme/dark.yaml</span>
+<span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dark</span>
+<span class="nt">tokens</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">color-bg</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;#121212&quot;</span><span class="w">       </span><span class="c1"># -&gt; --color-bg, consumed as var(--color-bg)</span>
+<span class="w">  </span><span class="nt">color-primary</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;#bb86fc&quot;</span>
+<span class="w">  </span><span class="nt">font-family</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&#39;Inter&#39;,</span><span class="nv"> </span><span class="s">system-ui,</span><span class="nv"> </span><span class="s">sans-serif&quot;</span>
+<span class="w">  </span><span class="nt">radius</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;4px&quot;</span>
+<span class="nt">assets</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">tone</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dark</span><span class="w">                </span><span class="c1"># apps map this onto their own non-CSS assets</span>
+<span class="w">  </span><span class="nt">icon_set</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bw</span>
 </code></pre></div>
 
-<p>Or specific apps with: <code>apps/calendar/appearance=$APPEARANCE</code>.</p>
+<p>Every <code>tokens</code> entry becomes a CSS custom property. <code>assets</code> covers the
+choices a CSS variable cannot reach -- the start page's raster icons, the
+Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately
+app-agnostic: the theme says <code>tone: dark</code> and each app picks its own dark
+asset, so a theme file never has to know which apps exist.</p>
+<h4 id="layout">Layout</h4>
+<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/todo/layout<span class="o">=</span>kanban_board
+uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/start_page/layout<span class="o">=</span>broken_logos
+</code></pre></div>
+
+<p>Available layouts: <code>todo</code> has <code>default</code> and <code>kanban_board</code>; <code>start_page</code> has
+<code>default</code>, <code>broken_logos</code> (icons detached from their tiles) and
+<code>clickable_logos</code>; the other apps currently have <code>default</code> only.</p>
 <h4 id="content">Content</h4>
 <div class="tabbed-set" data-tabs="2:3"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><label for="__tabbed_2_1">german</label><div class="tabbed-content">
 <div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">CONTENT</span><span class="o">=</span>german
@@ -524,7 +561,14 @@ <h4 id="content">Content</h4>
 </code></pre></div>
 
 <p>Or specific apps with: <code>apps/calendar/content=$CONTENT</code>.</p>
-<p>You can see the specific variables for each defined in the individual apps. For example, <code>config/apps/maps/appearance/dark_theme.yaml</code>.</p>
+<p>You can see the specific variables for each defined in the individual apps.
+For example, <code>config/apps/theme/dark.yaml</code> for the shared design tokens,
+<code>config/apps/start_page/layout/broken_logos.yaml</code> for a per-app structure
+variant, and <code>config/apps/maps/default.yaml</code> for behaviour (map zoom, tile
+layer, route planning) that is neither.</p>
+<p>Optional: to save screenshots of all apps with a specific variation for testing, we offer <code>tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/</code> to make this easy.</p>
+<h2 id="exposing-openapps-as-an-mcp-server">Exposing OpenApps as an MCP server</h2>
+<p>If you want an agent to interact with OpenApps using <a href="https://modelcontextprotocol.io/docs/getting-started/intro">MCP</a> please see <code>src/mcp/README.md</code>.</p>
 <h2 id="launch-agent">Launch Agent</h2>
 <p>For agents to directly interact with apps, install: <code>playwright install chromium</code>.</p>
 <p>Launch an agent to perform a task of <em>adding a meeting with Dennis to the calendar</em>:</p>
@@ -588,16 +632,44 @@ <h2 id="launch-agents-across-multiple-tasks">Launch Agent(s) Across Multiple Tas
 <span class="w">  </span><span class="nt">app_variations</span><span class="p">:</span>
 <span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;apps/start_page/content=default&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;apps/calendar/content=german&quot;</span><span class="p p-Indicator">]</span>
 <span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span>
-<span class="w">        </span><span class="s">&quot;apps/start_page/appearance=dark_theme&quot;</span><span class="p p-Indicator">,</span>
-<span class="w">        </span><span class="s">&quot;apps/calendar/appearance=dark_theme&quot;</span><span class="p p-Indicator">,</span>
+<span class="w">        </span><span class="s">&quot;apps/theme=dark&quot;</span><span class="p p-Indicator">,</span>
 <span class="w">      </span><span class="p p-Indicator">]</span>
 </code></pre></div>
 
 <p>You can modify the set of tasks or app variation by updating the <code>config_parallel_tasks.yaml</code>. We ensure:</p>
 <ul>
-<li>Each deployment of OpenApps can have different appearance and content per app.</li>
+<li>Each deployment of OpenApps can have a different theme (global), plus layout and content per app.</li>
 <li>Each task is launched in an isolated environment for reproducible results.</li>
 </ul>
+<p>To run <strong>every</strong> task in the loaded tasks config (rather than listing a subset by
+hand), set <code>task_names</code> to <code>all</code>. This expands to all task names defined in the
+selected <code>tasks=</code> group, so it composes with any tasks file:</p>
+<div class="codehilite"><pre><span></span><code>uv run launch_parallel_agents.py \
+  mode=slurm_cluster agent=dummy tasks=longer_horizon \
+  parallel_tasks.task_names=all use_wandb=True
+</code></pre></div>
+
+<p>Passing an explicit list (e.g. <code>parallel_tasks.task_names=[task_a,task_b]</code>) still
+runs only that subset.</p>
+<p>You can also select a task group to run via <code>tasks=longer_horizon parallel_tasks.task_names=all</code>.</p>
+<h3 id="running-across-goal-variations">Running across goal variations</h3>
+<p>Every task ships with <strong>goal variations</strong> — the same task with the goal reworded
+in a different style. Styles are <code>casual</code>, <code>formal</code>, and <code>unrelated_context</code>
+(the instruction wrapped in unrelated chit-chat), with 9 variations per task.
+They live in <code>config/tasks/user_goal_variations.yaml</code>, keyed
+<code>&lt;original_task&gt;__&lt;style&gt;_&lt;n&gt;</code> (e.g. <code>add_meeting_with_dennis__formal_1</code>), and
+each one preserves the original task's reward — only the <code>goal</code> wording differs
+and a <code>goal_style</code> field records the style.</p>
+<p>To run agents across <strong>all</strong> tasks and their goal variations in parallel, use
+the dedicated config, which lists every task name swept over a single default
+app variation:</p>
+<div class="codehilite"><pre><span></span><code><span class="n">uv</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="n">launch_parallel_agents</span><span class="o">.</span><span class="n">py</span><span class="w"> </span>\
+<span class="w">  </span><span class="o">--</span><span class="n">config</span><span class="o">-</span><span class="n">name</span><span class="o">=</span><span class="n">config_parallel_tasks_across_goal_variations</span><span class="w"> </span><span class="n">mode</span><span class="o">=</span><span class="n">slurm_cluster</span>
+</code></pre></div>
+
+<p>Use <code>mode=local</code> to run the jobs sequentially in the current process instead of
+on SLURM. This expands to one isolated job per goal phrasing, letting you
+measure how robust an agent is to how the same task is worded.</p>
 <h2 id="testing">Testing</h2>
 <p>Run all tests via:</p>
 <div class="codehilite"><pre><span></span><code><span class="n">uv</span> <span class="n">run</span> <span class="o">-</span><span class="n">m</span> <span class="n">pytest</span> <span class="n">tests</span><span class="o">/</span>
@@ -724,10 +796,16 @@ <h2 id="attribution">Attribution</h2>
         </a>
         
         
-        <a href="#appearance"
+        <a href="#theme"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            Theme
+        </a>
+        
+        <a href="#layout"
             class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
             data-active="false" data-depth="3">
-            Appearance
+            Layout
         </a>
         
         <a href="#content"
@@ -739,6 +817,14 @@ <h2 id="attribution">Attribution</h2>
         
 
         
+        <a href="#exposing-openapps-as-an-mcp-server"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="2">
+            Exposing OpenApps as an MCP server
+        </a>
+        
+
+        
         <a href="#launch-agent"
             class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
             data-active="false" data-depth="2">
@@ -761,6 +847,14 @@ <h2 id="attribution">Attribution</h2>
             Launch Agent(s) Across Multiple Tasks
         </a>
         
+        
+        <a href="#running-across-goal-variations"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            Running across goal variations
+        </a>
+        
+        
 
         
         <a href="#testing"
diff --git a/site/index.md b/site/index.md
index 8b980c3e..a338017d 100644
--- a/site/index.md
+++ b/site/index.md
@@ -46,12 +46,19 @@ uv run launch.py 'apps.todo.init_todos=[["Call Mom", false]]'
 
 OpenApps also comes with pre-defined variations that can affect the content and appearance of apps.
 
-#### Appearance
+Appearance is split along two axes:
+
+* **Theme** -- *look*: colors, typography, shape. One shared set of design
+  tokens in `config/apps/theme/`, applied to **every** app at once.
+* **Layout** -- *structure*: how an individual app arranges itself. Per-app,
+  under `config/apps/<app>/layout/`.
+
+#### Theme
 
 /// tab | challenging font
 
     ::bash
-    export APPEARANCE=challenging_font
+    export THEME=challenging_font
 
 
 ![landing](images/landing-challenging-font.png)
@@ -59,25 +66,62 @@ OpenApps also comes with pre-defined variations that can affect the content and
 /// tab | dark theme
 
     ::bash
-    export APPEARANCE=dark_theme
+    export THEME=dark
 
 ![landing](images/landing-dark.png)
 ///
 /// tab | default
 
     ::bash
-    export APPEARANCE=default
+    export THEME=default
 
 ![landing](images/landing.png)
 
 ///
 
-Launch specific apps with selected appearance:
+A single override themes every app:
+```shell
+uv run launch.py apps/theme=$THEME
+```
+
+Or one app only, leaving the rest on the global theme:
+`uv run launch.py apps.calendar.theme=$THEME`.
+
+Shipped themes: `default`, `dark`, `mono`, `challenging_font`, `colorblind`,
+`solarized`, `material`, `bootstrap`. Adding one means adding a yaml file to
+`config/apps/theme/` -- no app code changes.
+
+A theme file is a set of design tokens plus a small `assets` block:
+
+```yaml
+# config/apps/theme/dark.yaml
+name: dark
+tokens:
+  color-bg: "#121212"       # -> --color-bg, consumed as var(--color-bg)
+  color-primary: "#bb86fc"
+  font-family: "'Inter', system-ui, sans-serif"
+  radius: "4px"
+assets:
+  tone: dark                # apps map this onto their own non-CSS assets
+  icon_set: bw
+```
+
+Every `tokens` entry becomes a CSS custom property. `assets` covers the
+choices a CSS variable cannot reach -- the start page's raster icons, the
+Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately
+app-agnostic: the theme says `tone: dark` and each app picks its own dark
+asset, so a theme file never has to know which apps exist.
+
+#### Layout
+
 ```shell
-uv run launch.py apps/start_page/appearance=$APPEARANCE
+uv run launch.py apps/todo/layout=kanban_board
+uv run launch.py apps/start_page/layout=broken_logos
 ```
 
-Or specific apps with: `apps/calendar/appearance=$APPEARANCE`.
+Available layouts: `todo` has `default` and `kanban_board`; `start_page` has
+`default`, `broken_logos` (icons detached from their tiles) and
+`clickable_logos`; the other apps currently have `default` only.
 
 #### Content
 
@@ -111,7 +155,17 @@ uv run launch.py apps/start_page/content=$CONTENT
 
 Or specific apps with: `apps/calendar/content=$CONTENT`.
 
-You can see the specific variables for each defined in the individual apps. For example, `config/apps/maps/appearance/dark_theme.yaml`.
+You can see the specific variables for each defined in the individual apps.
+For example, `config/apps/theme/dark.yaml` for the shared design tokens,
+`config/apps/start_page/layout/broken_logos.yaml` for a per-app structure
+variant, and `config/apps/maps/default.yaml` for behaviour (map zoom, tile
+layer, route planning) that is neither.
+
+Optional: to save screenshots of all apps with a specific variation for testing, we offer `tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/` to make this easy.
+
+## Exposing OpenApps as an MCP server
+
+If you want an agent to interact with OpenApps using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) please see `src/mcp/README.md`.
 
 ## Launch Agent
 
@@ -192,16 +246,52 @@ parallel_tasks:
   app_variations:
     - ["apps/start_page/content=default", "apps/calendar/content=german"]
     - [
-        "apps/start_page/appearance=dark_theme",
-        "apps/calendar/appearance=dark_theme",
+        "apps/theme=dark",
       ]
 ```
 
 You can modify the set of tasks or app variation by updating the `config_parallel_tasks.yaml`. We ensure:
 
-* Each deployment of OpenApps can have different appearance and content per app.
+* Each deployment of OpenApps can have a different theme (global), plus layout and content per app.
 * Each task is launched in an isolated environment for reproducible results.
 
+To run **every** task in the loaded tasks config (rather than listing a subset by
+hand), set `task_names` to `all`. This expands to all task names defined in the
+selected `tasks=` group, so it composes with any tasks file:
+
+```
+uv run launch_parallel_agents.py \
+  mode=slurm_cluster agent=dummy tasks=longer_horizon \
+  parallel_tasks.task_names=all use_wandb=True
+```
+
+Passing an explicit list (e.g. `parallel_tasks.task_names=[task_a,task_b]`) still
+runs only that subset.
+
+You can also select a task group to run via `tasks=longer_horizon parallel_tasks.task_names=all`.
+
+### Running across goal variations
+
+Every task ships with **goal variations** — the same task with the goal reworded
+in a different style. Styles are `casual`, `formal`, and `unrelated_context`
+(the instruction wrapped in unrelated chit-chat), with 9 variations per task.
+They live in `config/tasks/user_goal_variations.yaml`, keyed
+`<original_task>__<style>_<n>` (e.g. `add_meeting_with_dennis__formal_1`), and
+each one preserves the original task's reward — only the `goal` wording differs
+and a `goal_style` field records the style.
+
+To run agents across **all** tasks and their goal variations in parallel, use
+the dedicated config, which lists every task name swept over a single default
+app variation:
+
+```
+uv run launch_parallel_agents.py \
+  --config-name=config_parallel_tasks_across_goal_variations mode=slurm_cluster
+```
+
+Use `mode=local` to run the jobs sequentially in the current process instead of
+on SLURM. This expands to one isolated job per goal phrasing, letting you
+measure how robust an agent is to how the same task is worded.
 
 ## Testing
 
diff --git a/site/search/search_index.json b/site/search/search_index.json
index 7a952371..a83c0f25 100644
--- a/site/search/search_index.json
+++ b/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance challenging font export APPEARANCE = challenging_font dark theme export APPEARANCE = dark_theme default export APPEARANCE = default Launch specific apps with selected appearance: uv run launch.py apps/start_page/appearance = $APPEARANCE Or specific apps with: apps/calendar/appearance=$APPEARANCE . Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/maps/appearance/dark_theme.yaml . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/start_page/appearance=dark_theme\" , \"apps/calendar/appearance=dark_theme\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have different appearance and content per app. Each task is launched in an isolated environment for reproducible results. Testing Run all tests via: uv run - m pytest tests / Attribution 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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps.","title":"App variations"},{"location":"#appearance","text":"challenging font export APPEARANCE = challenging_font dark theme export APPEARANCE = dark_theme default export APPEARANCE = default Launch specific apps with selected appearance: uv run launch.py apps/start_page/appearance = $APPEARANCE Or specific apps with: apps/calendar/appearance=$APPEARANCE .","title":"Appearance"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/maps/appearance/dark_theme.yaml .","title":"Content"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/start_page/appearance=dark_theme\" , \"apps/calendar/appearance=dark_theme\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have different appearance and content per app. Each task is launched in an isolated environment for reproducible results.","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./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. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ . Theme challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist. Layout uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only. Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy. Exposing OpenApps as an MCP server If you want an agent to interact with OpenApps using MCP please see src/mcp/README.md . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all . Running across goal variations Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded. Testing Run all tests via: uv run - m pytest tests / Attribution 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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ .","title":"App variations"},{"location":"#theme","text":"challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist.","title":"Theme"},{"location":"#layout","text":"uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only.","title":"Layout"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy.","title":"Content"},{"location":"#exposing-openapps-as-an-mcp-server","text":"If you want an agent to interact with OpenApps using MCP please see src/mcp/README.md .","title":"Exposing OpenApps as an MCP server"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all .","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#running-across-goal-variations","text":"Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded.","title":"Running across goal variations"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements. Running Evals on a Cluster (SLURM + vLLM + W&B) The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it. One-time cluster setup The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically. 1. Launch the persistent vLLM serve job Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it... 2. Submit the eval job scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True 3. Check results SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"agents/#running-evals-on-a-cluster-slurm-vllm-wb","text":"The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it.","title":"Running Evals on a Cluster (SLURM + vLLM + W&amp;B)"},{"location":"agents/#one-time-cluster-setup","text":"The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically.","title":"One-time cluster setup"},{"location":"agents/#1-launch-the-persistent-vllm-serve-job","text":"Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it...","title":"1. Launch the persistent vLLM serve job"},{"location":"agents/#2-submit-the-eval-job","text":"scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True","title":"2. Submit the eval job"},{"location":"agents/#3-check-results","text":"SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"3. Check results"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./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. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task . Goal Variations Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"},{"location":"tasks/#goal-variations","text":"Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Goal Variations"}]}
\ No newline at end of file
diff --git a/site/sitemap.xml b/site/sitemap.xml
index 50f32dae..c0ff6e23 100644
--- a/site/sitemap.xml
+++ b/site/sitemap.xml
@@ -2,42 +2,22 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/</loc>
-<<<<<<< HEAD
-         <lastmod>2026-04-13</lastmod>
+         <lastmod>2026-09-01</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/Intro%20to%20UI%20Agents/</loc>
-         <lastmod>2026-04-13</lastmod>
+         <lastmod>2026-09-01</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/agents/</loc>
-         <lastmod>2026-04-13</lastmod>
+         <lastmod>2026-09-01</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/installation/</loc>
-         <lastmod>2026-04-13</lastmod>
+         <lastmod>2026-09-01</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/tasks/</loc>
-         <lastmod>2026-04-13</lastmod>
-=======
-         <lastmod>2026-04-03</lastmod>
-    </url>
-    <url>
-         <loc>https://facebookresearch.github.io/OpenApps/Intro%20to%20UI%20Agents/</loc>
-         <lastmod>2026-04-03</lastmod>
-    </url>
-    <url>
-         <loc>https://facebookresearch.github.io/OpenApps/agents/</loc>
-         <lastmod>2026-04-03</lastmod>
-    </url>
-    <url>
-         <loc>https://facebookresearch.github.io/OpenApps/installation/</loc>
-         <lastmod>2026-04-03</lastmod>
-    </url>
-    <url>
-         <loc>https://facebookresearch.github.io/OpenApps/tasks/</loc>
-         <lastmod>2026-04-03</lastmod>
->>>>>>> 655adeaf76133621c1ecd692ac0ef1bce96f2815
+         <lastmod>2026-09-01</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/site/sitemap.xml.gz b/site/sitemap.xml.gz
index df7eecbe913886f7ec97e159070e1cd835391f0f..996f272771418aca66f31347a6c17612af881f55 100644
GIT binary patch
literal 248
zcmV<U00;jciwFpS6_#oO|8r?{Wo=<_E_iKh0L@ZOZ^AGPz4I%oNINzTJxpV2gSbrM
z#AW<|5WF@bO`_P){rshXrrkL(AN(czy(i1<`g`=%1v9xAI<b^WR2XbLy3luG|M^kB
ziM3v|=j;i&D#L*~F)*ihfN7c}ImXc>k}>x{b|?kGy$MRLgkDs|W`J9Ewbn<gXA~+h
zU&i7g##2T@lkFgT$HVy`U4&i2ut|xag?ZyIfFT~^Q8%i2t<|bl%QABB-5BAQ@=@|_
y;2d8X#k1RQi`(=V_{plwKhWR;vGLw;`JU%0VMC_}j&Tj;!}Sl<!j%aT0{{Teb$agr

literal 249
zcmV<V00#dbiwFn+GTdnb|8r?{Wo=<_E_iKh0L@ZOPs1<_z3*34kvKNa3POO|OuHcM
z#D)EUEc4oEX%fXA<>!-b6XL$Z@WEfQ-+Qv$uD(ZKePJdSLnoF}i3)>_dl&jnY(L-Y
z7qQZd_LMy#S7kU*CkE#91~5&NB*!?KL^9?c$PT3-xHdt_SD_bGu^Hf!ovroJ>KTO!
z%)waP#dyp}XtEt-?|3-vq>J#8FsxG|Xkp&?3t))HxYvzpo@@0~FCWXuwRd5JU&>p_
zH-U3}XcW(GyD4tnW8gchGXFq>3&h5I!{vMKtAq_5Z#c#|ln>WGu^IpI5d#1K&FpxW

diff --git a/site/tasks/index.html b/site/tasks/index.html
index 00231596..d4a4d370 100644
--- a/site/tasks/index.html
+++ b/site/tasks/index.html
@@ -490,6 +490,34 @@ <h3 id="new-custom-tasks">New custom tasks</h3>
 </code></pre></div>
 
 <p>Finally, ask your agent to solve the task by specifying <code>task_name=my_custom_task</code>.</p>
+<h2 id="goal-variations">Goal Variations</h2>
+<p>Tasks come with <strong>goal variations</strong>: the same task with its goal reworded in a
+different style, so you can study how robust an agent is to phrasing. There are
+three styles — <code>casual</code>, <code>formal</code>, and <code>unrelated_context</code> (the instruction
+embedded in unrelated chit-chat) — with 9 variations per task.</p>
+<p>Tasks are split across two files, both composed into <code>all_tasks.yaml</code>:</p>
+<ul>
+<li><code>config/tasks/original_tasks.yaml</code> — the base tasks.</li>
+<li><code>config/tasks/user_goal_variations.yaml</code> — the variations, keyed
+  <code>&lt;original_task&gt;__&lt;style&gt;_&lt;n&gt;</code> (e.g. <code>mark_water_plants_as_done__casual_2</code>).</li>
+</ul>
+<p>Every variation copies its original's fields verbatim — only the <code>goal</code> is
+reworded, and an optional <code>goal_style</code> field records the style — so the reward
+logic is identical to the base task:</p>
+<div class="codehilite"><pre><span></span><code><span class="nt">mark_water_plants_as_done__casual_2</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">_target_</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">open_apps.tasks.tasks.MarkToDoDoneTask</span>
+<span class="w">  </span><span class="nt">goal</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">can you check off &#39;Water plants&#39; in my to-do list?</span>
+<span class="w">  </span><span class="nt">todo_name</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;Water</span><span class="nv"> </span><span class="s">plants&quot;</span>
+<span class="w">  </span><span class="nt">goal_style</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">casual</span>
+</code></pre></div>
+
+<p>Run a single variation like any other task:</p>
+<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch_agent.py<span class="w"> </span><span class="nv">agent</span><span class="o">=</span>GPT-5-1<span class="w"> </span><span class="nv">task_name</span><span class="o">=</span>mark_water_plants_as_done__casual_2
+</code></pre></div>
+
+<p>To run agents across <strong>all</strong> tasks and their goal variations in parallel, use
+the <code>config_parallel_tasks_across_goal_variations.yaml</code> config — see
+<a href="../#launch-agents-across-multiple-tasks">Launch Agent(s) Across Multiple Tasks</a>.</p>
   </div>
 </article>
                                 <div class="mx-auto flex flex-wrap h-16 w-full max-w-2xl items-center gap-2 px-4 md:px-0">
@@ -576,12 +604,28 @@ <h3 id="new-custom-tasks">New custom tasks</h3>
         
         
         
-        <a href="#new-custom-tasks"
+        <a href="#adding-new-tasks"
             class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
             data-active="false" data-depth="2">
+            Adding New Tasks
+        </a>
+        
+        
+        <a href="#new-custom-tasks"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
             New custom tasks
         </a>
         
+        
+
+        
+        <a href="#goal-variations"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="2">
+            Goal Variations
+        </a>
+        
 
         
         
diff --git a/src/open_apps/apps/calendar_app/main.py b/src/open_apps/apps/calendar_app/main.py
index 0b702009..f72886db 100644
--- a/src/open_apps/apps/calendar_app/main.py
+++ b/src/open_apps/apps/calendar_app/main.py
@@ -13,7 +13,7 @@
     HighlightJS, database, dataclass)
 from datetime import datetime, timedelta
 from src.open_apps.frontend import local_hdrs
-from src.open_apps.theme import legacy_theme_style
+from src.open_apps.theme import render_theme_css, resolve_theme
 import calendar
 import os
 import logging
@@ -30,160 +30,136 @@
 # fix relative path issue
 current_dir = os.path.dirname(os.path.abspath(__file__))
 
-def generate_styles_from_config(config):
-    """Generate CSS styles from configuration"""
-    if not hasattr(config.calendar, 'style'):
-        raise ValueError("Calendar config does not contain 'style' section")
-    
-    # Extract style config
-    style_config = config.calendar.style
-    colors = style_config.colors
-    typography = style_config.typography
-    buttons = style_config.buttons
-    layout = style_config.layout
-    
-    # Build CSS with variables
-    return f"""
-        /* Custom CSS Variables */
-        :root {{
-            --primary: {colors.primary};
-            --primary-hover: {colors.primary_hover};
-            --secondary: {colors.secondary};
-            --background: {colors.background};
-            --text: {colors.text};
-            --error: {colors.error};
-            --border: {colors.border};
-            --font-family: {typography.font_family};
-            --heading-font: {typography.heading_font};
-            --base-font-size: {typography.base_font_size};
-            --heading-size: {typography.heading_size};
-            --button-border-radius: {buttons.border_radius};
-            --button-padding: {buttons.padding};
-            --container-width: {layout.container_width};
-            --spacing: {layout.spacing};
-        }}
-        
-        /* Base styles */
-        body {{
-            font-family: var(--font-family);
-            font-size: var(--base-font-size);
-            color: var(--text);
-            background-color: var(--background);
-        }}
-        
-        h1, h2, h3, h4, h5, h6 {{
-            font-family: var(--heading-font);
-        }}
-        
-        h1 {{
-            font-size: var(--heading-size);
-        }}
-        
-        /* Button styles */
-        [role="button"], button {{
-            border-radius: var(--button-border-radius);
-            padding: var(--button-padding);
-        }}
-        
-        /* Apply primary color to buttons */
-        [role="button"]:not(.outline):not(.secondary),
-        button:not(.outline):not(.secondary) {{
-            background-color: var(--primary);
-            border-color: var(--primary);
-        }}
-        
-        /* Apply hover state for primary buttons */
-        [role="button"]:not(.outline):not(.secondary):hover,
-        button:not(.outline):not(.secondary):hover {{
-            background-color: var(--primary-hover);
-            border-color: var(--primary-hover);
-        }}
-        
-        /* Secondary buttons */
-        [role="button"].secondary,
-        button.secondary {{
-            background-color: var(--secondary);
-            border-color: var(--secondary);
-        }}
-        
-        /* Apply border color to form elements */
-        input, select, textarea {{
-            border: 1px solid var(--border);
-            border-radius: var(--button-border-radius);
-        }}
-
-        [role="button"].outline,
-        button.outline {{
-            background-color: var(--background);
-            border-color: var(--border);
-            color: var(--primary);
-        }}
-        
-        /* Apply container width */
-        #calendar-container {{
-            width: var(--container-width);
-            margin: 0 auto;
-        }}
-        
-        /* Apply border color to tables */
-        table, th, td {{
-            border-color: var(--border);
-        }}
-        
-        /* Calendar days */
-        .calendar-cell {{
-            border: 1px solid var(--border);
-            background-color: var(--background);
-        }}
-        
-        /* Links */
-        a:not([role="button"]) {{
-            color: var(--primary);
-        }}
-        
-        a:not([role="button"]):hover {{
-            color: var(--primary-hover);
-        }}
-        
-        /* Calendar app specific styles */
-        .logo-title-container {{
-            display: flex;
-            align-items: center;
-            text-decoration: none;
-        }}
-        
-        .custom-logo {{
-            max-height: 50px;
-            margin-right: 10px;
-        }}
-        .calendar-title {{
-            margin: 0;
-            color: var(--primary);
-        }}
-        
-        .logo-title-container a {{
-            text-decoration: none;
-        }}
-        
-        .button-container {{
-            display: flex;
-            justify-content: space-between;
-            margin-top: var(--spacing);
-        }}
-        
-        .error-message {{
-            background-color: rgba(220, 53, 69, 0.1);
-            color: var(--error);
-            padding: var(--spacing);
-            margin-bottom: var(--spacing);
-            border-radius: var(--button-border-radius);
-            text-align: center;
-        }}
-    """
+# Static, theme-agnostic component styles. Every color, font and radius is a
+# design token from the shared theme (`config/apps/theme/`), resolved
+# per-request by `calendar_theme()`; the three structural values the calendar
+# owns come from its `layout` group as `--layout-*`. Nothing here depends on
+# the config, so this block is built once at import instead of rebuilt in
+# `set_environment`.
+_COMPONENT_CSS = """
+    /* Base styles */
+    body {
+        font-family: var(--font-family);
+        font-size: var(--font-size-base);
+        color: var(--color-fg);
+        background-color: var(--color-bg);
+    }
+
+    h1, h2, h3, h4, h5, h6 {
+        font-family: var(--font-heading);
+    }
+
+    h1 {
+        font-size: var(--font-size-heading);
+    }
+
+    /* Button styles */
+    [role="button"], button {
+        border-radius: var(--radius);
+        padding: var(--layout-button-padding);
+    }
+
+    /* Apply primary color to buttons */
+    [role="button"]:not(.outline):not(.secondary),
+    button:not(.outline):not(.secondary) {
+        background-color: var(--color-primary);
+        border-color: var(--color-primary);
+        color: var(--color-on-primary);
+    }
+
+    /* Apply hover state for primary buttons */
+    [role="button"]:not(.outline):not(.secondary):hover,
+    button:not(.outline):not(.secondary):hover {
+        background-color: var(--color-primary-hover);
+        border-color: var(--color-primary-hover);
+    }
+
+    /* Secondary buttons */
+    [role="button"].secondary,
+    button.secondary {
+        background-color: var(--color-neutral);
+        border-color: var(--color-neutral);
+        color: var(--color-btn-fg);
+    }
+
+    /* Apply border color to form elements */
+    input, select, textarea {
+        border: 1px solid var(--color-border);
+        border-radius: var(--radius);
+        background-color: var(--color-bg);
+        color: var(--color-fg);
+    }
+
+    [role="button"].outline,
+    button.outline {
+        background-color: var(--color-bg);
+        border-color: var(--color-border);
+        color: var(--color-primary);
+    }
+
+    /* Apply container width */
+    #calendar-container {
+        width: var(--layout-container-width);
+        margin: 0 auto;
+    }
+
+    /* Apply border color to tables */
+    table, th, td {
+        border-color: var(--color-border);
+    }
+
+    /* Calendar days */
+    .calendar-cell {
+        border: 1px solid var(--color-border);
+        background-color: var(--color-surface);
+    }
+
+    /* Links */
+    a:not([role="button"]) {
+        color: var(--color-primary);
+    }
+
+    a:not([role="button"]):hover {
+        color: var(--color-primary-hover);
+    }
+
+    /* Calendar app specific styles */
+    .logo-title-container {
+        display: flex;
+        align-items: center;
+        text-decoration: none;
+    }
+
+    .custom-logo {
+        max-height: 50px;
+        margin-right: 10px;
+    }
+    .calendar-title {
+        margin: 0;
+        color: var(--color-primary);
+    }
+
+    .logo-title-container a {
+        text-decoration: none;
+    }
+
+    .button-container {
+        display: flex;
+        justify-content: space-between;
+        margin-top: var(--layout-spacing);
+    }
+
+    .error-message {
+        background-color: rgba(220, 53, 69, 0.1);
+        color: var(--color-danger);
+        padding: var(--layout-spacing);
+        margin-bottom: var(--layout-spacing);
+        border-radius: var(--radius);
+        text-align: center;
+    }
+"""
 
-# Initialize with default styles
-# Will be updated in set_environment
-styles = Style("")
+styles = Style(_COMPONENT_CSS)
 
 
 app, rt = fast_app(
@@ -218,12 +194,9 @@ class Event:
 
 def set_environment(config):
     """Set environment variables for the messenger app"""
-    global app, styles, logo_title_container
+    global app, logo_title_container
     app.config = config
-    
-    # Update the styles from config
-    styles = Style(generate_styles_from_config(config))
-    
+
     db = database(config.calendar.database_path)
     # create new events
     global events
@@ -239,12 +212,24 @@ def set_environment(config):
 
 
 def calendar_theme():
-    """The active theme, mapped onto this app's `appearance` CSS variables.
+    """The active theme's tokens plus this app's layout variables.
 
-    Empty on the default theme. Rendered per-request (and after `styles`, which
-    it has to override) so live `reconfigure` theme swaps take effect.
+    Resolved per-request so live `reconfigure` theme and layout swaps take
+    effect. The `--layout-*` block is emitted here rather than in
+    `_COMPONENT_CSS` because it is the only part of the stylesheet that
+    depends on config.
     """
-    return legacy_theme_style(app.config, "calendar")
+    layout = app.config.calendar
+    return Style(
+        render_theme_css(resolve_theme(app.config, "calendar"))
+        + f"""
+:root {{
+  --layout-container-width: {layout.container_width};
+  --layout-spacing: {layout.spacing};
+  --layout-button-padding: {layout.button_padding};
+}}
+"""
+    )
 
 
 def update_db_from_hydra():
@@ -567,18 +552,18 @@ def show_main_layout(year, month, view="calendar", event_id=None):
     # Add calendar-specific styles that don't come from config
     calendar_specific_styles = Style(
         """
-        .calendar-nav { display: flex; justify-content: space-between; align-items: center; margin-bottom: var(--spacing); }
+        .calendar-nav { display: flex; justify-content: space-between; align-items: center; margin-bottom: var(--layout-spacing); }
         .calendar-nav h2 { margin: 0; }
-        .view-toggle { display: flex; justify-content: center; gap: 10px; margin-bottom: var(--spacing); }
+        .view-toggle { display: flex; justify-content: center; gap: 10px; margin-bottom: var(--layout-spacing); }
         .calendar-table { width: 100%; table-layout: fixed; }
         .calendar-table th { text-align: center; font-weight: bold; }
         .calendar-cell { height: 100px; vertical-align: top; padding: 5px !important; }
         .day-number { font-weight: bold; margin-bottom: 5px; }
         .event-link { display: block; margin-bottom: 2px; font-size: 0.8em; }
         .agenda-list { list-style-type: none; padding: 0; }
-        .agenda-list li { margin-bottom: var(--spacing); }
-        .footer-container { margin-top: var(--spacing); }
-        #about-dialog-content { padding: var(--spacing); }
+        .agenda-list li { margin-bottom: var(--layout-spacing); }
+        .footer-container { margin-top: var(--layout-spacing); }
+        #about-dialog-content { padding: var(--layout-spacing); }
         """
     )
     
diff --git a/src/open_apps/apps/codeeditor_app/main.py b/src/open_apps/apps/codeeditor_app/main.py
index e458a226..096ce6ad 100644
--- a/src/open_apps/apps/codeeditor_app/main.py
+++ b/src/open_apps/apps/codeeditor_app/main.py
@@ -12,7 +12,58 @@
 from starlette.responses import Response
 from src.open_apps.apps.start_page.helper import create_logo_header
 from src.open_apps.frontend import local_hdrs
-from src.open_apps.theme import legacy_theme_style
+from src.open_apps.theme import theme_asset, theme_style
+
+# Static, theme-agnostic component styles. Colors and fonts are design tokens
+# from the shared theme (`config/apps/theme/`), emitted per-request by
+# `codeeditor_theme()`. `!important` throughout because daisyUI ships utility
+# classes on these same elements.
+_COMPONENT_STYLES = Style(
+    """
+    .main-content {
+        background-color: var(--color-bg);
+    }
+    .styled-content {
+        font-size: var(--font-size-sm);
+        font-family: var(--font-family);
+        color: var(--color-fg);
+    }
+    /* The code pane keeps a monospace face regardless of the theme's body
+       font -- column alignment is load-bearing in an editor. */
+    textarea, textarea.styled-content {
+        background-color: var(--color-surface);
+        color: var(--color-fg);
+        font-family: var(--font-mono);
+    }
+    .btn-primary {
+        background-color: var(--color-primary) !important;
+        border-color: var(--color-primary) !important;
+        color: var(--color-on-primary) !important;
+        font-family: var(--font-family) !important;
+    }
+    .btn-secondary {
+        background-color: var(--color-neutral) !important;
+        border-color: var(--color-neutral) !important;
+        color: var(--color-btn-fg) !important;
+        font-family: var(--font-family) !important;
+    }
+    .btn-error {
+        background-color: var(--color-danger) !important;
+        border-color: var(--color-danger) !important;
+        color: var(--color-btn-fg) !important;
+        font-family: var(--font-family) !important;
+    }
+"""
+)
+
+# Set by the in-page theme dropdown; None means "follow the shared theme".
+_editor_theme_override = None
+
+
+def _as_dict(node):
+    """Coerce an OmegaConf node (or None) to a plain dict."""
+    return {k: v for k, v in node.items()} if node is not None else {}
+
 
 # Global variables
 _base_hdrs_no_highlight = (
@@ -100,7 +151,13 @@ def set_environment(config):
         Link(rel="stylesheet", href="https://cdn.jsdelivr.net/npm/daisyui@4.11.1/dist/full.min.css"),
         Link(rel="stylesheet", href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.2/codemirror.min.css"),
     )
-    for theme_name in list_of_themes:
+    # Every stylesheet the page could ask for, loaded up front: the dropdown
+    # switches themes client-side, and a shared-theme swap can select one by
+    # tone. Include the tone-mapped names even if `list_of_themes` was trimmed,
+    # otherwise `apps/theme=dark` asks CodeMirror for a stylesheet that is not
+    # on the page and the editor silently renders unstyled.
+    tone_themes = list(_as_dict(getattr(config.code_editor, "editor_theme_by_tone", None)).values())
+    for theme_name in dict.fromkeys([*list_of_themes, *tone_themes, config.code_editor.editor_theme]):
         _base_hdrs_with_highlight += (
             Link(rel="stylesheet", href=f"https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.2/theme/{theme_name}.min.css"),
         )
@@ -119,62 +176,9 @@ def set_environment(config):
     """),)
     _base_hdrs = _base_hdrs_with_highlight if config.code_editor.highlight else _base_hdrs_no_highlight
     
-    primary_color = getattr(config.code_editor, 'primary_button_color', '#4A90E2')
-    secondary_color = getattr(config.code_editor, 'secondary_button_color', '#50E3C2')
-    danger_color = getattr(config.code_editor, 'danger_button_color', '#D0021B')
-    # grey 800 background as default
-    textarea_background_color = getattr(config.code_editor, 'textarea_background_color', '#2d2d2d')
-    # grey 900 background as default
-    main_background_color = getattr(config.code_editor, 'main_background_color', '#1a202c')
-
-    env_styles = Style(
-        f"""
-        :root {{
-            --custom-font-size: {config.code_editor.font_size}px;
-            --custom-font-family: {config.code_editor.font};
-            --custom-font-color: {config.code_editor.fontcolor};
-            --main-bg-color: {main_background_color};
-        }}
-        .main-content {{
-            background-color: var(--main-bg-color);
-        }}
-        .styled-content {{
-            font-size: var(--custom-font-size);
-            font-family: var(--custom-font-family);
-            color: var(--custom-font-color);
-        }}
-        textarea.styled-content {{
-            font-family: var(--custom-font-family), monospace;
-            color: var(--custom-font-color);
-        }}
-        textarea {{
-            background-color: {textarea_background_color};
-            color: var(--custom-font-color);
-            font-family: var(--custom-font-family);
-        }}
-        .btn-primary {{
-            background-color: {primary_color} !important;
-            border-color: {primary_color} !important;
-            color: var(--custom-font-color) !important;
-            font-family: var(--custom-font-family); !important;
-        }}
-        .btn-secondary {{
-            background-color: {secondary_color} !important;
-            border-color: {secondary_color} !important;
-            color: var(--custom-font-color) !important;
-            font-family: var(--custom-font-family); !important;
-        }}
-        .btn-error {{
-            background-color: {danger_color} !important;
-            border-color: {danger_color} !important;
-            color: var(--custom-font-color) !important;
-            font-family: var(--custom-font-family); !important;
-        }}
-    """
-    )
     app.config = config
     # Update app headers by extending existing ones
-    app.hdrs = (*_base_hdrs, env_styles)
+    app.hdrs = (*_base_hdrs, _COMPONENT_STYLES)
 
     if config.code_editor.sort_feature:
         list_of_modes = sorted(list_of_modes)
@@ -187,13 +191,32 @@ def set_environment(config):
     )
 
 def codeeditor_theme():
-    """The active theme, mapped onto this app's `appearance` CSS variables.
+    """The active theme's `:root` token block.
+
+    Rendered into the page body (not `app.hdrs`) so live `reconfigure` theme
+    swaps take effect without rebuilding the headers.
+    """
+    return theme_style(app.config, "code_editor")
 
-    Empty on the default theme. Rendered into the page body (not `app.hdrs`)
-    so it lands after `env_styles`, which it has to override, and so live
-    `reconfigure` theme swaps take effect.
+
+def current_editor_theme():
+    """CodeMirror's syntax-highlighting stylesheet name.
+
+    Not the shared design-token theme -- CodeMirror ships a whole stylesheet
+    per theme, which no CSS variable can substitute for. The shared theme
+    therefore picks one indirectly via its `tone` asset, so `apps/theme=dark`
+    darkens the editor pane and not just the chrome around it.
+
+    An in-page selection from the dropdown wins over the tone mapping: the
+    user (or agent) just asked for that theme explicitly.
     """
-    return legacy_theme_style(app.config, "code_editor")
+    if _editor_theme_override is not None:
+        return _editor_theme_override
+    cfg = app.config.code_editor
+    tone = theme_asset(app.config, "code_editor", "tone", "light")
+    return _as_dict(getattr(cfg, "editor_theme_by_tone", None)).get(
+        tone, cfg.editor_theme
+    )
 
 
 def return_to_index():
@@ -482,7 +505,7 @@ def index():
                             });
                             """
                         )(
-                            *[Option(theme, value=theme, selected=(theme == app.config.code_editor.theme)) for theme in list_of_themes]
+                            *[Option(theme, value=theme, selected=(theme == current_editor_theme())) for theme in list_of_themes]
                         ),
                     ),
                 ),
@@ -497,7 +520,7 @@ def index():
                 Script(f"""
                     var editor = {'CodeMirror.fromTextArea' if app.config.code_editor.highlight else ''} (document.getElementById('editor'), {{
                         mode: '{app.config.code_editor.mode}',
-                        theme: '{app.config.code_editor.theme}',
+                        theme: '{current_editor_theme()}',
                         lineNumbers: true,
                         indentUnit: 4,
                         tabSize: 4,
@@ -588,7 +611,7 @@ def get_folder(folder: str):
                                 });
                             """
                         )(
-                            *[Option(theme, value=theme, selected=(theme == app.config.code_editor.theme)) for theme in list_of_themes]
+                            *[Option(theme, value=theme, selected=(theme == current_editor_theme())) for theme in list_of_themes]
                         ),
                     ),
                 ),
@@ -603,7 +626,7 @@ def get_folder(folder: str):
                 Script(f"""
                     var editor = {'CodeMirror.fromTextArea' if app.config.code_editor.highlight else ''} (document.getElementById('editor'), {{
                         mode: '{app.config.code_editor.mode}',
-                        theme: '{app.config.code_editor.theme}',
+                        theme: '{current_editor_theme()}',
                         lineNumbers: true,
                         readOnly: true
                     }});
@@ -852,7 +875,7 @@ def get_file(file: str):
                                 });
                             """
                         )(
-                            *[Option(theme, value=theme, selected=(theme == app.config.code_editor.theme)) for theme in list_of_themes]
+                            *[Option(theme, value=theme, selected=(theme == current_editor_theme())) for theme in list_of_themes]
                         ),
                     ),
                 ),
@@ -880,7 +903,7 @@ def get_file(file: str):
                 Script(f"""
                     var editor = {'CodeMirror.fromTextArea' if app.config.code_editor.highlight else ''} (document.getElementById('editor'), {{
                         mode: '{app.config.code_editor.mode}',
-                        theme: '{app.config.code_editor.theme}',
+                        theme: '{current_editor_theme()}',
                         lineNumbers: true,
                         indentUnit: 4,
                         tabSize: 4,
@@ -1042,7 +1065,10 @@ async def update_config(request):
         if data["type"] == "mode":
             app.config.code_editor.mode = data["value"]
         elif data["type"] == "theme":
-            app.config.code_editor.theme = data["value"]
+            # CodeMirror's stylesheet, not the shared design-token theme.
+            # Recorded as an override so it survives a later theme swap.
+            global _editor_theme_override
+            _editor_theme_override = data["value"]
         return {"success": True}
     except Exception as e:
         return {"success": False, "error": str(e)}
diff --git a/src/open_apps/apps/map_app/main.py b/src/open_apps/apps/map_app/main.py
index ae231e1f..ca08708c 100644
--- a/src/open_apps/apps/map_app/main.py
+++ b/src/open_apps/apps/map_app/main.py
@@ -14,7 +14,7 @@
 from fasthtml.common import *
 import requests
 import json
-from src.open_apps.theme import legacy_theme_css
+from src.open_apps.theme import render_theme_css, resolve_theme, theme_asset
 from datetime import datetime, timezone
 import subprocess
 import time
@@ -99,6 +99,23 @@ async def startup_event():
 async def shutdown_event():
     stop_otp_server()
 
+def current_tile_layer() -> str:
+    """Leaflet basemap for the active theme.
+
+    Tiles are raster images served from a CDN, so no design token can recolor
+    them -- a dark theme would otherwise render a dark sidebar around a bright
+    map. The theme instead names a `tone`, and `layer_by_tone` maps that onto
+    one of the layers defined in templates/map.html; anything unmapped keeps
+    the configured `default_layer`.
+    """
+    cfg = app.config.maps
+    tone = theme_asset(app.config, "maps", "tone", "light")
+    by_tone = getattr(cfg, "layer_by_tone", None)
+    if by_tone is not None and tone in by_tone:
+        return by_tone[tone]
+    return cfg.default_layer
+
+
 @app.get("/maps", response_class=HTMLResponse)
 async def map_page(request: Request):
     return templates.TemplateResponse(
@@ -106,26 +123,16 @@ async def map_page(request: Request):
         {
             "request": request,
             "enable_layer_control": app.config.maps.enable_layer_control,
-            "default_layer": app.config.maps.default_layer,
+            "default_layer": current_tile_layer(),
             "popup_display_rule": app.config.maps.popup_display_rule,
             "title": app.config.maps.title,
             "init_location": app.config.maps.init_location,
             "zoom": app.config.maps.zoom,
             "granularity": app.config.maps.granularity,
-            "font_family": app.config.maps.font_family,
-            "base_font_size": app.config.maps.base_font_size,
-            "search_button_color": app.config.maps.search_button_color,
-            "delete_button_color": app.config.maps.delete_button_color,
-            "return_button_color": app.config.maps.return_button_color,
-            "calculate_button_color": app.config.maps.calculate_button_color,
-            "delete_button_hover_color": getattr(app.config.maps, "delete_button_hover_color", "#ffecec"),
-            "search_button_hover_color": getattr(app.config.maps, "search_button_hover_color", "#2980b9"),
-            "calculate_button_hover_color": getattr(app.config.maps, "calculate_button_hover_color", "#2980b9"),
-            "sidebar_background_color": getattr(app.config.maps, "sidebar_background_color", "#f8f9fa"),
             "allow_planning": app.config.maps.allow_planning,
-            # Resolved per-request so live `reconfigure` theme swaps take
-            # effect; empty string on the default theme.
-            "theme_css": legacy_theme_css(app.config, "maps"),
+            # Every color and font in the template is a var() into this block.
+            # Resolved per-request so live `reconfigure` theme swaps take effect.
+            "theme_css": render_theme_css(resolve_theme(app.config, "maps")),
         },
     )
 
diff --git a/src/open_apps/apps/map_app/templates/map.html b/src/open_apps/apps/map_app/templates/map.html
index 2bb54141..a9ca75ac 100644
--- a/src/open_apps/apps/map_app/templates/map.html
+++ b/src/open_apps/apps/map_app/templates/map.html
@@ -11,8 +11,10 @@
     <style>
         body,
         html {
-            font-family: "{{ font_family }}";
-            font-size: "{{ base_font_size }}";
+            font-family: var(--font-family);
+            font-size: var(--font-size-base);
+            color: var(--color-fg);
+            background-color: var(--color-bg);
             margin: 0;
             padding: 0;
             height: 100vh;
@@ -37,20 +39,20 @@
         #sidebar {
             flex: 0.2;
             padding: 20px;
-            background: {{ sidebar_background_color }};
+            background: var(--color-surface);
             box-shadow: -2px 0 5px rgba(0, 0, 0, 0.1);
             overflow-y: auto;
         }
 
         #sidebar h2 {
-            color: #2c3e50;
+            color: var(--color-fg);
             margin-bottom: 20px;
-            border-bottom: 2px solid #3498db;
+            border-bottom: 2px solid var(--color-primary);
             padding-bottom: 10px;
         }
 
         #sidebar h3 {
-            color: #34495e;
+            color: var(--color-fg);
             margin: 20px 0 10px 0;
         }
 
@@ -58,9 +60,9 @@
             cursor: pointer;
             padding: 10px;
             margin: 5px 0;
-            background-color: white;
+            background-color: var(--color-bg);
             border-radius: 5px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             transition: all 0.2s;
             display: flex;
             justify-content: space-between;
@@ -68,12 +70,12 @@
         }
 
         .popup-list-item:hover {
-            background-color: #f5f6fa;
+            background-color: var(--color-surface);
             transform: translateX(5px);
         }
 
         .delete-btn {
-            color: {{ delete_button_color }};
+            color: var(--color-danger);
             cursor: pointer;
             font-size: 18px;
             padding: 0 5px;
@@ -83,7 +85,7 @@
         }
 
         .delete-btn:hover {
-            background-color: {{ delete_button_hover_color }}
+            background-color: var(--color-surface)
         }
 
         .search-container {
@@ -95,15 +97,15 @@
         #searchInput {
             flex: 1;
             padding: 8px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             border-radius: 5px;
             font-size: 14px;
         }
 
         #searchBtn {
             padding: 8px 15px;
-            background-color: {{ search_button_color }};
-            color: white;
+            background-color: var(--color-primary);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -111,7 +113,7 @@
         }
 
         #searchBtn:hover {
-            background-color: {{ search_button_hover_color }}
+            background-color: var(--color-primary-hover)
         }
 
         #searchResults {
@@ -122,22 +124,22 @@
             cursor: pointer;
             padding: 10px;
             margin: 5px 0;
-            background-color: white;
+            background-color: var(--color-bg);
             border-radius: 5px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             transition: all 0.2s;
         }
 
         .search-result-item:hover {
-            background-color: #f5f6fa;
+            background-color: var(--color-surface);
             transform: translateX(5px);
         }
 
         .info-box {
-            background: white;
+            background: var(--color-bg);
             padding: 10px;
             border-radius: 5px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             margin: 10px 0;
             font-size: 14px;
         }
@@ -158,15 +160,15 @@
         .location-input-container input {
             flex: 1;
             padding: 8px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             border-radius: 5px;
             font-size: 14px;
         }
 
         .location-input-container .search-btn {
             padding: 8px 15px;
-            background-color: {{ search_button_color }};
-            color: white;
+            background-color: var(--color-primary);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -174,7 +176,7 @@
         }
 
         .location-input-container .search-btn:hover {
-            background-color: {{ search_button_hover_color }}
+            background-color: var(--color-primary-hover)
         }
 
         .search-results-mini {
@@ -185,16 +187,16 @@
             max-height: 100px;
             overflow-y: auto;
             margin: 5px 0;
-            background: white;
-            border: 1px solid #e0e0e0;
+            background: var(--color-bg);
+            border: 1px solid var(--color-border);
             z-index: 1000;
         }
 
         #calculateRouteBtn {
             width: 100%;
             padding: 8px;
-            background-color: {{ calculate_button_color }};
-            color: white;
+            background-color: var(--color-primary);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -202,13 +204,13 @@
         }
 
         #calculateRouteBtn:hover {
-            background-color: {{ calculate_button_hover_color }};
+            background-color: var(--color-primary-hover);
         } */
 
         .search-btn {
             padding: 8px 15px;
-            background-color: {{ search_button_color }}
-            color: white;
+            background-color: var(--color-primary);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -217,14 +219,14 @@
         }
 
         .search-btn:hover {
-            background-color: {{ search_button_hover_color }};
+            background-color: var(--color-primary-hover);
         }
 
         #returnButton {
             width: 100%;
             padding: 10px;
-            background-color: {{ return_button_color }};
-            color: white;
+            background-color: var(--color-neutral);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -233,7 +235,7 @@
         }
 
         #returnButton:hover {
-            background-color: #7f8c8d;
+            background-color: var(--color-primary-hover);
         }
 
         .custom-select-container {
@@ -244,9 +246,9 @@
 
         .custom-select-header {
             padding: 8px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             border-radius: 5px;
-            background: white;
+            background: var(--color-bg);
             cursor: pointer;
             display: flex;
             justify-content: space-between;
@@ -258,8 +260,8 @@
             top: 100%;
             left: 0;
             right: 0;
-            background: white;
-            border: 1px solid #e0e0e0;
+            background: var(--color-bg);
+            border: 1px solid var(--color-border);
             border-radius: 5px;
             margin-top: 5px;
             max-height: 200px;
@@ -277,7 +279,7 @@
         }
 
         .custom-select-option:hover {
-            background-color: #f5f6fa;
+            background-color: var(--color-surface);
         }
 
         .custom-select-option i {
@@ -285,11 +287,11 @@
         }
 
         .custom-select-option.selected {
-            background-color: #e3f2fd;
+            background-color: var(--color-surface);
         }
     </style>
-    <!-- Shared design tokens (open_apps.theme). Empty unless a theme is
-         selected; must come last so it overrides the appearance config above. -->
+    <!-- Shared design tokens (open_apps.theme). Every color and font above
+         is a var() into this block. -->
     <style>{{ theme_css|safe }}</style>
 </head>
 
@@ -492,13 +494,22 @@ <h3>Saved Locations</h3>
                 maxZoom: 19,
                 attribution: '© OpenStreetMap contributors, © CartoDB'
             }),
+            // Greyscale basemap -- what the `mono` theme selects, so the map
+            // carries no hue either.
+            'CartoDB Positron': L.tileLayer('https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png', {
+                maxZoom: 19,
+                attribution: '© OpenStreetMap contributors, © CartoDB'
+            }),
 
             'OpenStreetMap Transport': L.tileLayer('https://tile.memomaps.de/tilegen/{z}/{x}/{y}.png', {
                 maxZoom: 18,
                 attribution: '© OpenStreetMap contributors, © MeMoMaps'
             }),
         };
-        layers['{{ default_layer }}'].addTo(map);
+        // Fall back rather than throw: an unknown name here used to raise a
+        // TypeError that aborted the rest of this script, leaving a blank map
+        // with no landmarks and no sidebar wiring.
+        (layers['{{ default_layer }}'] || layers['OpenStreetMap']).addTo(map);
 
         {% if enable_layer_control %}
         // Add layer control only if enabled
@@ -1208,7 +1219,7 @@ <h3>Saved Locations</h3>
                                 let content = `
                                     <div style="display: flex; justify-content: space-between; align-items: center; width: 100%;">
                                         <div>Option ${index + 1}: ${icons}</div>
-                                        <div style="color: #666; font-size: 0.9em;">
+                                        <div style="color: var(--color-muted); font-size: 0.9em;">
                                             ${formatTime(startTime)} → ${formatTime(endTime)}
                                         </div>
                                     </div>
@@ -1278,7 +1289,7 @@ <h3>Saved Locations</h3>
         {% endif %}
 
     </script>
-    <div id="markerCustomizationModal" style="display: none; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); background: white; padding: 20px; border-radius: 5px; box-shadow: 0 0 10px rgba(0,0,0,0.3); z-index: 1000;">
+    <div id="markerCustomizationModal" style="display: none; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); background: var(--color-bg); padding: 20px; border-radius: 5px; box-shadow: 0 0 10px rgba(0,0,0,0.3); z-index: 1000;">
         <h3>Customize Marker</h3>
         <div style="margin-bottom: 15px;">
             <label for="markerIcon">Icon:</label>
@@ -1345,7 +1356,7 @@ <h3>Customize Marker</h3>
         </div>
         <div style="text-align: right;">
             <button onclick="cancelMarkerCustomization()" style="margin-right: 10px;">Cancel</button>
-            <button onclick="confirmMarkerCustomization()" style="background-color: #3498db; color: white; border: none; padding: 5px 15px; border-radius: 3px;">Confirm</button>
+            <button onclick="confirmMarkerCustomization()" style="background-color: var(--color-primary); color: var(--color-on-primary); border: none; padding: 5px 15px; border-radius: 3px;">Confirm</button>
         </div>
     </div>
 </body>
diff --git a/src/open_apps/apps/messenger_app/main.py b/src/open_apps/apps/messenger_app/main.py
index cd7b6c15..b5df6b18 100644
--- a/src/open_apps/apps/messenger_app/main.py
+++ b/src/open_apps/apps/messenger_app/main.py
@@ -12,7 +12,7 @@
 import json
 from src.open_apps.apps.start_page.helper import create_logo_header
 from open_apps.frontend import local_hdrs
-from open_apps.theme import legacy_theme_style
+from open_apps.theme import theme_style
 
 
 @dataclass
@@ -273,6 +273,78 @@ class Messages:
 )
 app = FastHTML(hdrs=_base_hdrs, cls="p-4 max-w-lg mx-auto", default_hdrs=False)
 
+# Static, theme-agnostic component styles. Colors and fonts are design tokens
+# from the shared theme (`config/apps/theme/`), emitted per-request by
+# `messenger_theme()`.
+#
+# The chat surface maps onto generic tokens rather than bubble-specific ones:
+# the outgoing bubble is the primary action color, the incoming bubble is the
+# surface color, and the transcript sits on the page background. Keeping the
+# vocabulary generic is what lets a theme file stay app-agnostic -- no theme
+# has to know this app has bubbles.
+#
+# `!important` throughout: daisyUI ships utility classes on these same
+# elements and would otherwise win.
+_COMPONENT_STYLES = Style(
+    """
+    body {
+        background-color: var(--color-bg);
+    }
+    /* Global text styling */
+    h1, h2, h3, p, div {
+        font-family: var(--font-family) !important;
+        color: var(--color-fg) !important;
+    }
+
+    /* Message list specific styling */
+    .text-2xl {
+        font-size: calc(var(--font-size-base) * 1.5) !important;
+    }
+
+    .text-sm {
+        font-size: var(--font-size-sm) !important;
+    }
+
+    /* Chat specific styling */
+    .chat .chat-header {
+        font-family: var(--font-family) !important;
+        color: var(--color-muted) !important;
+        margin-bottom: calc(var(--font-size-sm) * 0.5);
+    }
+
+    .chat .chat-bubble {
+        font-family: var(--font-family) !important;
+        font-size: var(--font-size-sm) !important;
+        color: var(--color-fg) !important;
+        padding: calc(var(--font-size-sm) * 0.75) var(--font-size-sm);
+        min-height: calc(var(--font-size-sm) * 2);
+        display: flex;
+        align-items: center;
+    }
+    .input {
+        font-family: var(--font-family) !important;
+        font-size: var(--font-size-sm) !important;
+        color: var(--color-fg) !important;
+        background-color: var(--color-bg) !important;
+    }
+
+    /* Chat bubbles */
+    .chat-bubble-primary {
+        background-color: var(--color-primary) !important;
+        color: var(--color-on-primary) !important;
+    }
+
+    .chat-bubble-secondary {
+        background-color: var(--color-surface) !important;
+    }
+
+    /* daisyUI paints these from its own palette, which no token can reach. */
+    .bg-base-100, .bg-base-200 {
+        background-color: var(--color-surface) !important;
+    }
+"""
+)
+
 
 def set_environment(config):
     """Set environment variables for the messenger app"""
@@ -292,77 +364,9 @@ def set_environment(config):
     #         current_file_path=__file__
     #     )
     #     return
-    # Create styles with environment variables
-    env_styles = Style(
-        f"""
-        :root {{
-            --custom-font-size: {config.messenger.font_size}px;
-            --custom-font-family: {config.messenger.font};
-            --custom-font-color: {config.messenger.fontcolor};
-            --custom-background-color: {config.messenger.background_color};
-            --chat-font-size: {config.messenger.chat_font_size}px;
-            --chat-font-family: {config.messenger.chat_font};
-            --chat-font-color: {config.messenger.chat_fontcolor};
-            --chat-header-font-color: {config.messenger.chat_header_fontcolor};
-            --chat-primary-bubble-color: {config.messenger.chat_primary_bubble_color};
-            --chat-secondary-bubble-color: {config.messenger.chat_secondary_bubble_color};
-            --chat-display-background-color: {config.messenger.chat_display_background_color};
-        }}
-        body {{
-            background-color: var(--custom-background-color);
-        }}
-        /* Global text styling */
-        h1, h2, h3, p, div {{
-            font-family: var(--custom-font-family) !important;
-            color: var(--custom-font-color) !important;
-        }}
-
-        /* Message list specific styling */
-        .text-2xl {{
-            font-size: calc(var(--custom-font-size) * 1.5) !important;
-        }}
-
-        .text-sm {{
-            font-size: calc(var(--custom-font-size) * 0.875) !important;
-        }}
-        
-        /* Chat specific styling */
-        .chat .chat-header {{
-            font-family: var(--chat-font-family) !important;
-            color: var(--chat-header-font-color) !important;
-            margin-bottom: calc(var(--chat-font-size) * 0.5);
-        }}
-        
-        .chat .chat-bubble {{
-            font-family: var(--chat-font-family) !important;
-            font-size: var(--chat-font-size) !important;
-            color: var(--chat-font-color) !important;
-            padding: calc(var(--chat-font-size) * 0.75) calc(var(--chat-font-size) * 1);
-            min-height: calc(var(--chat-font-size) * 2);
-            display: flex;
-            align-items: center;
-        }}
-        .input {{
-            font-family: var(--chat-font-family) !important;
-            font-size: var(--chat-font-size) !important;
-            color: var(--chat-font-color) !important;
-        }}
-
-        # Add these new styles for chat bubbles
-        .chat-bubble-primary {{
-            background-color: var(--chat-primary-bubble-color) !important;
-        }}
-        
-        .chat-bubble-secondary {{
-            background-color: var(--chat-secondary-bubble-color) !important;
-        }}
-    """
-    )
-
-    # Update app headers by extending existing ones
     # Note: in future implementations, we might need to preserve
     # the order of the style files, scripts and links to prevent conflicts
-    app.hdrs = (*_base_hdrs, env_styles)
+    app.hdrs = (*_base_hdrs, _COMPONENT_STYLES)
     app.config = config
     # create database
     db = database(app.config.messenger.database_path)
@@ -379,13 +383,12 @@ def set_environment(config):
     )
 
 def messenger_theme():
-    """The active theme, mapped onto this app's `appearance` CSS variables.
+    """The active theme's `:root` token block.
 
-    Empty on the default theme. Rendered into the page body (not `app.hdrs`)
-    so it lands after `env_styles`, which it has to override, and so live
-    `reconfigure` theme swaps take effect.
+    Rendered into the page body (not `app.hdrs`) so live `reconfigure` theme
+    swaps take effect without rebuilding the headers.
     """
-    return legacy_theme_style(app.config, "messenger")
+    return theme_style(app.config, "messenger")
 
 
 def populate_database(config, db):
@@ -418,7 +421,7 @@ def add_new_message_to_history(user, message, sender, timestamp):
 # Chat message component (renders a chat bubble)
 def ChatMessage(message, sender, timestamp=None):
     if sender == "you":
-        bubble_class = "chat-bubble-primary custom-primary-bubble bg-[var(--chat-primary-bubble-color)] text-[var(--chat-font-color)]"
+        bubble_class = "chat-bubble-primary custom-primary-bubble bg-[var(--color-primary)] text-[var(--color-on-primary)]"
         chat_class = "chat-end"
     else:
         bubble_class = "chat-bubble-secondary"
@@ -599,7 +602,7 @@ def index(user_id: str):
         ),
         Style("""
             .chat-bg {
-                background-color: var(--chat-display-background-color);
+                background-color: var(--color-bg);
             }
             .chat-bubble {
                 border-radius: 12px;
@@ -628,7 +631,7 @@ def index(user_id: str):
                 transition: background-color 0.2s ease;
             }
             .search-result-item:hover {
-                background-color: #e5e7eb;
+                background-color: var(--color-surface);
             }
         """),
         # Add debugging script
diff --git a/src/open_apps/apps/onlineshop_app/main.py b/src/open_apps/apps/onlineshop_app/main.py
index d7f7255c..036ca951 100644
--- a/src/open_apps/apps/onlineshop_app/main.py
+++ b/src/open_apps/apps/onlineshop_app/main.py
@@ -50,7 +50,7 @@ def set_environment(config):
     app.config = config
     if not os.path.exists(config.onlineshop.database_path):
         os.makedirs(config.onlineshop.database_path)
-    global_state.update_config(config.onlineshop)
+    global_state.update_config(config.onlineshop, apps_config=config)
     update_db_from_hydra(global_state)
 
 def generate_search_results(products: List[Dict], keywords: str, page: int, total: int) -> str:
diff --git a/src/open_apps/apps/onlineshop_app/models/global_state.py b/src/open_apps/apps/onlineshop_app/models/global_state.py
index 0b317814..afc14265 100644
--- a/src/open_apps/apps/onlineshop_app/models/global_state.py
+++ b/src/open_apps/apps/onlineshop_app/models/global_state.py
@@ -21,6 +21,9 @@ def __init__(self):
         self.SHOW_ATTRS_TAB = False
         self.cart = Cart()
         self.config = None
+        # The whole `config.apps` node, not just this app's slice: resolving
+        # the shared theme needs the sibling `apps.theme` group.
+        self.apps_config = None
         self.orders = []
 
     def initialize(self):
@@ -31,8 +34,9 @@ def initialize(self):
             num_products=DEBUG_PROD_SIZE
         )
         self.search_engine = init_search_engine(num_products=DEBUG_PROD_SIZE)
-    def update_config(self, config):
+    def update_config(self, config, apps_config=None):
         self.config = config
+        self.apps_config = apps_config
     def load_state_from_config(self):
         cart, orders = self.config.cart, self.config.orders
         if isinstance(cart, ListConfig) or isinstance(cart, DictConfig):
diff --git a/src/open_apps/apps/onlineshop_app/templates/html_generator.py b/src/open_apps/apps/onlineshop_app/templates/html_generator.py
index cbc08471..e38f29bd 100644
--- a/src/open_apps/apps/onlineshop_app/templates/html_generator.py
+++ b/src/open_apps/apps/onlineshop_app/templates/html_generator.py
@@ -4,18 +4,16 @@
 This source code is licensed under the license found in the
 LICENSE file in the root directory of this source tree.
 """
+from open_apps.theme import render_theme_css, resolve_theme
+
 from ..models.global_state import global_state
 
 # HTML Templates
 def generate_base_html(content: str) -> str:
     cart_count = global_state.cart.get_total_quantity() if hasattr(global_state, 'cart') else 0
-    bg_color = global_state.config.background_color
-    font_family = global_state.config.font_family
-    base_font_size = global_state.config.base_font_size
-    font_color = global_state.config.font_color
-    button_background_color = getattr(global_state.config, 'button_background_color', '#0d6efd')
-    button_font_color = getattr(global_state.config, 'button_font_color', '#FFFFFF')
-    highlight_font_color = getattr(global_state.config, 'highlight_font_color', '#0d6efd')
+    # Every color and font below is a var() into this block. Resolved
+    # per-request so live `reconfigure` theme swaps take effect.
+    theme_css = render_theme_css(resolve_theme(global_state.apps_config, "onlineshop"))
     return f"""
     <!DOCTYPE html>
     <html>
@@ -24,17 +22,18 @@ def generate_base_html(content: str) -> str:
             <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
             <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" rel="stylesheet">
             <style>
+                {theme_css}
                 body {{
-                    font-family: "{font_family}";
-                    font-size: {base_font_size};
-                    background-color: {bg_color};
-                    color: {font_color};
+                    font-family: var(--font-family);
+                    font-size: var(--font-size-base);
+                    background-color: var(--color-bg);
+                    color: var(--color-fg);
                 }}
                 button, input, textarea, select {{
                     font-family: inherit;
                 }}
                 h1, h2, h3, h4, h5, h6 {{
-                    font-family: inherit;
+                    font-family: var(--font-heading);
                 }}
                 .result-img {{
                     max-width: 100%;
@@ -51,49 +50,55 @@ def generate_base_html(content: str) -> str:
                     margin: 2px;
                 }}
                 .option-btn.active {{
-                    background-color: #0d6efd;
-                    color: white;
-                }}
-                .review-item {{
-                    border-bottom: 1px solid #ddd;
-                    padding: 10px 0;
+                    background-color: var(--color-primary);
+                    color: var(--color-on-primary);
                 }}
                 .hover-shadow:hover {{
                     transform: translateY(-3px);
                     box-shadow: 0 4px 20px rgba(0,0,0,0.1) !important;
                     transition: all 0.3s ease;
                 }}
+                /* Bootstrap paints its own navbar/card surfaces, which no
+                   token can reach from the outside. */
+                .navbar.bg-light, .card {{
+                    background-color: var(--color-surface) !important;
+                    color: var(--color-fg);
+                }}
+                .card {{
+                    border-color: var(--color-border);
+                }}
                 .nav-tabs .nav-link {{
-                    color: #666;
+                    color: var(--color-muted);
                     border: none;
                     padding: 1rem 1.5rem;
                 }}
                 .nav-tabs .nav-link.active {{
-                    color: #0d6efd;
-                    border-bottom: 2px solid #0d6efd;
+                    color: var(--color-primary);
+                    border-bottom: 2px solid var(--color-primary);
                     background: none;
                 }}
                 .review-item {{
-                    border-bottom: 1px solid #eee;
+                    border-bottom: 1px solid var(--color-border);
                     padding: 1rem 0;
                 }}
                 .review-item:last-child {{
                     border-bottom: none;
                 }}
                 .btn-primary, .btn-outline-primary {{
-                    background-color: {button_background_color} !important;
-                    color: {button_font_color} !important;
+                    background-color: var(--color-primary) !important;
+                    border-color: var(--color-primary) !important;
+                    color: var(--color-on-primary) !important;
                 }}
                 .text-primary {{
-                    color: {highlight_font_color} !important;
+                    color: var(--color-primary) !important;
                 }}
                 .breadcrumb-item,
                 .breadcrumb-item a,
                 .breadcrumb-item.active {{
-                    color: {highlight_font_color} !important;
+                    color: var(--color-primary) !important;
                 }}
                 .breadcrumb-item + .breadcrumb-item::before {{
-                    color: {highlight_font_color} !important;
+                    color: var(--color-primary) !important;
                 }}
             </style>
         </head>
diff --git a/src/open_apps/apps/start_page/helper.py b/src/open_apps/apps/start_page/helper.py
index 5b827044..bf0ba9f9 100644
--- a/src/open_apps/apps/start_page/helper.py
+++ b/src/open_apps/apps/start_page/helper.py
@@ -57,23 +57,12 @@ def Wrapper(title, description, content, style=1, align=None, color=None, invert
         "wrapper style", style, "align-", align, "invert", invert, "color", color
     )
     
-    # Apply custom styling to title and description
-    title_style = {}
-    desc_style = {}
-    
-    if config:
-        if config.get('heading_font'):
-            title_style['font-family'] = config['heading_font']
-        if config.get('heading_color'):
-            title_style['color'] = config['heading_color']
-        if config.get('font_family'):
-            desc_style['font-family'] = config['font_family']
-        if config.get('font_color'):
-            desc_style['color'] = config['font_color']
-    
+    # Typography is inherited from the shared theme's tokens (see the
+    # stylesheet PageWrapper emits) rather than written as inline styles from
+    # per-app font config, which is what the `appearance` group used to supply.
     inner_content = [
-        H2(title, style=";".join([f"{k}:{v}" for k, v in title_style.items()]) if title_style else None),
-        P(description, style=";".join([f"{k}:{v}" for k, v in desc_style.items()]) if desc_style else None),
+        H2(title),
+        P(description),
         content
     ]
     
@@ -110,26 +99,10 @@ def ItemContent(title, description, color="primary", icon=None, xtra=None, href=
         else:
             content.append(Span(cls=f"icon style2 major fa-{icon}"))
     
-    # Apply font styling to title and description if configured
-    title_style = {}
-    desc_style = {}
-    
-    if config.get('heading_font'):
-        title_style['font-family'] = config['heading_font']
-    if config.get('heading_color'):
-        title_style['color'] = config['heading_color']
-    if config.get('font_family'):
-        desc_style['font-family'] = config['font_family']
-    if config.get('font_color'):
-        desc_style['color'] = config['font_color']
-    if config.get('font_size'):
-        base_size = int(config['font_size'])
-        title_style['font-size'] = f"{base_size * 1.5}px"
-        desc_style['font-size'] = f"{base_size}px"
-    
-    # Add title and description with any configured styling
-    content.append(H3(title, style=";".join([f"{k}:{v}" for k, v in title_style.items()]) if title_style else None))
-    content.append(P(description, style=";".join([f"{k}:{v}" for k, v in desc_style.items()]) if desc_style else None))
+    # Tile typography comes from the shared theme (the `.item h3` / `.item p`
+    # rules in PageWrapper), not from inline per-app font config.
+    content.append(H3(title))
+    content.append(P(description))
     
     # Add any extra content
     if xtra:
@@ -309,29 +282,34 @@ def PageWrapper(title, *content, config=None, theme_css=""):
         *content: Content elements
         config: Configuration dictionary with styling options
         theme_css: Shared design-token CSS from ``open_apps.theme``. Emitted
-            last so it overrides the appearance-derived rules above it; empty
-            unless a non-default theme is selected.
+            last; every color and font below is a ``var()`` into it.
     """
     # Set defaults if config is None
     if config is None:
         config = {}
-    
-    # Generate custom CSS based on configuration
-    custom_css = ""
-    
-    # Font settings
-    if config.get('font_family'):
-        custom_css += f"body {{ font-family: {config['font_family']}; }}\n"
-    if config.get('font_color'):
-        custom_css += f"body {{ color: {config['font_color']}; }}\n"
-    if config.get('heading_font'):
-        custom_css += f"h1, h2, h3, h4, h5, h6 {{ font-family: {config['heading_font']}; }}\n"
-    if config.get('heading_color'):
-        custom_css += f"h1, h2, h3, h4, h5, h6 {{ color: {config['heading_color']}; }}\n"
-    if config.get('background_color'):
-        custom_css += f"body {{ background-color: {config['background_color']}; }}\n"
-    
+
+    # Typography and page chrome come from the shared theme; only geometry
+    # (radii, padding, hover behaviour) is still read from `config`, which is
+    # the start page's `layout` group.
+    custom_css = """
+        body {
+            font-family: var(--font-family);
+            color: var(--color-fg);
+            background-color: var(--color-bg);
+        }
+        h1, h2, h3, h4, h5, h6 {
+            font-family: var(--font-heading);
+            color: var(--color-fg);
+        }
+        #wrapper > .wrapper {
+            background-color: var(--color-bg);
+        }
+    """
+
     # Add iOS-style typography for items
+    # Tile labels stay white in every theme: they sit on the tile fill, not
+    # on the page background, and every tone's fill is dark enough to carry
+    # white text. `--color-fg` here would be white-on-white in a light theme.
     custom_css += """
         .item h3 {
             font-size: 0.9em !important;
@@ -410,11 +388,15 @@ def PageWrapper(title, *content, config=None, theme_css=""):
             .modal.left .modal-dialog {{ margin-left: 5%; }}
             .modal.right .modal-dialog {{ margin-left: auto; margin-right: 5%; }}
             
+            /* Themed like the rest of the page on purpose: a pop-up that
+               stayed near-white on a dark theme would be trivially easy to
+               spot, which confounds the adversarial-pop-up variation. */
             .modal-content {{
-                background-color: #fefefe;
+                background-color: var(--color-surface);
+                color: var(--color-fg);
                 padding: 20px;
                 padding-bottom: 80px;
-                border-radius: 5px;
+                border-radius: var(--radius);
                 box-shadow: 0 4px 8px rgba(0,0,0,0.1);
             }}
             .close-modal {{
@@ -429,11 +411,12 @@ def PageWrapper(title, *content, config=None, theme_css=""):
             }}
             
             .link-button {{
-                background-color: #4CAF50;
+                background-color: var(--color-accent);
+                color: var(--color-btn-fg);
             }}
-            
+
             .link-button:hover {{
-                background-color: #45a049;
+                background-color: var(--color-primary-hover);
             }}
             
             /* Story template item scaling customization */
diff --git a/src/open_apps/apps/start_page/main.py b/src/open_apps/apps/start_page/main.py
index b75fb778..012b56fa 100644
--- a/src/open_apps/apps/start_page/main.py
+++ b/src/open_apps/apps/start_page/main.py
@@ -34,7 +34,39 @@
         generate_random_colors,
     )
 from omegaconf import DictConfig, OmegaConf
-from open_apps.theme import legacy_theme_css
+from open_apps.theme import render_theme_css, resolve_theme, theme_asset
+
+
+def icon_for(app_config, app_name):
+    """Path to an app's start-page tile icon under the active theme.
+
+    The icons are PNGs, so a CSS variable cannot recolor them; the theme picks
+    a set via its `icon_set` asset and the repo ships a hand-made greyscale
+    version alongside the color one. Falls back to the color icon when a theme
+    asks for a set the config has no path for.
+    """
+    if theme_asset(app.config, "start_page", "icon_set", "color") == "bw":
+        bw = app_config.get("bw_icon")
+        if bw:
+            return bw
+    return app_config.get("icon", f"/assets/icons/real_icons/{app_name}.png")
+
+
+def tile_colors(config):
+    """Background fills for the app tiles, in position order.
+
+    The default palette is six saturated iOS-style hues that carry no semantic
+    meaning -- mapping them onto theme tokens would collapse six visually
+    distinct targets into one. Non-light themes do collapse them, deliberately:
+    that is the perturbation `dark` and `mono` are for.
+    """
+    if config.get("use_random_colors"):
+        return generate_random_colors(10)
+    tone = theme_asset(app.config, "start_page", "tone", "light")
+    by_tone = config.get("tile_fill_by_tone") or {}
+    if tone in by_tone:
+        return [by_tone[tone]]
+    return config.app_background_colors
 
 # Define available apps and their route getters
 AVAILABLE_APPS = {
@@ -166,12 +198,19 @@ def initialize_routes_and_configure_task(config: DictConfig = None):
             print(f"Failed to find route getter for {app_name}: {e}")
 
     if getattr(app.config.start_page, "shuffle_icons", False):
-        # randomize icons and app names if specified
-        icons = [getattr(app.config.start_page.apps[app_name], "icon") for app_name in app.config.start_page.apps]
-        random.shuffle(icons)
-        print(app.config.start_page.apps)
-        for app_name in app.config.start_page.apps:
-            app.config.start_page.apps[app_name].icon = icons.pop()
+        # Detach each icon from its app so the picture stops identifying the
+        # tile. Both sets are permuted the same way, otherwise selecting a
+        # `bw` theme would quietly undo the shuffle.
+        apps_cfg = app.config.start_page.apps
+        order = list(apps_cfg)
+        shuffled = order[:]
+        random.shuffle(shuffled)
+        icons = {name: apps_cfg[name].get("icon") for name in order}
+        bw_icons = {name: apps_cfg[name].get("bw_icon") for name in order}
+        for name, source in zip(order, shuffled):
+            apps_cfg[name].icon = icons[source]
+            if bw_icons[source] is not None:
+                apps_cfg[name].bw_icon = bw_icons[source]
 
     return app
 
@@ -183,13 +222,8 @@ def get():
     # Get configuration from app.config
     config = app.config.start_page
     
-    # Check if we should use random colors
-    colors = []
-    if hasattr(config, 'use_random_colors') and config.use_random_colors:
-        colors = generate_random_colors(10)  # Generate more than we need
-    else:
-        colors = config.app_background_colors
-    
+    colors = tile_colors(config)
+
     # Build items based on app configurations
     items = []
     
@@ -216,7 +250,7 @@ def get():
                 ItemContent(
                     app_config.get('title', f"Open{app_name.capitalize()}"),
                     app_config.get('description', f"Description for {app_name}"),
-                    icon=app_config.get('icon', f"/assets/icons/real_icons/{app_name}.png"),
+                    icon=icon_for(app_config, app_name),
                     color=color,
                     href=app_url,
                     config=config,
@@ -330,9 +364,8 @@ def get():
         wrapper,
         footer(),
         config=config,
-        # Resolved per-request so live `reconfigure` theme swaps take effect;
-        # empty string on the default theme.
-        theme_css=legacy_theme_css(app.config, "start_page"),
+        # Resolved per-request so live `reconfigure` theme swaps take effect.
+        theme_css=render_theme_css(resolve_theme(app.config, "start_page")),
     )
 
 
diff --git a/src/open_apps/mcp/README.md b/src/open_apps/mcp/README.md
index c676e163..4abfb70f 100644
--- a/src/open_apps/mcp/README.md
+++ b/src/open_apps/mcp/README.md
@@ -45,9 +45,9 @@ the server is then ready for tool calls.
 | `load_task(key)` | Bind a task for scoring; returns its goal. Call `reset` after. |
 | `get_reward()` | Reward for the bound task (1.0 if complete, else 0.0). |
 | `set_goal(goal)` | Free-form goal, no automatic scoring. |
-| `reconfigure(theme, layout, appearance, content, seed, extras)` | Live variant/seed change. `theme` is the shared global design-token theme; `layout` is per-app structure; `appearance` is legacy (unmigrated apps). |
+| `reconfigure(theme, layout, content, seed, extras)` | Live variant/seed change. `theme` is the shared global design-token theme; `layout` and `content` are per-app. |
 | `list_apps()` | App keys actually registered (Java-aware). |
-| `list_variants(app, group)` | Variant stems for a group (`theme`/`layout`/`content`/`appearance`). |
+| `list_variants(app, group)` | Variant stems for a group (`theme`/`layout`/`content`). |
 | `app_url(app=None)` | Absolute URL of an app's landing page. |
 
 **Actions** are BrowserGym action strings (full-resolution pixels):
diff --git a/src/open_apps/mcp/appserver.py b/src/open_apps/mcp/appserver.py
index 3528b965..b664b49d 100644
--- a/src/open_apps/mcp/appserver.py
+++ b/src/open_apps/mcp/appserver.py
@@ -159,7 +159,6 @@ def reconfigure(
         *,
         theme: str | None = None,
         layout: str | None = None,
-        appearance: str | None = None,
         content: str | None = None,
         seed: int | None = None,
         extras: dict[str, Any] | None = None,
@@ -178,9 +177,6 @@ def reconfigure(
             layout: Per-app structure variant stem under
                 ``config/apps/<app>/layout/`` for ``self.app_name``
                 (e.g. ``kanban_board``).
-            appearance: Legacy per-app variant stem under
-                ``config/apps/<app>/appearance/`` for apps not yet migrated
-                to the theme/layout split.
             content: Variant yaml stem under
                 ``config/apps/<app>/content/`` for ``self.app_name``.
             seed: Fresh integer seed for the OpenApps content samplers.
@@ -194,8 +190,6 @@ def reconfigure(
             overrides.append(f"apps/theme={theme}")
         if layout is not None:
             overrides.append(f"apps/{cfg_dir}/layout={layout}")
-        if appearance is not None:
-            overrides.append(f"apps/{cfg_dir}/appearance={appearance}")
         if content is not None:
             overrides.append(f"apps/{cfg_dir}/content={content}")
         if seed is not None:
@@ -214,7 +208,7 @@ def reconfigure(
         # Routes read ``app.config`` per request, but the assignment above
         # rebinds ``self.config.apps`` to a fresh node — so re-point the
         # FastHTML app at it, otherwise the page keeps rendering the
-        # pre-reconfigure appearance/content.
+        # pre-reconfigure theme/layout/content.
         _fasthtml_app.config = self.config.apps
 
         shutil.rmtree(new_tmp_logs, ignore_errors=True)
diff --git a/src/open_apps/mcp/registry.py b/src/open_apps/mcp/registry.py
index 90e61e0e..0c27a9be 100644
--- a/src/open_apps/mcp/registry.py
+++ b/src/open_apps/mcp/registry.py
@@ -48,7 +48,7 @@ def config_dir_for(app_name: str) -> str:
 
 
 def list_variants(app_name: str, group: str) -> list[str]:
-    """List Hydra variant yamls for a group (``theme``/``layout``/``content``/``appearance``).
+    """List Hydra variant yamls for a group (``theme``/``layout``/``content``).
 
     Returns a sorted list of variant stems (without ``.yaml``).
     ``"default"`` is forced to index 0 when present so it has a stable
diff --git a/src/open_apps/mcp/server.py b/src/open_apps/mcp/server.py
index 72ad63db..2013ddfc 100644
--- a/src/open_apps/mcp/server.py
+++ b/src/open_apps/mcp/server.py
@@ -88,21 +88,18 @@ async def reset(seed: int | None = None):
 async def reconfigure(
     theme: str | None = None,
     layout: str | None = None,
-    appearance: str | None = None,
     content: str | None = None,
     seed: int | None = None,
     extras: dict | None = None,
 ) -> str:
     """Swap theme/layout/content variant and seed (live) and re-seed app state.
 
-    `theme` is the shared design-token theme (global); `layout` is the per-app
-    structure; `appearance` is the legacy per-app variant for apps not yet
-    migrated to the theme/layout split.
+    `theme` is the shared design-token theme and applies to every app;
+    `layout` and `content` are per-app.
     """
     await _require().reconfigure(
         theme=theme,
         layout=layout,
-        appearance=appearance,
         content=content,
         seed=seed,
         extras=extras,
@@ -202,7 +199,7 @@ async def list_apps() -> list[str]:
 
 @mcp.tool()
 async def list_variants(app: str, group: str) -> list[str]:
-    """Variant stems for an app's ``appearance`` or ``content`` group."""
+    """Variant stems for a group: ``theme`` (shared), ``layout`` or ``content``."""
     return _list_variants(app, group)
 
 
diff --git a/src/open_apps/mcp/session.py b/src/open_apps/mcp/session.py
index 66058381..82f5770b 100644
--- a/src/open_apps/mcp/session.py
+++ b/src/open_apps/mcp/session.py
@@ -210,7 +210,6 @@ async def reconfigure(
         *,
         theme: str | None = None,
         layout: str | None = None,
-        appearance: str | None = None,
         content: str | None = None,
         seed: int | None = None,
         extras: dict | None = None,
@@ -220,7 +219,6 @@ async def reconfigure(
             self.appserver.reconfigure,
             theme=theme,
             layout=layout,
-            appearance=appearance,
             content=content,
             seed=seed,
             extras=extras,
diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index abe99f38..5aae7a3c 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -10,7 +10,8 @@
 defined once in ``config/apps/theme/<name>.yaml`` and shared across every
 app. Selecting a theme emits a ``:root { --token: value }`` block that all
 apps consume via ``var(--token)``. This decouples *look* (theme) from
-*structure* (each app's ``layout``).
+*structure* (each app's ``layout``) and from *behaviour* (plain keys in
+each app's ``config/apps/<app>/default.yaml``).
 
 Selection is done with Hydra overrides:
 
@@ -31,15 +32,19 @@
       font-family: "'Inter', sans-serif"
       radius: "8px"
       ...
+    assets:
+      tone: light
+      icon_set: color
 
 The ``tokens`` mapping is open-ended: every ``key: value`` becomes the CSS
 custom property ``--key: value``, so apps can introduce new tokens without
 touching this module.
 
-Apps that have not been migrated to design tokens yet (everything except
-todo) still build their stylesheet from ``config/apps/<app>/appearance/``.
-:func:`legacy_theme_css` bridges the two worlds — see the comment on
-``_LEGACY_ALIASES`` below.
+``assets`` covers what a CSS variable cannot reach: raster icons, Leaflet
+tile layers, CodeMirror stylesheets. It is deliberately *app-agnostic* --
+a theme declares intent (``tone: dark``) and each app maps that onto its
+own concrete choice, so a shared theme file never has to grow a key for
+every app in the repo. See :func:`theme_assets`.
 """
 from __future__ import annotations
 
@@ -53,6 +58,9 @@
 
 _DEFAULT_THEME = "default"
 
+# Fallbacks for a theme that predates (or omits) the `assets` block.
+_DEFAULT_ASSETS: dict[str, str] = {"tone": "light", "icon_set": "color"}
+
 
 def _as_plain(value):
     """Coerce an OmegaConf node (or anything mapping-like) to a plain dict."""
@@ -67,9 +75,9 @@ def _as_plain(value):
 def load_theme(name: str) -> dict:
     """Load a theme's tokens from ``config/apps/theme/<name>.yaml``.
 
-    Returns a dict with at least ``name``, ``tokens`` and ``import_url``.
-    Falls back to the default theme when ``name`` is unknown so a bad
-    override degrades gracefully instead of raising.
+    Returns a dict with at least ``name``, ``tokens``, ``import_url`` and
+    ``assets``. Falls back to the default theme when ``name`` is unknown so
+    a bad override degrades gracefully instead of raising.
     """
     path = _THEME_DIR / f"{name}.yaml"
     if not path.exists():
@@ -78,6 +86,7 @@ def load_theme(name: str) -> dict:
     data.setdefault("name", name)
     data.setdefault("tokens", {})
     data.setdefault("import_url", "")
+    data.setdefault("assets", {})
     return data
 
 
@@ -97,12 +106,14 @@ def resolve_theme(apps_config, app_name: str) -> dict:
     global_theme = getattr(apps_config, "theme", None)
     if global_theme is not None:
         # Allow global theme to be provided either as a composed config node
-        # (apps/theme=<name>) or as a plain string override (apps.theme=<name>). 
+        # (apps/theme=<name>) or as a plain string override (apps.theme=<name>).
         if isinstance(global_theme, str):
             return load_theme(global_theme)
         theme = _as_plain(global_theme)
         theme.setdefault("tokens", {})
         theme["tokens"] = _as_plain(theme["tokens"])
+        theme.setdefault("assets", {})
+        theme["assets"] = _as_plain(theme["assets"])
         return theme
 
     return load_theme(_DEFAULT_THEME)
@@ -149,110 +160,28 @@ def theme_style(apps_config, app_name: str) -> Style:
 
 
 # --------------------------------------------------------------------------
-# Bridge for apps that still render `config/apps/<app>/appearance/*.yaml`
+# Non-CSS theme choices
 # --------------------------------------------------------------------------
-#
-# Only the todo app has been rewritten against design tokens. The other apps
-# build a `:root` block of their own from their `appearance` config and read
-# those names throughout their stylesheets, so a theme selection was invisible
-# to them. Rewriting five stylesheets is a much larger change than this one;
-# until then, re-point the legacy custom properties at the shared tokens.
-#
-# Keys are the legacy custom-property names those apps declare; values are the
-# token they should follow. `--font-family` needs no entry: the theme declares
-# that name itself, and the bridge block is emitted after the app's own
-# stylesheet, so the token value already wins.
-_LEGACY_ALIASES: dict[str, str] = {
-    # calendar
-    "primary": "color-primary",
-    "primary-hover": "color-accent",
-    "secondary": "color-neutral",
-    "background": "color-bg",
-    "text": "color-fg",
-    "error": "color-danger",
-    "border": "color-border",
-    "heading-font": "font-heading",
-    "base-font-size": "font-size-base",
-    "button-border-radius": "radius",
-    # messenger + code editor
-    "custom-font-family": "font-family",
-    "custom-font-size": "font-size-base",
-    "custom-font-color": "color-fg",
-    "custom-background-color": "color-bg",
-    "chat-font-family": "font-family",
-    "chat-font-size": "font-size-base",
-    "chat-font-color": "color-fg",
-    "chat-header-font-color": "color-muted",
-    "chat-primary-bubble-color": "color-primary",
-    "chat-secondary-bubble-color": "color-surface",
-    "chat-display-background-color": "color-bg",
-    "main-bg-color": "color-surface",
-}
-
-# The page chrome every app shares. Aliasing alone is not enough: an app only
-# picks up a token where its own CSS happens to use a variable, and several
-# paint the page from hard-coded values.
-_LEGACY_BASE_CSS = """
-html, body {
-  background-color: var(--color-bg);
-  color: var(--color-fg);
-  font-family: var(--font-family);
-}
-"""
 
-# Per-app selectors whose colors are hard-coded in the app's stylesheet (so no
-# alias can reach them) but which cover enough of the page that leaving them
-# unthemed reads as "the theme did nothing".
-_LEGACY_APP_CSS: dict[str, str] = {
-    "maps": """
-#sidebar { background: var(--color-surface); }
-#sidebar h2, #sidebar h3 { color: var(--color-fg); }
-.popup-list-item, .route-result, .saved-place { background: var(--color-surface); }
-""",
-    "code_editor": """
-.main-content { background-color: var(--color-surface); }
-textarea, textarea.styled-content { background-color: var(--color-surface); }
-""",
-    "messenger": """
-.bg-base-100, .bg-base-200 { background-color: var(--color-surface); }
-""",
-    "start_page": """
-#wrapper > .wrapper { background-color: var(--color-bg); }
-""",
-}
-
-
-def legacy_theme_css(apps_config, app_name: str) -> str:
-    """CSS that makes the active theme visible in an app built on ``appearance``.
-
-    Emits the theme's token block, the legacy-variable aliases, and the shared
-    page chrome. Returns ``""`` for the ``default`` theme: unmigrated apps are
-    still described entirely by their ``appearance`` config, so a deployment
-    that never selects a theme must render exactly as it did before.
-
-    Emit the result *after* the app's own stylesheet — the bridge relies on
-    document order, not specificity, to win.
+
+def theme_assets(apps_config, app_name: str) -> dict:
+    """The active theme's ``assets`` block for ``app_name``, with defaults filled.
+
+    Keys are app-agnostic on purpose:
+
+    * ``tone``     -- ``light`` | ``dark`` | ``mono``. Apps map this onto their
+      own concrete asset (maps picks a tile layer, the code editor picks a
+      CodeMirror stylesheet, the start page picks a tile fill).
+    * ``icon_set`` -- ``color`` | ``bw``. Which raster icon directory to serve.
+
+    A theme that omits ``assets`` (or omits a key) gets the light/color
+    defaults, so adding a new theme file never has to spell them out.
     """
-    theme = resolve_theme(apps_config, app_name)
-    if str(theme.get("name", _DEFAULT_THEME)) == _DEFAULT_THEME:
-        return ""
+    assets = dict(_DEFAULT_ASSETS)
+    assets.update(_as_plain(resolve_theme(apps_config, app_name).get("assets", {})))
+    return assets
 
-    tokens = _as_plain(theme.get("tokens", {}))
-    aliases = "\n".join(
-        f"  --{legacy}: var(--{token});"
-        for legacy, token in _LEGACY_ALIASES.items()
-        if token in tokens
-    )
-    return "\n".join(
-        [
-            render_theme_css(theme),
-            f":root {{\n{aliases}\n}}",
-            _LEGACY_BASE_CSS,
-            _LEGACY_APP_CSS.get(app_name, ""),
-        ]
-    )
-
-
-def legacy_theme_style(apps_config, app_name: str) -> Style:
-    """:func:`legacy_theme_css` as a FastHTML ``Style`` (empty on the default theme)."""
-    return Style(legacy_theme_css(apps_config, app_name))
+
+def theme_asset(apps_config, app_name: str, key: str, default=None):
+    """A single :func:`theme_assets` entry, or ``default`` when unset."""
+    return theme_assets(apps_config, app_name).get(key, default)
diff --git a/tests/save_screenshots.py b/tests/save_screenshots.py
index 13f9eec9..06a4dd89 100644
--- a/tests/save_screenshots.py
+++ b/tests/save_screenshots.py
@@ -63,14 +63,15 @@ class ComparisonResult:
 
 THEME_DIR = REPO_ROOT / "config" / "apps" / "theme"
 
-# The todo app no longer has an `appearance` group -- it renders from the shared
-# design tokens, so its counterpart to an appearance variant is a theme name.
-# Everything else still composes `config/apps/<app>/appearance/`.
-APPEARANCE_APPS = ("start_page", "calendar", "messenger", "maps", "code_editor")
 CONTENT_APPS = ("start_page", "todo", "calendar", "messenger", "maps", "code_editor")
-TODO_THEME_FOR_APPEARANCE = {
-    "dark_theme": "dark",
-    "challenging_font": "challenging_font",
+
+# Per-app structure variants worth a screenshot of their own. Themes are
+# captured separately (one variation per stem) because they are global -- a
+# layout is not, so it has to name its app.
+LAYOUT_VARIATIONS = {
+    "layout_kanban_board": ["apps/todo/layout=kanban_board"],
+    "layout_broken_logos": ["apps/start_page/layout=broken_logos"],
+    "layout_clickable_logos": ["apps/start_page/layout=clickable_logos"],
 }
 
 
@@ -80,34 +81,24 @@ def available_themes() -> list[str]:
     return ["default"] + [stem for stem in stems if stem != "default"]
 
 
-def appearance_variation(name: str, onlineshop_overrides: list[str]) -> list[str]:
-    apps = list(APPEARANCE_APPS) + (["onlineshop"] if onlineshop_overrides else [])
-    return (
-        onlineshop_overrides
-        + [f"apps/{app_name}/appearance={name}" for app_name in apps]
-        + [f"apps.todo.theme={TODO_THEME_FOR_APPEARANCE[name]}"]
-    )
-
-
 def build_variation_overrides(include_onlineshop: bool) -> dict[str, list[str]]:
     onlineshop_overrides = ["apps.onlineshop.enable=True"] if include_onlineshop else []
     content_apps = list(CONTENT_APPS) + (["onlineshop"] if include_onlineshop else [])
 
     variations = {
         "default": onlineshop_overrides,
-        "dark_theme": appearance_variation("dark_theme", onlineshop_overrides),
-        "challenging_font": appearance_variation(
-            "challenging_font", onlineshop_overrides
-        ),
         "german": onlineshop_overrides
         + [f"apps/{app_name}/content=german" for app_name in content_apps],
         "long_descriptions": onlineshop_overrides
         + [f"apps/{app_name}/content=long_descriptions" for app_name in content_apps],
     }
-    # One variation per shared theme, named `theme_<stem>`, so a single
-    # `apps/theme=` override can be captured across every app at once.
+    # One variation per shared theme, named `theme_<stem>`. A single
+    # `apps/theme=` override reaches every app, which is what replaced the
+    # per-app `appearance` groups.
     for theme in available_themes():
         variations[f"theme_{theme}"] = onlineshop_overrides + [f"apps/theme={theme}"]
+    for name, overrides in LAYOUT_VARIATIONS.items():
+        variations[name] = onlineshop_overrides + overrides
     return variations
 
 
@@ -140,13 +131,14 @@ def parse_args() -> argparse.Namespace:
         "--variation",
         dest="variations",
         nargs="*",
-        # `theme_*` entries are opt-in: they are not part of the reference set,
-        # they exist so the docs gallery can be regenerated with one command.
+        # Every `theme_*` and `layout_*` entry is selectable, but only the set
+        # below is captured by default -- the rest exist so the docs gallery
+        # can be regenerated with one command.
         choices=sorted(build_variation_overrides(include_onlineshop=False)),
         default=[
             "default",
-            "dark_theme",
-            "challenging_font",
+            "theme_dark",
+            "theme_challenging_font",
             "german",
             "long_descriptions",
         ],
diff --git a/tests/test_apps.py b/tests/test_apps.py
index 48d2191a..028d546f 100644
--- a/tests/test_apps.py
+++ b/tests/test_apps.py
@@ -33,10 +33,12 @@
 @pytest.fixture(scope="module")
 def client(tmpdir_factory):
     logs_dir = str(tmpdir_factory.getbasetemp())
+    # Exercise a non-default selection on every axis: the shared theme
+    # (global), a per-app theme override, and per-app content.
     alt_config = [
-        "apps/messenger/appearance=challenging_font",
+        "apps/theme=challenging_font",
         "apps/messenger/content=misleading_descriptions",
-        "apps/calendar/appearance=dark_theme",
+        "apps.calendar.theme=dark",
     ]
     standard_overrides = [f"logs_dir={logs_dir}"]
 
diff --git a/tests/test_theme.py b/tests/test_theme.py
index 4dd6286b..6f8a6cf9 100644
--- a/tests/test_theme.py
+++ b/tests/test_theme.py
@@ -21,6 +21,8 @@
     load_theme,
     render_theme_tokens,
     resolve_theme,
+    theme_asset,
+    theme_assets,
     theme_style,
 )
 
@@ -45,7 +47,64 @@ def test_unknown_theme_falls_back_to_default(self):
 
     def test_always_has_required_keys(self):
         theme = load_theme("dark")
-        assert set(theme) >= {"name", "tokens", "import_url"}
+        assert set(theme) >= {"name", "tokens", "import_url", "assets"}
+
+
+class TestTokenVocabulary:
+    """Every theme must declare the same tokens.
+
+    Apps use `var(--token)` without knowing which theme is active, so a theme
+    that omits one renders that property as an empty value -- an invisible
+    button rather than a loud failure.
+    """
+
+    THEMES = [
+        "default", "dark", "mono", "challenging_font",
+        "colorblind", "solarized", "material", "bootstrap",
+    ]
+
+    def test_all_themes_declare_the_default_vocabulary(self):
+        expected = set(load_theme("default")["tokens"])
+        for name in self.THEMES:
+            assert set(load_theme(name)["tokens"]) == expected, name
+
+    def test_dark_theme_is_actually_dark(self):
+        """Regression: `dark` was a port of todo's local variant and had a
+        white background with white foreground text."""
+        tokens = load_theme("dark")["tokens"]
+        assert tokens["color-bg"] != tokens["color-fg"]
+
+    def test_no_theme_has_invisible_body_text(self):
+        for name in self.THEMES:
+            tokens = load_theme(name)["tokens"]
+            assert tokens["color-bg"] != tokens["color-fg"], name
+
+
+class TestThemeAssets:
+
+    def test_defaults_when_theme_omits_assets(self):
+        cfg = OmegaConf.create({"theme": {"name": "x", "tokens": {}}, "todo": {}})
+        assert theme_assets(cfg, "todo") == {"tone": "light", "icon_set": "color"}
+
+    def test_reads_assets_from_the_theme_file(self):
+        cfg = OmegaConf.create({"theme": "dark", "maps": {}})
+        assert theme_assets(cfg, "maps")["tone"] == "dark"
+        assert theme_assets(cfg, "maps")["icon_set"] == "bw"
+
+    def test_partial_assets_are_filled_from_defaults(self):
+        cfg = OmegaConf.create(
+            {"theme": {"name": "x", "tokens": {}, "assets": {"tone": "dark"}}}
+        )
+        assert theme_assets(cfg, "todo") == {"tone": "dark", "icon_set": "color"}
+
+    def test_follows_per_app_theme_override(self):
+        cfg = OmegaConf.create({"theme": "default", "maps": {"theme": "dark"}})
+        assert theme_asset(cfg, "maps", "tone") == "dark"
+        assert theme_asset(cfg, "calendar", "tone") == "light"
+
+    def test_unknown_key_returns_default(self):
+        cfg = OmegaConf.create({"theme": "default"})
+        assert theme_asset(cfg, "todo", "no_such_key", "fallback") == "fallback"
 
 
 class TestResolveTheme:

From 69185c340590320ff8a19d1a5fa0e56ad4a684f1 Mon Sep 17 00:00:00 2001
From: Smokey <aaronsmulktis@gmail.com>
Date: Tue, 8 Sep 2026 14:07:36 -0400
Subject: [PATCH 12/23] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/open_apps/theme.py | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index 5aae7a3c..32ceaec3 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -132,7 +132,17 @@ def render_theme_css(theme: dict) -> str:
         # Allow only simple custom-property names to avoid broken CSS/injection.
         if (not key) or any(not (c.isalnum() or c in "-_") for c in key):
             continue
-        val = str(value).replace("\n", " ").replace("\r", " ")
+        # Sanitize values to avoid breaking out of the declaration / <style> context.
+        val = (
+            str(value)
+            .replace("\n", " ")
+            .replace("\r", " ")
+            .replace(";", " ")
+            .replace("}", " ")
+            .replace("<", " ")
+            .replace(">", " ")
+            .strip()
+        )
         safe_lines.append(f"  --{key}: {val};")
 
     lines = "\n".join(safe_lines)

From 459f7eee87e1bd3687cce2d68674c5d7271a9d5a Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Wed, 9 Sep 2026 10:33:08 -0400
Subject: [PATCH 13/23] [Docs] Add an appearance -> theme/layout migration
 table

Anyone with existing `apps/<app>/appearance=...` overrides -- notably the
paper's variation grid -- gets a Hydra resolution error after this branch
merges, with no pointer to the replacement. Maps every old value onto its
theme or layout equivalent, calls out the two renderings that shift
(`mono` polarity, `colorblind` scope), and points at the `v1.0-paper` tag
for anyone who wants the old tree rather than a port.
---
 docs/index.md                 |  27 +++++++++++++++
 site/index.html               |  60 ++++++++++++++++++++++++++++++++++
 site/index.md                 |  27 +++++++++++++++
 site/search/search_index.json |   2 +-
 site/sitemap.xml              |  10 +++---
 site/sitemap.xml.gz           | Bin 248 -> 248 bytes
 6 files changed, 120 insertions(+), 6 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index a338017d..6860b2a5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -123,6 +123,33 @@ Available layouts: `todo` has `default` and `kanban_board`; `start_page` has
 `default`, `broken_logos` (icons detached from their tiles) and
 `clickable_logos`; the other apps currently have `default` only.
 
+#### Migrating from `appearance`
+
+The `appearance` group these two replaced was removed. Overrides written
+against it no longer resolve; translate them as:
+
+| Old override | New override |
+| --- | --- |
+| `apps/<app>/appearance=default` | `apps/theme=default` |
+| `apps/<app>/appearance=dark_theme` | `apps/theme=dark` |
+| `apps/<app>/appearance=black_and_white` | `apps/theme=mono` |
+| `apps/<app>/appearance=challenging_font` | `apps/theme=challenging_font` |
+| `apps/code_editor/appearance=colorblind_access` | `apps/theme=colorblind` |
+| `apps/todo/appearance=kanban_board` | `apps/todo/layout=kanban_board` |
+| `apps/start_page/appearance=broken_logos` | `apps/start_page/layout=broken_logos` |
+| `apps/start_page/appearance=clickable_logos` | `apps/start_page/layout=clickable_logos` |
+
+The theme rows are global, so the six per-app overrides the old dark variation
+needed collapse to one `apps/theme=dark`. Two renderings shift slightly:
+`mono` picks white-page/black-ink for every app, where the old
+`black_and_white` variants disagreed on polarity (calendar inverted the page,
+the rest did not), and `colorblind` is now available to all apps rather than
+the code editor alone.
+
+To reproduce the numbers in [the paper](https://arxiv.org/abs/2511.20766)
+rather than port to the new axes, check out the `v1.0-paper` tag — the last
+tree with `appearance` intact.
+
 #### Content
 
 /// tab | german
diff --git a/site/index.html b/site/index.html
index 0c0b2d7e..a016c159 100644
--- a/site/index.html
+++ b/site/index.html
@@ -537,6 +537,60 @@ <h4 id="layout">Layout</h4>
 <p>Available layouts: <code>todo</code> has <code>default</code> and <code>kanban_board</code>; <code>start_page</code> has
 <code>default</code>, <code>broken_logos</code> (icons detached from their tiles) and
 <code>clickable_logos</code>; the other apps currently have <code>default</code> only.</p>
+<h4 id="migrating-from-appearance">Migrating from <code>appearance</code></h4>
+<p>The <code>appearance</code> group these two replaced was removed. Overrides written
+against it no longer resolve; translate them as:</p>
+<div class="table-wrapper"><table>
+<thead>
+<tr>
+<th>Old override</th>
+<th>New override</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>apps/&lt;app&gt;/appearance=default</code></td>
+<td><code>apps/theme=default</code></td>
+</tr>
+<tr>
+<td><code>apps/&lt;app&gt;/appearance=dark_theme</code></td>
+<td><code>apps/theme=dark</code></td>
+</tr>
+<tr>
+<td><code>apps/&lt;app&gt;/appearance=black_and_white</code></td>
+<td><code>apps/theme=mono</code></td>
+</tr>
+<tr>
+<td><code>apps/&lt;app&gt;/appearance=challenging_font</code></td>
+<td><code>apps/theme=challenging_font</code></td>
+</tr>
+<tr>
+<td><code>apps/code_editor/appearance=colorblind_access</code></td>
+<td><code>apps/theme=colorblind</code></td>
+</tr>
+<tr>
+<td><code>apps/todo/appearance=kanban_board</code></td>
+<td><code>apps/todo/layout=kanban_board</code></td>
+</tr>
+<tr>
+<td><code>apps/start_page/appearance=broken_logos</code></td>
+<td><code>apps/start_page/layout=broken_logos</code></td>
+</tr>
+<tr>
+<td><code>apps/start_page/appearance=clickable_logos</code></td>
+<td><code>apps/start_page/layout=clickable_logos</code></td>
+</tr>
+</tbody>
+</table></div>
+<p>The theme rows are global, so the six per-app overrides the old dark variation
+needed collapse to one <code>apps/theme=dark</code>. Two renderings shift slightly:
+<code>mono</code> picks white-page/black-ink for every app, where the old
+<code>black_and_white</code> variants disagreed on polarity (calendar inverted the page,
+the rest did not), and <code>colorblind</code> is now available to all apps rather than
+the code editor alone.</p>
+<p>To reproduce the numbers in <a href="https://arxiv.org/abs/2511.20766">the paper</a>
+rather than port to the new axes, check out the <code>v1.0-paper</code> tag — the last
+tree with <code>appearance</code> intact.</p>
 <h4 id="content">Content</h4>
 <div class="tabbed-set" data-tabs="2:3"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><label for="__tabbed_2_1">german</label><div class="tabbed-content">
 <div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">CONTENT</span><span class="o">=</span>german
@@ -808,6 +862,12 @@ <h2 id="attribution">Attribution</h2>
             Layout
         </a>
         
+        <a href="#migrating-from-appearance"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            Migrating from appearance
+        </a>
+        
         <a href="#content"
             class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
             data-active="false" data-depth="3">
diff --git a/site/index.md b/site/index.md
index a338017d..6860b2a5 100644
--- a/site/index.md
+++ b/site/index.md
@@ -123,6 +123,33 @@ Available layouts: `todo` has `default` and `kanban_board`; `start_page` has
 `default`, `broken_logos` (icons detached from their tiles) and
 `clickable_logos`; the other apps currently have `default` only.
 
+#### Migrating from `appearance`
+
+The `appearance` group these two replaced was removed. Overrides written
+against it no longer resolve; translate them as:
+
+| Old override | New override |
+| --- | --- |
+| `apps/<app>/appearance=default` | `apps/theme=default` |
+| `apps/<app>/appearance=dark_theme` | `apps/theme=dark` |
+| `apps/<app>/appearance=black_and_white` | `apps/theme=mono` |
+| `apps/<app>/appearance=challenging_font` | `apps/theme=challenging_font` |
+| `apps/code_editor/appearance=colorblind_access` | `apps/theme=colorblind` |
+| `apps/todo/appearance=kanban_board` | `apps/todo/layout=kanban_board` |
+| `apps/start_page/appearance=broken_logos` | `apps/start_page/layout=broken_logos` |
+| `apps/start_page/appearance=clickable_logos` | `apps/start_page/layout=clickable_logos` |
+
+The theme rows are global, so the six per-app overrides the old dark variation
+needed collapse to one `apps/theme=dark`. Two renderings shift slightly:
+`mono` picks white-page/black-ink for every app, where the old
+`black_and_white` variants disagreed on polarity (calendar inverted the page,
+the rest did not), and `colorblind` is now available to all apps rather than
+the code editor alone.
+
+To reproduce the numbers in [the paper](https://arxiv.org/abs/2511.20766)
+rather than port to the new axes, check out the `v1.0-paper` tag — the last
+tree with `appearance` intact.
+
 #### Content
 
 /// tab | german
diff --git a/site/search/search_index.json b/site/search/search_index.json
index a83c0f25..5368475c 100644
--- a/site/search/search_index.json
+++ b/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ . Theme challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist. Layout uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only. Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy. Exposing OpenApps as an MCP server If you want an agent to interact with OpenApps using MCP please see src/mcp/README.md . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all . Running across goal variations Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded. Testing Run all tests via: uv run - m pytest tests / Attribution 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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ .","title":"App variations"},{"location":"#theme","text":"challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist.","title":"Theme"},{"location":"#layout","text":"uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only.","title":"Layout"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy.","title":"Content"},{"location":"#exposing-openapps-as-an-mcp-server","text":"If you want an agent to interact with OpenApps using MCP please see src/mcp/README.md .","title":"Exposing OpenApps as an MCP server"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all .","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#running-across-goal-variations","text":"Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded.","title":"Running across goal variations"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements. Running Evals on a Cluster (SLURM + vLLM + W&B) The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it. One-time cluster setup The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically. 1. Launch the persistent vLLM serve job Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it... 2. Submit the eval job scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True 3. Check results SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"agents/#running-evals-on-a-cluster-slurm-vllm-wb","text":"The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it.","title":"Running Evals on a Cluster (SLURM + vLLM + W&amp;B)"},{"location":"agents/#one-time-cluster-setup","text":"The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically.","title":"One-time cluster setup"},{"location":"agents/#1-launch-the-persistent-vllm-serve-job","text":"Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it...","title":"1. Launch the persistent vLLM serve job"},{"location":"agents/#2-submit-the-eval-job","text":"scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True","title":"2. Submit the eval job"},{"location":"agents/#3-check-results","text":"SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"3. Check results"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./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. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task . Goal Variations Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"},{"location":"tasks/#goal-variations","text":"Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Goal Variations"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ . Theme challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist. Layout uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only. Migrating from appearance The appearance group these two replaced was removed. Overrides written against it no longer resolve; translate them as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. To reproduce the numbers in the paper rather than port to the new axes, check out the v1.0-paper tag \u2014 the last tree with appearance intact. Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy. Exposing OpenApps as an MCP server If you want an agent to interact with OpenApps using MCP please see src/mcp/README.md . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all . Running across goal variations Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded. Testing Run all tests via: uv run - m pytest tests / Attribution 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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ .","title":"App variations"},{"location":"#theme","text":"challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist.","title":"Theme"},{"location":"#layout","text":"uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only.","title":"Layout"},{"location":"#migrating-from-appearance","text":"The appearance group these two replaced was removed. Overrides written against it no longer resolve; translate them as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. To reproduce the numbers in the paper rather than port to the new axes, check out the v1.0-paper tag \u2014 the last tree with appearance intact.","title":"Migrating from appearance"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy.","title":"Content"},{"location":"#exposing-openapps-as-an-mcp-server","text":"If you want an agent to interact with OpenApps using MCP please see src/mcp/README.md .","title":"Exposing OpenApps as an MCP server"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all .","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#running-across-goal-variations","text":"Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded.","title":"Running across goal variations"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements. Running Evals on a Cluster (SLURM + vLLM + W&B) The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it. One-time cluster setup The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically. 1. Launch the persistent vLLM serve job Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it... 2. Submit the eval job scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True 3. Check results SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"agents/#running-evals-on-a-cluster-slurm-vllm-wb","text":"The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it.","title":"Running Evals on a Cluster (SLURM + vLLM + W&amp;B)"},{"location":"agents/#one-time-cluster-setup","text":"The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically.","title":"One-time cluster setup"},{"location":"agents/#1-launch-the-persistent-vllm-serve-job","text":"Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it...","title":"1. Launch the persistent vLLM serve job"},{"location":"agents/#2-submit-the-eval-job","text":"scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True","title":"2. Submit the eval job"},{"location":"agents/#3-check-results","text":"SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"3. Check results"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./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. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task . Goal Variations Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"},{"location":"tasks/#goal-variations","text":"Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Goal Variations"}]}
\ No newline at end of file
diff --git a/site/sitemap.xml b/site/sitemap.xml
index c0ff6e23..fa3ef46c 100644
--- a/site/sitemap.xml
+++ b/site/sitemap.xml
@@ -2,22 +2,22 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/</loc>
-         <lastmod>2026-09-01</lastmod>
+         <lastmod>2026-09-09</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/Intro%20to%20UI%20Agents/</loc>
-         <lastmod>2026-09-01</lastmod>
+         <lastmod>2026-09-09</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/agents/</loc>
-         <lastmod>2026-09-01</lastmod>
+         <lastmod>2026-09-09</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/installation/</loc>
-         <lastmod>2026-09-01</lastmod>
+         <lastmod>2026-09-09</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/tasks/</loc>
-         <lastmod>2026-09-01</lastmod>
+         <lastmod>2026-09-09</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/site/sitemap.xml.gz b/site/sitemap.xml.gz
index 996f272771418aca66f31347a6c17612af881f55..0378dc75ca2e7d109f4848965ed794d981da7486 100644
GIT binary patch
literal 248
zcmV<U00;jciwFpSp`dC4|8r?{Wo=<_E_iKh0L@atZo)7Oz4H}Sq#a2@4+y3<h|45S
zyTAv8khKwM9K~kc=g$R%cIUvX$WE;1_nsm*o1Y<8-@agg)QW}FqVmbXDWt9yhyBNV
zB{pW(TuMYw6@wGDq9@AlN{!<vF_0f@MhT@;=z4yjx;K@UYhh*;$3$?uU89NM%*29B
z^JSes0-TFSZ;R_?7pT7+WdQY=ecI-Xs!`L#UjmCXz{%9QUe5KJ4@2&~o1%J1J}bUU
yRN$@FG^N9i)3)=8UhK;L0}mk~*%&SH_Po{!Sv)`S8P~!aZhis6WtH<00{{RgDtZwB

literal 248
zcmV<U00;jciwFpS6_#oO|8r?{Wo=<_E_iKh0L@ZOZ^AGPz4I%oNINzTJxpV2gSbrM
z#AW<|5WF@bO`_P){rshXrrkL(AN(czy(i1<`g`=%1v9xAI<b^WR2XbLy3luG|M^kB
ziM3v|=j;i&D#L*~F)*ihfN7c}ImXc>k}>x{b|?kGy$MRLgkDs|W`J9Ewbn<gXA~+h
zU&i7g##2T@lkFgT$HVy`U4&i2ut|xag?ZyIfFT~^Q8%i2t<|bl%QABB-5BAQ@=@|_
y;2d8X#k1RQi`(=V_{plwKhWR;vGLw;`JU%0VMC_}j&Tj;!}Sl<!j%aT0{{Teb$agr


From 348d532549bb8a60f2187cbe8af8fc5a3aacd304 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Fri, 11 Sep 2026 10:18:23 -0400
Subject: [PATCH 14/23] [Fix] address Copilot undefined path var

---
 tests/save_screenshots.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/save_screenshots.py b/tests/save_screenshots.py
index 06a4dd89..9b318289 100644
--- a/tests/save_screenshots.py
+++ b/tests/save_screenshots.py
@@ -77,7 +77,7 @@ class ComparisonResult:
 
 def available_themes() -> list[str]:
     """Theme stems under ``config/apps/theme/``, default first."""
-    stems = sorted(path.stem for path in THEME_DIR.glob("*.yaml"))
+    stems = sorted(p.stem for p in THEME_DIR.glob("*.yaml"))
     return ["default"] + [stem for stem in stems if stem != "default"]
 
 

From 39851d40cae258938a97bca7118818e3d8509b08 Mon Sep 17 00:00:00 2001
From: Smokey <aaronsmulktis@gmail.com>
Date: Fri, 11 Sep 2026 11:58:40 -0400
Subject: [PATCH 15/23] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/open_apps/theme.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index 32ceaec3..5555eb47 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -79,9 +79,9 @@ def load_theme(name: str) -> dict:
     ``assets``. Falls back to the default theme when ``name`` is unknown so
     a bad override degrades gracefully instead of raising.
     """
+    if not name or any(not (char.isalnum() or char in "-_") for char in name):
+        name = _DEFAULT_THEME
     path = _THEME_DIR / f"{name}.yaml"
-    if not path.exists():
-        path = _THEME_DIR / f"{_DEFAULT_THEME}.yaml"
     data = yaml.safe_load(path.read_text()) or {}
     data.setdefault("name", name)
     data.setdefault("tokens", {})

From c4ad3448b7093124bab8728f1116f3f95e35ad1d Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Fri, 11 Sep 2026 12:06:01 -0400
Subject: [PATCH 16/23] [Fix] Keep appearance= bindable on the MCP reconfigure
 tool

Removing the parameter changed the published tool schema, so an existing
client calling reconfigure(appearance=...) fails argument validation
before the call reaches us -- with no alias and no error pointing at the
replacement.

appearance is back as a deprecated keyword on AppServer/Session/the MCP
tool, translated onto the new axes by registry.migrate_appearance() using
the same map the docs migration table publishes: five stems became shared
themes, three became per-app layouts. Each call raises DeprecationWarning;
an appearance that disagrees with a theme/layout passed alongside it
raises ValueError rather than silently picking a winner, and an unknown
stem raises with the known values listed.

list_variants(app, 'appearance') now raises too. The group's directory is
gone, so it was falling through to the missing-dir ['default'] fallback --
a client sampling variations would get a silently single-variant sweep.

Verified appearance='dark_theme' composes a config identical to
theme='dark', and appearance='kanban_board' sets todo.layout=kanban_board.

Test plan: uv run -m pytest tests/ -> 766 passed, 7 skipped (was 755/7;
+11, including one asserting the reconfigure tool schema still advertises
an optional appearance property). ruff unchanged at 6 pre-existing E402.
---
 src/open_apps/mcp/README.md    | 28 ++++++++++++-
 src/open_apps/mcp/appserver.py | 12 +++++-
 src/open_apps/mcp/registry.py  | 68 ++++++++++++++++++++++++++++++
 src/open_apps/mcp/server.py    |  9 ++++
 src/open_apps/mcp/session.py   |  4 ++
 tests/test_mcp.py              | 75 ++++++++++++++++++++++++++++++++++
 6 files changed, 194 insertions(+), 2 deletions(-)

diff --git a/src/open_apps/mcp/README.md b/src/open_apps/mcp/README.md
index 4abfb70f..f5a91268 100644
--- a/src/open_apps/mcp/README.md
+++ b/src/open_apps/mcp/README.md
@@ -45,11 +45,37 @@ the server is then ready for tool calls.
 | `load_task(key)` | Bind a task for scoring; returns its goal. Call `reset` after. |
 | `get_reward()` | Reward for the bound task (1.0 if complete, else 0.0). |
 | `set_goal(goal)` | Free-form goal, no automatic scoring. |
-| `reconfigure(theme, layout, content, seed, extras)` | Live variant/seed change. `theme` is the shared global design-token theme; `layout` and `content` are per-app. |
+| `reconfigure(theme, layout, content, seed, extras, appearance)` | Live variant/seed change. `theme` is the shared global design-token theme; `layout` and `content` are per-app. `appearance` is deprecated — see below. |
 | `list_apps()` | App keys actually registered (Java-aware). |
 | `list_variants(app, group)` | Variant stems for a group (`theme`/`layout`/`content`). |
 | `app_url(app=None)` | Absolute URL of an app's landing page. |
 
+### Deprecated: `appearance`
+
+`reconfigure` used to take a per-app `appearance` stem. That group was split
+into a shared `theme` (look) and a per-app `layout` (structure). The parameter
+still exists so existing clients keep binding, and is translated:
+
+| `appearance=` | becomes |
+| --- | --- |
+| `default` | `theme="default"` |
+| `dark_theme` | `theme="dark"` |
+| `black_and_white` | `theme="mono"` |
+| `challenging_font` | `theme="challenging_font"` |
+| `colorblind_access` | `theme="colorblind"` |
+| `kanban_board` | `layout="kanban_board"` |
+| `broken_logos` | `layout="broken_logos"` |
+| `clickable_logos` | `layout="clickable_logos"` |
+
+Each call raises a `DeprecationWarning`; passing `appearance` together with a
+`theme`/`layout` it disagrees with raises `ValueError` rather than silently
+picking one. `list_variants(app, "appearance")` raises too — the group's
+directory is gone, and the missing-dir fallback would otherwise answer
+`["default"]` and quietly drop every variation from a sweep. Two renderings
+shift slightly under the new axes (`mono` polarity, `colorblind` scope); the
+[docs](https://facebookresearch.github.io/OpenApps/) migration table has the
+detail. `appearance` will be removed in a later release.
+
 **Actions** are BrowserGym action strings (full-resolution pixels):
 
 ```text
diff --git a/src/open_apps/mcp/appserver.py b/src/open_apps/mcp/appserver.py
index b664b49d..b488ea53 100644
--- a/src/open_apps/mcp/appserver.py
+++ b/src/open_apps/mcp/appserver.py
@@ -38,7 +38,7 @@
     initialize_routes_and_configure_task,
     reset_all_apps,
 )
-from open_apps.mcp.registry import config_dir_for, url_path_for
+from open_apps.mcp.registry import config_dir_for, migrate_appearance, url_path_for
 from open_apps.state import get_current_state
 
 
@@ -162,6 +162,7 @@ def reconfigure(
         content: str | None = None,
         seed: int | None = None,
         extras: dict[str, Any] | None = None,
+        appearance: str | None = None,
     ) -> None:
         """Recompose the Hydra config with new variant choices and seed.
 
@@ -183,7 +184,16 @@ def reconfigure(
             extras: Additional dotpath overrides applied to the live
                 config in-place after compose. Example for the maps
                 app: ``{"apps.maps.init_location": [40.78, -73.97]}``.
+            appearance: **Deprecated.** Stem from the removed ``appearance``
+                group, translated onto ``theme``/``layout`` via
+                ``registry.APPEARANCE_MIGRATION``. Raises if it disagrees
+                with a ``theme``/``layout`` passed alongside it.
         """
+        if appearance is not None:
+            theme, layout = migrate_appearance(
+                appearance, theme=theme, layout=layout
+            )
+
         cfg_dir = config_dir_for(self.app_name)
         overrides: list[str] = []
         if theme is not None:
diff --git a/src/open_apps/mcp/registry.py b/src/open_apps/mcp/registry.py
index 0c27a9be..2de943b9 100644
--- a/src/open_apps/mcp/registry.py
+++ b/src/open_apps/mcp/registry.py
@@ -14,6 +14,8 @@
 
 from __future__ import annotations
 
+import warnings
+
 from open_apps import config_dir
 
 
@@ -47,6 +49,62 @@ def config_dir_for(app_name: str) -> str:
     return APP_CONFIG_DIRS.get(app_name, app_name)
 
 
+# ---------------------------------------------------------------------------
+# Legacy ``appearance`` group (removed — kept resolvable for one release).
+
+# ``appearance`` conflated global look with per-app structure, so the split is
+# not one-to-one: five stems became shared themes, three became per-app
+# layouts. Same mapping the docs migration table publishes.
+APPEARANCE_MIGRATION: dict[str, tuple[str, str]] = {
+    "default": ("theme", "default"),
+    "dark_theme": ("theme", "dark"),
+    "black_and_white": ("theme", "mono"),
+    "challenging_font": ("theme", "challenging_font"),
+    "colorblind_access": ("theme", "colorblind"),
+    "kanban_board": ("layout", "kanban_board"),
+    "broken_logos": ("layout", "broken_logos"),
+    "clickable_logos": ("layout", "clickable_logos"),
+}
+
+
+def migrate_appearance(
+    appearance: str,
+    *,
+    theme: str | None = None,
+    layout: str | None = None,
+) -> tuple[str | None, str | None]:
+    """Translate a legacy ``appearance`` stem into ``(theme, layout)``.
+
+    ``theme``/``layout`` are whatever the caller passed alongside it. A
+    disagreement raises rather than picking a winner silently — the caller
+    cannot tell from the result which of the two was applied.
+    """
+    try:
+        group, stem = APPEARANCE_MIGRATION[appearance]
+    except KeyError:
+        raise ValueError(
+            f"unknown appearance variant {appearance!r}. The appearance group "
+            f"was replaced by a shared theme + per-app layout; known legacy "
+            f"values are {', '.join(sorted(APPEARANCE_MIGRATION))}."
+        ) from None
+
+    passed = {"theme": theme, "layout": layout}[group]
+    if passed is not None and passed != stem:
+        raise ValueError(
+            f"appearance={appearance!r} maps to {group}={stem!r}, which "
+            f"conflicts with {group}={passed!r} passed alongside it. Drop the "
+            f"deprecated appearance argument."
+        )
+
+    warnings.warn(
+        f"appearance={appearance!r} is deprecated and will be removed; "
+        f"pass {group}={stem!r} instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+    return (stem, layout) if group == "theme" else (theme, stem)
+
+
 def list_variants(app_name: str, group: str) -> list[str]:
     """List Hydra variant yamls for a group (``theme``/``layout``/``content``).
 
@@ -57,7 +115,17 @@ def list_variants(app_name: str, group: str) -> list[str]:
 
     ``theme`` is a *shared* group (``config/apps/theme/``) applying to every
     app, so ``app_name`` is ignored for it; all other groups are per-app.
+
+    Raises ``ValueError`` for the removed ``appearance`` group: its directory
+    is gone, so the generic missing-dir path would answer ``["default"]`` and
+    a caller sampling variations would silently lose every non-default one.
     """
+    if group == "appearance":
+        raise ValueError(
+            "the appearance group was removed; list_variants(app, 'theme') "
+            "for the shared design-token themes and "
+            "list_variants(app, 'layout') for this app's structure variants."
+        )
     if group == "theme":
         group_dir = config_dir() / "apps" / "theme"
     else:
diff --git a/src/open_apps/mcp/server.py b/src/open_apps/mcp/server.py
index 2013ddfc..f7e4983e 100644
--- a/src/open_apps/mcp/server.py
+++ b/src/open_apps/mcp/server.py
@@ -91,11 +91,19 @@ async def reconfigure(
     content: str | None = None,
     seed: int | None = None,
     extras: dict | None = None,
+    appearance: str | None = None,
 ) -> str:
     """Swap theme/layout/content variant and seed (live) and re-seed app state.
 
     `theme` is the shared design-token theme and applies to every app;
     `layout` and `content` are per-app.
+
+    `appearance` is DEPRECATED: it names a stem from the removed `appearance`
+    group and is translated onto `theme`/`layout` (`dark_theme` -> `dark`,
+    `black_and_white` -> `mono`, `colorblind_access` -> `colorblind`,
+    `kanban_board`/`broken_logos`/`clickable_logos` -> the same `layout`).
+    Passing it alongside a conflicting `theme`/`layout` is an error. New
+    callers should use `theme`/`layout`; it will be removed in a later release.
     """
     await _require().reconfigure(
         theme=theme,
@@ -103,6 +111,7 @@ async def reconfigure(
         content=content,
         seed=seed,
         extras=extras,
+        appearance=appearance,
     )
     return "reconfigured"
 
diff --git a/src/open_apps/mcp/session.py b/src/open_apps/mcp/session.py
index 82f5770b..476ed881 100644
--- a/src/open_apps/mcp/session.py
+++ b/src/open_apps/mcp/session.py
@@ -213,7 +213,10 @@ async def reconfigure(
         content: str | None = None,
         seed: int | None = None,
         extras: dict | None = None,
+        appearance: str | None = None,
     ) -> None:
+        # ``appearance`` is the removed group, kept as a deprecated alias and
+        # translated onto theme/layout in AppServer.reconfigure.
         self._require_started()
         await asyncio.to_thread(
             self.appserver.reconfigure,
@@ -222,6 +225,7 @@ async def reconfigure(
             content=content,
             seed=seed,
             extras=extras,
+            appearance=appearance,
         )
 
     # -- action ------------------------------------------------------------
diff --git a/tests/test_mcp.py b/tests/test_mcp.py
index b0beb908..12ebb8b2 100644
--- a/tests/test_mcp.py
+++ b/tests/test_mcp.py
@@ -112,6 +112,81 @@ def test_list_variants_default_first(self):
         assert themes[0] == "default"
         assert "solarized" in themes
 
+    def test_list_variants_rejects_removed_appearance_group(self):
+        # Must not fall through to the missing-dir ``["default"]`` answer: a
+        # caller sampling variations would silently get a single-variant sweep.
+        with pytest.raises(ValueError, match="appearance group was removed"):
+            registry.list_variants("todo", "appearance")
+
+
+class TestAppearanceMigration:
+    """The removed ``appearance`` group, kept bindable for existing clients."""
+
+    def test_every_legacy_stem_maps_to_a_real_variant(self):
+        themes = set(registry.list_variants("todo", "theme"))
+        # Layouts are per-app and the legacy stems came from different apps
+        # (kanban_board from todo, the logo ones from start_page), so pool them.
+        layouts = {
+            p.stem
+            for group_dir in (config_dir() / "apps").glob("*/layout")
+            for p in group_dir.glob("*.yaml")
+        }
+        for stem, (group, target) in registry.APPEARANCE_MIGRATION.items():
+            pool = themes if group == "theme" else layouts
+            assert target in pool, f"appearance={stem} -> {group}={target}"
+
+    @pytest.mark.parametrize(
+        "appearance,expected",
+        [
+            ("default", ("default", None)),
+            ("dark_theme", ("dark", None)),
+            ("black_and_white", ("mono", None)),
+            ("challenging_font", ("challenging_font", None)),
+            ("colorblind_access", ("colorblind", None)),
+            ("kanban_board", (None, "kanban_board")),
+            ("broken_logos", (None, "broken_logos")),
+            ("clickable_logos", (None, "clickable_logos")),
+        ],
+    )
+    def test_maps_onto_theme_or_layout(self, appearance, expected):
+        with pytest.deprecated_call():
+            assert registry.migrate_appearance(appearance) == expected
+
+    def test_preserves_the_untouched_axis(self):
+        with pytest.deprecated_call():
+            assert registry.migrate_appearance("dark_theme", layout="kanban_board") == (
+                "dark",
+                "kanban_board",
+            )
+
+    def test_agreeing_value_is_not_a_conflict(self):
+        with pytest.deprecated_call():
+            assert registry.migrate_appearance("dark_theme", theme="dark") == (
+                "dark",
+                None,
+            )
+
+    def test_conflicting_value_raises(self):
+        with pytest.raises(ValueError, match="conflicts with"):
+            registry.migrate_appearance("dark_theme", theme="solarized")
+
+    def test_unknown_stem_raises_with_the_known_values(self):
+        with pytest.raises(ValueError, match="unknown appearance variant"):
+            registry.migrate_appearance("neon")
+
+    def test_reconfigure_tool_schema_still_binds_appearance(self):
+        # The published tool schema is the contract clients validate against:
+        # dropping the parameter fails their call before it reaches us.
+        from open_apps.mcp import server
+
+        tools = asyncio.run(server.mcp.list_tools())
+        schema = next(t for t in tools if t.name == "reconfigure").inputSchema
+        assert {"theme", "layout", "content", "seed", "extras"} <= set(
+            schema["properties"]
+        )
+        assert "appearance" in schema["properties"]
+        assert "appearance" not in schema.get("required", [])
+
 
 def _browsergym_calls(fn, *args):
     """Playwright calls BrowserGym's (sync) action function makes, demo off."""

From 6af0a1216c02c4163f365b5099ed97d66e2d1071 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Fri, 11 Sep 2026 12:56:27 -0400
Subject: [PATCH 17/23] [Improve] style tag safe parsing

---
 src/open_apps/theme.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index 32ceaec3..e479c001 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -149,7 +149,7 @@ def render_theme_css(theme: dict) -> str:
 
     import_url = (theme.get("import_url") or "").strip()
     # Avoid breaking out of the quoted @import string.
-    if any(c in import_url for c in ('"', "'", "\n", "\r")):
+    if any(c in import_url for c in ('"', "'", "\n", "\r", "<", ">")):
         import_url = ""
 
     import_rule = f'@import url("{import_url}");\n' if import_url else ""

From 20ba830d1e088d695334348903faf57c9b396a83 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Fri, 11 Sep 2026 14:56:20 -0400
Subject: [PATCH 18/23] [Docs] fix MCP paths & links

---
 docs/index.md                 |  8 ++++----
 site/index.html               |  8 ++++----
 site/index.md                 |  8 ++++----
 site/search/search_index.json |  2 +-
 site/sitemap.xml              | 10 +++++-----
 5 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 6860b2a5..0f7020f8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,7 +20,7 @@ Install the conda alternative [uv](https://docs.astral.sh/uv/getting-started/) a
    git clone https://github.com/facebookresearch/OpenApps.git
 ```
 
-Install dependencies:   
+Install dependencies:
 
 ```bash
    uv sync
@@ -31,7 +31,7 @@ For other installation options and online shop setup see [Installation](installa
 ### Run OpenApps
 
 ```bash
-uv run launch.py 
+uv run launch.py
 ```
 ![landing](images/landing.png)
 
@@ -192,7 +192,7 @@ Optional: to save screenshots of all apps with a specific variation for testing,
 
 ## Exposing OpenApps as an MCP server
 
-If you want an agent to interact with OpenApps using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) please see `src/mcp/README.md`.
+If you want an agent to interact with OpenApps using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) please see `src/open_apps/mcp/README.md`.
 
 ## Launch Agent
 
@@ -330,7 +330,7 @@ uv run -m pytest tests/
 
 ## Attribution
 
-Our apps are built on top of several excellent frameworks:  
+Our apps are built on top of several excellent frameworks:
 
 - FastHTML [framework](https://github.com/AnswerDotAI/fasthtml) and [examples](https://github.com/AnswerDotAI/fasthtml-example) which allowed us to build fully functional apps in Python, the language most familiar to AI researchers.
 - [Browser Gym](https://github.com/ServiceNow/BrowserGym/blob/main/LICENSE) and [AgentLab](https://github.com/ServiceNow/AgentLab/blob/main/LICENSE):
diff --git a/site/index.html b/site/index.html
index a016c159..4393d634 100644
--- a/site/index.html
+++ b/site/index.html
@@ -458,13 +458,13 @@ <h3 id="install">Install</h3>
 <div class="codehilite"><pre><span></span><code><span class="w">   </span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/facebookresearch/OpenApps.git
 </code></pre></div>
 
-<p>Install dependencies:   </p>
+<p>Install dependencies:</p>
 <div class="codehilite"><pre><span></span><code><span class="w">   </span>uv<span class="w"> </span>sync
 </code></pre></div>
 
 <p>For other installation options and online shop setup see <a href="installation/">Installation</a>.</p>
 <h3 id="run-openapps">Run OpenApps</h3>
-<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>
+<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py
 </code></pre></div>
 
 <p><img alt="landing" src="images/landing.png" /></p>
@@ -622,7 +622,7 @@ <h4 id="content">Content</h4>
 layer, route planning) that is neither.</p>
 <p>Optional: to save screenshots of all apps with a specific variation for testing, we offer <code>tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/</code> to make this easy.</p>
 <h2 id="exposing-openapps-as-an-mcp-server">Exposing OpenApps as an MCP server</h2>
-<p>If you want an agent to interact with OpenApps using <a href="https://modelcontextprotocol.io/docs/getting-started/intro">MCP</a> please see <code>src/mcp/README.md</code>.</p>
+<p>If you want an agent to interact with OpenApps using <a href="https://modelcontextprotocol.io/docs/getting-started/intro">MCP</a> please see <code>src/open_apps/mcp/README.md</code>.</p>
 <h2 id="launch-agent">Launch Agent</h2>
 <p>For agents to directly interact with apps, install: <code>playwright install chromium</code>.</p>
 <p>Launch an agent to perform a task of <em>adding a meeting with Dennis to the calendar</em>:</p>
@@ -730,7 +730,7 @@ <h2 id="testing">Testing</h2>
 </code></pre></div>
 
 <h2 id="attribution">Attribution</h2>
-<p>Our apps are built on top of several excellent frameworks:  </p>
+<p>Our apps are built on top of several excellent frameworks:</p>
 <ul>
 <li>FastHTML <a href="https://github.com/AnswerDotAI/fasthtml">framework</a> and <a href="https://github.com/AnswerDotAI/fasthtml-example">examples</a> which allowed us to build fully functional apps in Python, the language most familiar to AI researchers.</li>
 <li><a href="https://github.com/ServiceNow/BrowserGym/blob/main/LICENSE">Browser Gym</a> and <a href="https://github.com/ServiceNow/AgentLab/blob/main/LICENSE">AgentLab</a>:</li>
diff --git a/site/index.md b/site/index.md
index 6860b2a5..0f7020f8 100644
--- a/site/index.md
+++ b/site/index.md
@@ -20,7 +20,7 @@ Install the conda alternative [uv](https://docs.astral.sh/uv/getting-started/) a
    git clone https://github.com/facebookresearch/OpenApps.git
 ```
 
-Install dependencies:   
+Install dependencies:
 
 ```bash
    uv sync
@@ -31,7 +31,7 @@ For other installation options and online shop setup see [Installation](installa
 ### Run OpenApps
 
 ```bash
-uv run launch.py 
+uv run launch.py
 ```
 ![landing](images/landing.png)
 
@@ -192,7 +192,7 @@ Optional: to save screenshots of all apps with a specific variation for testing,
 
 ## Exposing OpenApps as an MCP server
 
-If you want an agent to interact with OpenApps using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) please see `src/mcp/README.md`.
+If you want an agent to interact with OpenApps using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) please see `src/open_apps/mcp/README.md`.
 
 ## Launch Agent
 
@@ -330,7 +330,7 @@ uv run -m pytest tests/
 
 ## Attribution
 
-Our apps are built on top of several excellent frameworks:  
+Our apps are built on top of several excellent frameworks:
 
 - FastHTML [framework](https://github.com/AnswerDotAI/fasthtml) and [examples](https://github.com/AnswerDotAI/fasthtml-example) which allowed us to build fully functional apps in Python, the language most familiar to AI researchers.
 - [Browser Gym](https://github.com/ServiceNow/BrowserGym/blob/main/LICENSE) and [AgentLab](https://github.com/ServiceNow/AgentLab/blob/main/LICENSE):
diff --git a/site/search/search_index.json b/site/search/search_index.json
index 5368475c..797c5338 100644
--- a/site/search/search_index.json
+++ b/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ . Theme challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist. Layout uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only. Migrating from appearance The appearance group these two replaced was removed. Overrides written against it no longer resolve; translate them as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. To reproduce the numbers in the paper rather than port to the new axes, check out the v1.0-paper tag \u2014 the last tree with appearance intact. Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy. Exposing OpenApps as an MCP server If you want an agent to interact with OpenApps using MCP please see src/mcp/README.md . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all . Running across goal variations Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded. Testing Run all tests via: uv run - m pytest tests / Attribution 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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ .","title":"App variations"},{"location":"#theme","text":"challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist.","title":"Theme"},{"location":"#layout","text":"uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only.","title":"Layout"},{"location":"#migrating-from-appearance","text":"The appearance group these two replaced was removed. Overrides written against it no longer resolve; translate them as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. To reproduce the numbers in the paper rather than port to the new axes, check out the v1.0-paper tag \u2014 the last tree with appearance intact.","title":"Migrating from appearance"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy.","title":"Content"},{"location":"#exposing-openapps-as-an-mcp-server","text":"If you want an agent to interact with OpenApps using MCP please see src/mcp/README.md .","title":"Exposing OpenApps as an MCP server"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all .","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#running-across-goal-variations","text":"Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded.","title":"Running across goal variations"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements. Running Evals on a Cluster (SLURM + vLLM + W&B) The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it. One-time cluster setup The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically. 1. Launch the persistent vLLM serve job Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it... 2. Submit the eval job scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True 3. Check results SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"agents/#running-evals-on-a-cluster-slurm-vllm-wb","text":"The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it.","title":"Running Evals on a Cluster (SLURM + vLLM + W&amp;B)"},{"location":"agents/#one-time-cluster-setup","text":"The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically.","title":"One-time cluster setup"},{"location":"agents/#1-launch-the-persistent-vllm-serve-job","text":"Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it...","title":"1. Launch the persistent vLLM serve job"},{"location":"agents/#2-submit-the-eval-job","text":"scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True","title":"2. Submit the eval job"},{"location":"agents/#3-check-results","text":"SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"3. Check results"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./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. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task . Goal Variations Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"},{"location":"tasks/#goal-variations","text":"Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Goal Variations"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ . Theme challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist. Layout uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only. Migrating from appearance The appearance group these two replaced was removed. Overrides written against it no longer resolve; translate them as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. To reproduce the numbers in the paper rather than port to the new axes, check out the v1.0-paper tag \u2014 the last tree with appearance intact. Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy. Exposing OpenApps as an MCP server If you want an agent to interact with OpenApps using MCP please see src/open_apps/mcp/README.md . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all . Running across goal variations Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded. Testing Run all tests via: uv run - m pytest tests / Attribution 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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ .","title":"App variations"},{"location":"#theme","text":"challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist.","title":"Theme"},{"location":"#layout","text":"uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only.","title":"Layout"},{"location":"#migrating-from-appearance","text":"The appearance group these two replaced was removed. Overrides written against it no longer resolve; translate them as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. To reproduce the numbers in the paper rather than port to the new axes, check out the v1.0-paper tag \u2014 the last tree with appearance intact.","title":"Migrating from appearance"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy.","title":"Content"},{"location":"#exposing-openapps-as-an-mcp-server","text":"If you want an agent to interact with OpenApps using MCP please see src/open_apps/mcp/README.md .","title":"Exposing OpenApps as an MCP server"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all .","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#running-across-goal-variations","text":"Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded.","title":"Running across goal variations"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements. Running Evals on a Cluster (SLURM + vLLM + W&B) The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it. One-time cluster setup The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically. 1. Launch the persistent vLLM serve job Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it... 2. Submit the eval job scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True 3. Check results SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"agents/#running-evals-on-a-cluster-slurm-vllm-wb","text":"The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it.","title":"Running Evals on a Cluster (SLURM + vLLM + W&amp;B)"},{"location":"agents/#one-time-cluster-setup","text":"The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically.","title":"One-time cluster setup"},{"location":"agents/#1-launch-the-persistent-vllm-serve-job","text":"Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it...","title":"1. Launch the persistent vLLM serve job"},{"location":"agents/#2-submit-the-eval-job","text":"scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True","title":"2. Submit the eval job"},{"location":"agents/#3-check-results","text":"SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"3. Check results"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./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. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task . Goal Variations Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"},{"location":"tasks/#goal-variations","text":"Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Goal Variations"}]}
\ No newline at end of file
diff --git a/site/sitemap.xml b/site/sitemap.xml
index fa3ef46c..37df568e 100644
--- a/site/sitemap.xml
+++ b/site/sitemap.xml
@@ -2,22 +2,22 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/</loc>
-         <lastmod>2026-09-09</lastmod>
+         <lastmod>2026-09-11</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/Intro%20to%20UI%20Agents/</loc>
-         <lastmod>2026-09-09</lastmod>
+         <lastmod>2026-09-11</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/agents/</loc>
-         <lastmod>2026-09-09</lastmod>
+         <lastmod>2026-09-11</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/installation/</loc>
-         <lastmod>2026-09-09</lastmod>
+         <lastmod>2026-09-11</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/tasks/</loc>
-         <lastmod>2026-09-09</lastmod>
+         <lastmod>2026-09-11</lastmod>
     </url>
 </urlset>
\ No newline at end of file

From dcaf26642dc63b9a9a412db848380ecd3ad7a941 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Fri, 11 Sep 2026 15:30:43 -0400
Subject: [PATCH 19/23] [Fix] Restore load_theme's fallback for an unknown
 theme name

39851d4 swapped the `path.exists()` fallback for a character check. The
character check is the right guard against a name escaping _THEME_DIR, but
it is not a substitute: a well-formed name that simply has no yaml
(`apps.todo.theme=does_not_exist`) went straight to read_text() and raised
FileNotFoundError, against the docstring's promise to degrade gracefully.
Keep both guards.

Test plan: tests/test_theme.py 28 passed (2 were failing on the branch:
TestLoadTheme::test_unknown_theme_falls_back_to_default and
TestResolveTheme::test_unknown_per_app_name_degrades_to_default).
---
 src/open_apps/theme.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
index 4afdf355..3aa14c8c 100644
--- a/src/open_apps/theme.py
+++ b/src/open_apps/theme.py
@@ -79,9 +79,14 @@ def load_theme(name: str) -> dict:
     ``assets``. Falls back to the default theme when ``name`` is unknown so
     a bad override degrades gracefully instead of raising.
     """
+    # Two separate guards, both needed: the character check keeps a name from
+    # escaping _THEME_DIR (``../``, absolute paths), the existence check keeps
+    # a merely-unknown-but-well-formed name from raising FileNotFoundError.
     if not name or any(not (char.isalnum() or char in "-_") for char in name):
         name = _DEFAULT_THEME
     path = _THEME_DIR / f"{name}.yaml"
+    if not path.exists():
+        path = _THEME_DIR / f"{_DEFAULT_THEME}.yaml"
     data = yaml.safe_load(path.read_text()) or {}
     data.setdefault("name", name)
     data.setdefault("tokens", {})

From c296f1511103706a4049d562930275e20f93cbe8 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Fri, 11 Sep 2026 15:30:43 -0400
Subject: [PATCH 20/23] [Test] Guard the raw Hydra override strings in the
 variation grids

`parallel_tasks.app_variations` and save_screenshots' variation grid hold
override strings as *data*. A renamed config group there raises when a
sweep launches, not at import, so nothing catches it until an allocation
is already running -- exactly how the appearance -> theme/layout rename
could rot silently. Compose each entry for real.

Confirmed the guard bites: reverting one entry to
`apps/todo/appearance=dark_theme` fails with
"app_variations entry ['apps/todo/appearance=dark_theme'] no longer
composes: Could not override 'apps/todo/appearance'."

Test plan: uv run -m pytest tests/ -> 768 passed, 7 skipped.
---
 tests/test_parallel_tasks.py | 41 ++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/tests/test_parallel_tasks.py b/tests/test_parallel_tasks.py
index 2d182247..234e35ab 100644
--- a/tests/test_parallel_tasks.py
+++ b/tests/test_parallel_tasks.py
@@ -126,3 +126,44 @@ def test_create_configs_count_all_longer_horizon(monkeypatch):
     configs = cfg.create_configs(_fake_default_config(task_names))
 
     assert len(configs) == len(task_names) * len(app_variations)
+
+
+class TestVariationOverridesCompose:
+    """The variation grids are raw Hydra override strings -- data, not code.
+
+    A renamed config group here raises at *launch* time, not import time, so
+    nothing catches it until a sweep is already holding an allocation. These
+    tests compose for real (no ``_stub_compose``), which is slower but is the
+    only thing that actually exercises the strings.
+    """
+
+    @staticmethod
+    def _compose(overrides: list[str]) -> None:
+        from hydra import compose, initialize_config_dir
+        from hydra.core.global_hydra import GlobalHydra
+
+        GlobalHydra.instance().clear()
+        with initialize_config_dir(config_dir=str(config_dir()), version_base=None):
+            compose(config_name="config_parallel_tasks", overrides=overrides)
+
+    def test_app_variations_in_config_parallel_tasks(self):
+        raw = OmegaConf.load(config_dir() / "config_parallel_tasks.yaml")
+        variations = OmegaConf.to_container(raw.parallel_tasks.app_variations)
+        assert variations, "no app_variations to check"
+        for overrides in variations:
+            try:
+                self._compose(list(overrides))
+            except Exception as e:
+                pytest.fail(f"app_variations entry {overrides} no longer composes: {e}")
+
+    def test_save_screenshots_variation_grid(self):
+        """Same guard for the visual-regression grid in save_screenshots.py."""
+        from tests.save_screenshots import build_variation_overrides
+
+        grid = build_variation_overrides(include_onlineshop=False)
+        assert grid, "no screenshot variations to check"
+        for name, overrides in grid.items():
+            try:
+                self._compose(list(overrides))
+            except Exception as e:
+                pytest.fail(f"screenshot variation {name!r} no longer composes: {e}")

From ef6243c4a03e4284e730b469193308a11a149898 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Wed, 16 Sep 2026 15:17:10 -0400
Subject: [PATCH 21/23] [Docs] Point the appearance migration at the v1.0-paper
 tag

The appearance group is gone from config and rendering, so an override
written against it is a Hydra composition error rather than a silent
no-op -- say so, and make the paper-reproduction path explicit: theme +
layout do not reproduce the paper's grid pixel-for-pixel, v1.0-paper
does. Also document the one surviving exception, the MCP reconfigure
shim, which callers cannot discover from the config tree.

Rebuilds site/ from docs/.
---
 docs/index.md                 |  30 +++++-
 site/agents.md                | 190 ++++++++++++++++++++++++++++++++++
 site/index.html               |  26 ++++-
 site/index.md                 |  30 +++++-
 site/installation.md          |  31 ++++++
 site/search/search_index.json |   2 +-
 site/sitemap.xml              |  10 +-
 site/sitemap.xml.gz           | Bin 248 -> 248 bytes
 site/tasks.md                 |  97 +++++++++++++++++
 9 files changed, 395 insertions(+), 21 deletions(-)
 create mode 100644 site/agents.md
 create mode 100644 site/installation.md
 create mode 100644 site/tasks.md

diff --git a/docs/index.md b/docs/index.md
index 0f7020f8..31035a2c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -125,8 +125,10 @@ Available layouts: `todo` has `default` and `kanban_board`; `start_page` has
 
 #### Migrating from `appearance`
 
-The `appearance` group these two replaced was removed. Overrides written
-against it no longer resolve; translate them as:
+The `appearance` group these two replaced was removed: there are no
+`config/apps/<app>/appearance/` directories and no app renders from one.
+`apps/<app>/appearance=...` is a Hydra composition error, not a silent
+no-op. Translate overrides as:
 
 | Old override | New override |
 | --- | --- |
@@ -146,9 +148,27 @@ needed collapse to one `apps/theme=dark`. Two renderings shift slightly:
 the rest did not), and `colorblind` is now available to all apps rather than
 the code editor alone.
 
-To reproduce the numbers in [the paper](https://arxiv.org/abs/2511.20766)
-rather than port to the new axes, check out the `v1.0-paper` tag — the last
-tree with `appearance` intact.
+##### Reproducing the paper
+
+The paper's variation grid is indexed by `appearance` stem names, and the two
+axes above do not reproduce it pixel-for-pixel — see the shifts noted just
+above. **To reproduce the numbers in
+[the paper](https://arxiv.org/abs/2511.20766), use the `v1.0-paper` tag**, the
+last tree with `appearance` intact:
+
+```bash
+git checkout v1.0-paper
+uv run launch.py apps/todo/appearance=dark_theme
+```
+
+Theme and layout are the supported axes going forward; `v1.0-paper` is frozen
+and gets no fixes.
+
+One exception to the removal: the MCP `reconfigure` tool still accepts an
+`appearance=` argument, translates it onto `theme`/`layout` per the table
+above, and raises a `DeprecationWarning`. It exists so existing MCP clients
+keep working for one release and will be removed — see
+[`src/open_apps/mcp/README.md`](https://github.com/facebookresearch/OpenApps/blob/main/src/open_apps/mcp/README.md).
 
 #### Content
 
diff --git a/site/agents.md b/site/agents.md
new file mode 100644
index 00000000..bc6e8a4d
--- /dev/null
+++ b/site/agents.md
@@ -0,0 +1,190 @@
+# Agent Configuration & Setup Guide
+
+## Quickstart: Getting Your Agent to Run
+
+### Prerequisites
+
+To use GPT-5-1 to complete tasks, set your OpenAI API key:
+
+```bash
+export OPENAI_API_KEY=YOUR_KEY
+```
+
+Alternatively, edit the corresponding line in `config/agent/GPT-5-1.yaml`.
+
+### Supported Clients
+
+We support multiple client types:
+
+- vLLM
+- OpenAI 
+- Azure
+- AWS
+
+To use a different client, change the `client_type` argument in your configuration. Check out `/src/open_apps/agent/vLLM_agent.py` Line 49 and following for specifics about how these clients are called internally.
+
+### Running Your Agent
+
+```bash
+uv run launch_agent.py agent=GPT-4o
+```
+To run a local model with [vLLM](https://docs.vllm.ai/en/latest/), 
+
+1. Launch your local vLLM model: `vllm serve [MODEL_NAME]`. VLLM will tell you your hostname.
+
+2. Launch your agent
+
+```bash
+uv run launch_agent.py agent=AGENT_CONFIG agent.hostname=VLLM_HOSTNAME
+```
+
+## Configuring Your Policy
+
+Our agent policies are built on top of [AgentLab](https://github.com/ServiceNow/AgentLab). Our setup enables automatic configuration of your prompt with config flags.
+Here are some key flags you can configure in your agent's YAML file:
+
+**Observation Flags:**
+
+- `use_axtree`: Enable AXTree observation (accessibility tree)
+- `use_screenshot`: Enable screenshot observation
+- `use_som`: Add visual marks to screenshots for element identification
+- `extract_coords`: Include element coordinates in observations
+
+**History & Memory Flags:**
+
+- `use_history`: Enable action/thought history tracking
+- `use_action_history`: Track previous actions taken by the agent
+- `use_think_history`: Track previous thoughts/reasoning steps
+
+**Reasoning & Examples Flags:**
+
+- `use_thinking`: Enable chain-of-thought reasoning before actions
+- `use_concrete_example`: Include concrete examples in the prompt
+- `use_abstract_example`: Include abstract reasoning examples in the prompt
+
+**Custom Prompts:**
+
+- `prompt_txt.system_prompt`: Override the default system prompt
+- `prompt_txt.action_prompt`: Define custom action instructions
+- `prompt_txt.think_prompt`: Define custom thinking/reasoning instructions
+
+For the complete set of configuration options, see `config/agent/default.yaml`.
+
+
+## Creating Your Own Agent
+
+If AgentLab's capabilities don't meet your needs, you can create a custom agent.
+
+1. Navigate to `src/open_apps/agent/`
+2. Copy and modify the following files:
+
+      - `vLLM_agent.py`
+      - `vLLM_prompt.py`
+
+This allows you to build rich, custom agent implementations tailored to your specific requirements.
+
+## Running Evals on a Cluster (SLURM + vLLM + W&B)
+
+The workflow consists of two jobs:
+
+1. A persistent **vLLM GPU job** that serves the model on `:8000`.
+2. An **eval CPU job** (`sbatch scripts/conduct_slurm.sh`) that auto-discovers the vLLM node and runs the worker pool against it.
+
+### One-time cluster setup
+
+The repo needs to live on shared storage (e.g. `/example/dir/$USER`
+or `/storage/home/$USER`). On a login node:
+
+```bash
+# Bring the repo over. Use rsync if you have uncommitted local changes (e.g.
+# scripts/conduct.sh) that aren't pushed yet:
+rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/$USER/OpenApps/
+# ...or clone it fresh:
+#   git clone <repo-url> /example/dir/$USER/OpenApps
+
+cd /example/dir/$USER/OpenApps
+
+# Python env
+curl -LsSf https://astral.sh/uv/install.sh | sh   # install uv if needed
+uv sync
+
+# Headless browser
+uv run playwright install chromium
+uv run playwright install-deps chromium   # system deps (may need sudo/module)
+
+# App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg)
+./setup.sh
+
+# Secrets — do NOT commit this file
+cat > .env <<'EOF'
+OPENAI_API_KEY=sk-...
+WANDB_BASE_URL=...
+WANDB_API_KEY=...
+EOF
+```
+
+`launch_agent.py` calls `load_dotenv()`, so `.env` is picked up automatically.
+
+### 1. Launch the persistent vLLM serve job
+
+Give it a generous `--time` so it isn't killed mid-eval. For example, an
+interactive allocation:
+
+```bash
+srun --account=example_account --qos=example_qos --partition=example_partition \ --gpus-per-node=1 --time=1440 --pty bash
+# then, on the GPU node:
+vllm serve google/gemma-4-E2B-it --host 0.0.0.0 --port 8000
+```
+
+Confirm it's healthy from its own node:
+
+```bash
+srun --overlap --jobid=<vllm-job> --pty curl -s http://localhost:8000/v1/models
+# expect: ...google/gemma-4-E2B-it...
+```
+
+### 2. Submit the eval job
+
+`scripts/conduct_slurm.sh` requests a CPU allocation, finds the vLLM node, and
+runs `scripts/conduct.sh` pointed at it with `use_wandb=True`:
+
+```bash
+# smoke test (1 run)
+AGENTS=gemma-4-e2b-it COUNT=1 sbatch scripts/conduct_slurm.sh
+
+# larger sweep
+AGENTS="gemma-4-e2b-it" COUNT=20 MAX_PARALLEL=4 sbatch scripts/conduct_slurm.sh
+```
+
+**Discovery:** the wrapper lists your running jobs (`squeue --me`), expands their
+nodelists, excludes the eval node itself, and probes each `http://<node>:8000/v1/models`,
+selecting the first one serving `google/gemma-4-E2B-it`. It probes by *serving the
+model*, so it doesn't matter how the vLLM job was started (e.g. a `bash`-named
+`srun --pty`).
+
+**Override:** skip discovery by pinning the node:
+
+```bash
+VLLM_HOST=example_host AGENTS=gemma-4-e2b-it COUNT=1 sbatch scripts/conduct_slurm.sh
+```
+
+Other env overrides: `VLLM_MODEL`, `VLLM_PORT`, and `WANDB_MODE` (set
+`WANDB_MODE=offline` to skip online logging). Extra CLI args are forwarded
+verbatim to `launch_agent.py` as Hydra overrides.
+
+**Fallback if compute→compute `:8000` is firewalled:** run the eval inside the
+vLLM job's own allocation and talk to it over localhost:
+
+```bash
+srun --overlap --jobid=<vllm-job> \
+  env AGENTS=gemma-4-e2b-it COUNT=1 VLLM_HOST=localhost \
+  ./scripts/conduct.sh agent.hostname=localhost use_wandb=True
+```
+
+### 3. Check results
+
+- SLURM log: `slurm-<jobid>.out` — confirm discovery selected the vLLM node and
+  there are no "Connection error" messages.
+- Per-run logs: `log_outputs/<stamp>/run-*.log` — confirm an action is produced.
+- W&B: a run should appear in `open_apps_${USER}` (i.e. `open_apps_aaronsmulktis`)
+  with the expected `group`/`job_type` and a logged `web_app_url`.
diff --git a/site/index.html b/site/index.html
index 4393d634..4fb16694 100644
--- a/site/index.html
+++ b/site/index.html
@@ -538,8 +538,10 @@ <h4 id="layout">Layout</h4>
 <code>default</code>, <code>broken_logos</code> (icons detached from their tiles) and
 <code>clickable_logos</code>; the other apps currently have <code>default</code> only.</p>
 <h4 id="migrating-from-appearance">Migrating from <code>appearance</code></h4>
-<p>The <code>appearance</code> group these two replaced was removed. Overrides written
-against it no longer resolve; translate them as:</p>
+<p>The <code>appearance</code> group these two replaced was removed: there are no
+<code>config/apps/&lt;app&gt;/appearance/</code> directories and no app renders from one.
+<code>apps/&lt;app&gt;/appearance=...</code> is a Hydra composition error, not a silent
+no-op. Translate overrides as:</p>
 <div class="table-wrapper"><table>
 <thead>
 <tr>
@@ -588,9 +590,23 @@ <h4 id="migrating-from-appearance">Migrating from <code>appearance</code></h4>
 <code>black_and_white</code> variants disagreed on polarity (calendar inverted the page,
 the rest did not), and <code>colorblind</code> is now available to all apps rather than
 the code editor alone.</p>
-<p>To reproduce the numbers in <a href="https://arxiv.org/abs/2511.20766">the paper</a>
-rather than port to the new axes, check out the <code>v1.0-paper</code> tag — the last
-tree with <code>appearance</code> intact.</p>
+<h5 id="reproducing-the-paper">Reproducing the paper</h5>
+<p>The paper's variation grid is indexed by <code>appearance</code> stem names, and the two
+axes above do not reproduce it pixel-for-pixel — see the shifts noted just
+above. <strong>To reproduce the numbers in
+<a href="https://arxiv.org/abs/2511.20766">the paper</a>, use the <code>v1.0-paper</code> tag</strong>, the
+last tree with <code>appearance</code> intact:</p>
+<div class="codehilite"><pre><span></span><code>git<span class="w"> </span>checkout<span class="w"> </span>v1.0-paper
+uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/todo/appearance<span class="o">=</span>dark_theme
+</code></pre></div>
+
+<p>Theme and layout are the supported axes going forward; <code>v1.0-paper</code> is frozen
+and gets no fixes.</p>
+<p>One exception to the removal: the MCP <code>reconfigure</code> tool still accepts an
+<code>appearance=</code> argument, translates it onto <code>theme</code>/<code>layout</code> per the table
+above, and raises a <code>DeprecationWarning</code>. It exists so existing MCP clients
+keep working for one release and will be removed — see
+<a href="https://github.com/facebookresearch/OpenApps/blob/main/src/open_apps/mcp/README.md"><code>src/open_apps/mcp/README.md</code></a>.</p>
 <h4 id="content">Content</h4>
 <div class="tabbed-set" data-tabs="2:3"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><label for="__tabbed_2_1">german</label><div class="tabbed-content">
 <div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">CONTENT</span><span class="o">=</span>german
diff --git a/site/index.md b/site/index.md
index 0f7020f8..31035a2c 100644
--- a/site/index.md
+++ b/site/index.md
@@ -125,8 +125,10 @@ Available layouts: `todo` has `default` and `kanban_board`; `start_page` has
 
 #### Migrating from `appearance`
 
-The `appearance` group these two replaced was removed. Overrides written
-against it no longer resolve; translate them as:
+The `appearance` group these two replaced was removed: there are no
+`config/apps/<app>/appearance/` directories and no app renders from one.
+`apps/<app>/appearance=...` is a Hydra composition error, not a silent
+no-op. Translate overrides as:
 
 | Old override | New override |
 | --- | --- |
@@ -146,9 +148,27 @@ needed collapse to one `apps/theme=dark`. Two renderings shift slightly:
 the rest did not), and `colorblind` is now available to all apps rather than
 the code editor alone.
 
-To reproduce the numbers in [the paper](https://arxiv.org/abs/2511.20766)
-rather than port to the new axes, check out the `v1.0-paper` tag — the last
-tree with `appearance` intact.
+##### Reproducing the paper
+
+The paper's variation grid is indexed by `appearance` stem names, and the two
+axes above do not reproduce it pixel-for-pixel — see the shifts noted just
+above. **To reproduce the numbers in
+[the paper](https://arxiv.org/abs/2511.20766), use the `v1.0-paper` tag**, the
+last tree with `appearance` intact:
+
+```bash
+git checkout v1.0-paper
+uv run launch.py apps/todo/appearance=dark_theme
+```
+
+Theme and layout are the supported axes going forward; `v1.0-paper` is frozen
+and gets no fixes.
+
+One exception to the removal: the MCP `reconfigure` tool still accepts an
+`appearance=` argument, translates it onto `theme`/`layout` per the table
+above, and raises a `DeprecationWarning`. It exists so existing MCP clients
+keep working for one release and will be removed — see
+[`src/open_apps/mcp/README.md`](https://github.com/facebookresearch/OpenApps/blob/main/src/open_apps/mcp/README.md).
 
 #### Content
 
diff --git a/site/installation.md b/site/installation.md
new file mode 100644
index 00000000..9ee19504
--- /dev/null
+++ b/site/installation.md
@@ -0,0 +1,31 @@
+
+- Pre-requisite: install uv (a much faster pip): `pip install uv` (or from [source](https://docs.astral.sh/uv/getting-started/installation/))
+<!-- - [If using Conda] Create a fresh venv: `uv venv --python "$(which python)"` -->
+
+0) Clone [repo](https://github.com/facebookresearch/OpenApps)
+
+1) Install packages: `uv sync`
+
+2) Activate environment: `source .venv/bin/activate`
+
+3) Install `playwright install chromium`
+
+/// details | Optionally install for onlineshop (off by default)
+
+`Onlineshop java + spacy configuration`
+
+4) Prepare Java, Webshop data and spacy model: `chmod +x setup.sh` and `./setup.sh` for **Linux X64** or **Mac ARM64** systems
+
+5) Designate Java path: `source setup_javapath.sh` for **Linux X64** or **Mac ARM64** systems
+
+6) Check `java -version` gives you `java version "21.0.1"`
+
+7) Build search engine indexes: `chmod +x setup_pyserini.sh` and `./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.**
+
+Finally, launch with
+```
+uv run launch.py apps.onlineshop.enable=True
+```
+///
diff --git a/site/search/search_index.json b/site/search/search_index.json
index 797c5338..17afa048 100644
--- a/site/search/search_index.json
+++ b/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ . Theme challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist. Layout uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only. Migrating from appearance The appearance group these two replaced was removed. Overrides written against it no longer resolve; translate them as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. To reproduce the numbers in the paper rather than port to the new axes, check out the v1.0-paper tag \u2014 the last tree with appearance intact. Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy. Exposing OpenApps as an MCP server If you want an agent to interact with OpenApps using MCP please see src/open_apps/mcp/README.md . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all . Running across goal variations Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded. Testing Run all tests via: uv run - m pytest tests / Attribution 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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ .","title":"App variations"},{"location":"#theme","text":"challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist.","title":"Theme"},{"location":"#layout","text":"uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only.","title":"Layout"},{"location":"#migrating-from-appearance","text":"The appearance group these two replaced was removed. Overrides written against it no longer resolve; translate them as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. To reproduce the numbers in the paper rather than port to the new axes, check out the v1.0-paper tag \u2014 the last tree with appearance intact.","title":"Migrating from appearance"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy.","title":"Content"},{"location":"#exposing-openapps-as-an-mcp-server","text":"If you want an agent to interact with OpenApps using MCP please see src/open_apps/mcp/README.md .","title":"Exposing OpenApps as an MCP server"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all .","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#running-across-goal-variations","text":"Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded.","title":"Running across goal variations"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements. Running Evals on a Cluster (SLURM + vLLM + W&B) The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it. One-time cluster setup The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically. 1. Launch the persistent vLLM serve job Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it... 2. Submit the eval job scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True 3. Check results SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"agents/#running-evals-on-a-cluster-slurm-vllm-wb","text":"The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it.","title":"Running Evals on a Cluster (SLURM + vLLM + W&amp;B)"},{"location":"agents/#one-time-cluster-setup","text":"The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically.","title":"One-time cluster setup"},{"location":"agents/#1-launch-the-persistent-vllm-serve-job","text":"Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it...","title":"1. Launch the persistent vLLM serve job"},{"location":"agents/#2-submit-the-eval-job","text":"scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True","title":"2. Submit the eval job"},{"location":"agents/#3-check-results","text":"SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"3. Check results"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./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. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task . Goal Variations Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"},{"location":"tasks/#goal-variations","text":"Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Goal Variations"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ . Theme challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist. Layout uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only. Migrating from appearance The appearance group these two replaced was removed: there are no config/apps/<app>/appearance/ directories and no app renders from one. apps/<app>/appearance=... is a Hydra composition error, not a silent no-op. Translate overrides as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. Reproducing the paper The paper's variation grid is indexed by appearance stem names, and the two axes above do not reproduce it pixel-for-pixel \u2014 see the shifts noted just above. To reproduce the numbers in the paper , use the v1.0-paper tag , the last tree with appearance intact: git checkout v1.0-paper uv run launch.py apps/todo/appearance = dark_theme Theme and layout are the supported axes going forward; v1.0-paper is frozen and gets no fixes. One exception to the removal: the MCP reconfigure tool still accepts an appearance= argument, translates it onto theme / layout per the table above, and raises a DeprecationWarning . It exists so existing MCP clients keep working for one release and will be removed \u2014 see src/open_apps/mcp/README.md . Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy. Exposing OpenApps as an MCP server If you want an agent to interact with OpenApps using MCP please see src/open_apps/mcp/README.md . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all . Running across goal variations Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded. Testing Run all tests via: uv run - m pytest tests / Attribution 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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ .","title":"App variations"},{"location":"#theme","text":"challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist.","title":"Theme"},{"location":"#layout","text":"uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only.","title":"Layout"},{"location":"#migrating-from-appearance","text":"The appearance group these two replaced was removed: there are no config/apps/<app>/appearance/ directories and no app renders from one. apps/<app>/appearance=... is a Hydra composition error, not a silent no-op. Translate overrides as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone.","title":"Migrating from appearance"},{"location":"#reproducing-the-paper","text":"The paper's variation grid is indexed by appearance stem names, and the two axes above do not reproduce it pixel-for-pixel \u2014 see the shifts noted just above. To reproduce the numbers in the paper , use the v1.0-paper tag , the last tree with appearance intact: git checkout v1.0-paper uv run launch.py apps/todo/appearance = dark_theme Theme and layout are the supported axes going forward; v1.0-paper is frozen and gets no fixes. One exception to the removal: the MCP reconfigure tool still accepts an appearance= argument, translates it onto theme / layout per the table above, and raises a DeprecationWarning . It exists so existing MCP clients keep working for one release and will be removed \u2014 see src/open_apps/mcp/README.md .","title":"Reproducing the paper"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy.","title":"Content"},{"location":"#exposing-openapps-as-an-mcp-server","text":"If you want an agent to interact with OpenApps using MCP please see src/open_apps/mcp/README.md .","title":"Exposing OpenApps as an MCP server"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis 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, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all .","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#running-across-goal-variations","text":"Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded.","title":"Running across goal variations"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"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 : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements. Running Evals on a Cluster (SLURM + vLLM + W&B) The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it. One-time cluster setup The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically. 1. Launch the persistent vLLM serve job Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it... 2. Submit the eval job scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True 3. Check results SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"agents/#running-evals-on-a-cluster-slurm-vllm-wb","text":"The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it.","title":"Running Evals on a Cluster (SLURM + vLLM + W&amp;B)"},{"location":"agents/#one-time-cluster-setup","text":"The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically.","title":"One-time cluster setup"},{"location":"agents/#1-launch-the-persistent-vllm-serve-job","text":"Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it...","title":"1. Launch the persistent vLLM serve job"},{"location":"agents/#2-submit-the-eval-job","text":"scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True","title":"2. Submit the eval job"},{"location":"agents/#3-check-results","text":"SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"3. Check results"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./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. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task . Goal Variations Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"},{"location":"tasks/#goal-variations","text":"Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Goal Variations"}]}
\ No newline at end of file
diff --git a/site/sitemap.xml b/site/sitemap.xml
index 37df568e..809e242b 100644
--- a/site/sitemap.xml
+++ b/site/sitemap.xml
@@ -2,22 +2,22 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/</loc>
-         <lastmod>2026-09-11</lastmod>
+         <lastmod>2026-09-16</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/Intro%20to%20UI%20Agents/</loc>
-         <lastmod>2026-09-11</lastmod>
+         <lastmod>2026-09-16</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/agents/</loc>
-         <lastmod>2026-09-11</lastmod>
+         <lastmod>2026-09-16</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/installation/</loc>
-         <lastmod>2026-09-11</lastmod>
+         <lastmod>2026-09-16</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/tasks/</loc>
-         <lastmod>2026-09-11</lastmod>
+         <lastmod>2026-09-16</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/site/sitemap.xml.gz b/site/sitemap.xml.gz
index 0378dc75ca2e7d109f4848965ed794d981da7486..5b5a5521cb6ae6cb91d0a589f2baf5ccfce13965 100644
GIT binary patch
literal 248
zcmV<U00;jciwFn++^K2;|8r?{Wo=<_E_iKh0L@ZOZ^AGPz4I%oNE{o79?+QDATE<Q
z?J|Bq2woeJCQ)qG{rshXrrkL(AN(czy(i1<_Ivcz7iMxXbYdlys4&=ga-r|U;p44-
z5nH`zFWD1vRfYp~Vqi|M0Mj%{a*U%%BxCM@>`)4VdlQu02)(F^%>cLTYORk}&nQ%2
zK8?j=jOUDmCfh;wj)%)px(M$H!!9L)7Uqq=0ET#sC*7!KU8_yKT9=V~@5Ttfl#i0{
y1LwGG6wmIkFK*Xk;3umx|3HHa#KwEW<$Ip1gbke^IL0-U57$3EKjxDW0{{SwHg=2v

literal 248
zcmV<U00;jciwFpSp`dC4|8r?{Wo=<_E_iKh0L@atZo)7Oz4H}Sq#a2@4+y3<h|45S
zyTAv8khKwM9K~kc=g$R%cIUvX$WE;1_nsm*o1Y<8-@agg)QW}FqVmbXDWt9yhyBNV
zB{pW(TuMYw6@wGDq9@AlN{!<vF_0f@MhT@;=z4yjx;K@UYhh*;$3$?uU89NM%*29B
z^JSes0-TFSZ;R_?7pT7+WdQY=ecI-Xs!`L#UjmCXz{%9QUe5KJ4@2&~o1%J1J}bUU
yRN$@FG^N9i)3)=8UhK;L0}mk~*%&SH_Po{!Sv)`S8P~!aZhis6WtH<00{{RgDtZwB

diff --git a/site/tasks.md b/site/tasks.md
new file mode 100644
index 00000000..ccd20b49
--- /dev/null
+++ b/site/tasks.md
@@ -0,0 +1,97 @@
+
+To ask GPT-4o to mark water plants as done in your todo list:
+
+```shell
+# export OPENAI_API_KEY=""
+uv run launch_agent.py agent=GPT-5-1 task_name=mark_water_plants_as_done
+```
+
+`task_name` specifies the task. Tasks are defined in `config/tasks/all_tasks.yaml`. For example,
+
+```yaml
+mark_water_plants_as_done:
+  # Indicates class where reward logic is defined
+  _target_: open_apps.tasks.tasks.MarkToDoDoneTask
+  goal: Mark 'Water plants' as done in my todo list.
+  todo_name: "Water plants"
+```
+
+## Adding New Tasks
+
+To add a new task using an existing reward function, simply add a new entry to the `config/tasks/all_tasks.yaml`:
+
+```yaml
+add_my_special_item_to_todo:
+  # _target_ defines the class containing the task reward logic
+  _target_: open_apps.tasks.tasks.AddToDoTask
+  goal: ENTER YOUR GOAL
+  todo_name: ENTER TITLE of TODO
+  is_done: false
+```
+
+You can select this new task by specifying the `task_name=add_my_special_item_todo`.
+
+
+### New custom tasks
+
+To add a custom task with its own reward logic, create a new class in `src/open_apps/tasks/tasks.py`.
+
+Your new class should inherit `Task` and implement a reward function, `check_if_task_is_complete`, indicating whether the task is complete:
+
+
+```python
+@dataclass
+class MyCustomTask(Task):
+	def check_if_task_is_complete(
+		self, 
+		initiate_state: dict, 
+		current_state: dict) -> bool:
+		# we handle providing the initial and current states for you!
+		# write your custom reward logic
+		...
+```
+
+Then create a corresponding entry in `config/tasks/all_tasks.yaml`:
+
+```yaml
+my_custom_task:
+	_target_: open_apps.tasks.tasks.MyCustomTask
+	goal: ENTER
+```
+
+Finally, ask your agent to solve the task by specifying `task_name=my_custom_task`.
+
+## Goal Variations
+
+Tasks come with **goal variations**: the same task with its goal reworded in a
+different style, so you can study how robust an agent is to phrasing. There are
+three styles — `casual`, `formal`, and `unrelated_context` (the instruction
+embedded in unrelated chit-chat) — with 9 variations per task.
+
+Tasks are split across two files, both composed into `all_tasks.yaml`:
+
+* `config/tasks/original_tasks.yaml` — the base tasks.
+* `config/tasks/user_goal_variations.yaml` — the variations, keyed
+  `<original_task>__<style>_<n>` (e.g. `mark_water_plants_as_done__casual_2`).
+
+Every variation copies its original's fields verbatim — only the `goal` is
+reworded, and an optional `goal_style` field records the style — so the reward
+logic is identical to the base task:
+
+```yaml
+mark_water_plants_as_done__casual_2:
+  _target_: open_apps.tasks.tasks.MarkToDoDoneTask
+  goal: can you check off 'Water plants' in my to-do list?
+  todo_name: "Water plants"
+  goal_style: casual
+```
+
+Run a single variation like any other task:
+
+```shell
+uv run launch_agent.py agent=GPT-5-1 task_name=mark_water_plants_as_done__casual_2
+```
+
+To run agents across **all** tasks and their goal variations in parallel, use
+the `config_parallel_tasks_across_goal_variations.yaml` config — see
+[Launch Agent(s) Across Multiple Tasks](index.md#launch-agents-across-multiple-tasks).

From a7200d945ccdcea4cfb47e19de87e2e4dc072e41 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Wed, 16 Sep 2026 15:17:10 -0400
Subject: [PATCH 22/23] [Chore] Ignore watchman cookie files

Watchman drops a probe file into every watched directory; eight of them
were showing up as untracked in every status.
---
 .gitignore | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 45cfc444..9b755dee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -198,4 +198,7 @@ CLAUDE.md
 
 tests/generated_screenshots/.runtime/*
 
-internal-*
\ No newline at end of file
+internal-*
+
+# Watchman drops these probe files into every watched directory.
+.watchman-cookie-*
\ No newline at end of file

From f301b0714291e888d67b3db68b77ab542bff7829 Mon Sep 17 00:00:00 2001
From: Aaron Smulktis <aaronsmulktis@meta.com>
Date: Wed, 16 Sep 2026 20:12:59 -0400
Subject: [PATCH 23/23] Update sitemap

---
 site/sitemap.xml    |  10 +++++-----
 site/sitemap.xml.gz | Bin 248 -> 249 bytes
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/site/sitemap.xml b/site/sitemap.xml
index 809e242b..1eb5e9f2 100644
--- a/site/sitemap.xml
+++ b/site/sitemap.xml
@@ -2,22 +2,22 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/</loc>
-         <lastmod>2026-09-16</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/Intro%20to%20UI%20Agents/</loc>
-         <lastmod>2026-09-16</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/agents/</loc>
-         <lastmod>2026-09-16</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/installation/</loc>
-         <lastmod>2026-09-16</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/tasks/</loc>
-         <lastmod>2026-09-16</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/site/sitemap.xml.gz b/site/sitemap.xml.gz
index 5b5a5521cb6ae6cb91d0a589f2baf5ccfce13965..87f56e6319ce8b20ea16e2f2fa2f2f103680e1c5 100644
GIT binary patch
delta 228
zcmV<A02}}K0r>$3ABzYGfGw+$2Ood7F||QlCUM$j{D2U$HX@Cq*sS~cO94&0b6`IB
zOZIzDmfOwu7^*Lq$z$xqN-9ygXz}P{---RlTm2$7deNS9Ajef1j?{^PIlTf*(<I5W
z8%-jKxd*aCDF|*&P;xEwqAE56T(gU{0j-`<sK9(0>kf#g?8upH2ibcb&IeTK5#E!F
z+mr}em^c0c7~&C+x>3zjt=9GGxs2R;S4Q}yyqA0zIpeZXJiGm_xNYwuKUkId2O4}N
eHX#@;-}6`{Z0K~yF)pEexc&jB$*e390{{RlZ*9u}

delta 227
zcmV<90384M0r&w2ABzYG0NkmO2OodXnA#vNlQ``%en1Fb8<8eaY}Wn!rGTd0IWQmm
zCHuW6%kB1i^wk$;axrvbC6%Z!*m!cG@5JHbt$q<(y=X7l6LM9C19f6xPOkvdG)Z!d
zqe&!V?t$!33W9qRl-vltsEW-1x9n=Ik5<npRA4@h#bb=;jD#lJLH3S^%TZIh2=58Q
zE+v8%=8eAqhIou8-Kb_=t4+OHmyvt##t6TZkCN{L=eTSX&+f1<Zr5YrC#y35K!Xd!
d#(Tr%d!DO=4V@o2#x;}=*FQZ!=93Wv004OoZLk0U