---
title: Chrome Agent
emoji: 🌍
colorFrom: purple
colorTo: pink
sdk: docker
app_port: 7860
pinned: false
---

Self-hosted [Magentic-UI / MagenticLite](https://github.com/microsoft/magentic-ui) —
a human-centered multi-agent web/browser automation assistant, pointed at
any OpenAI-compatible endpoint. Chromium browser, no stored credentials —
the known-working configuration.

## Required Space secrets

| Secret | Description |
|---|---|
| `OPENAI_BASE_URL` | Base URL of an OpenAI-compatible `/v1/chat/completions` API (vLLM, OpenRouter, your own gateway, etc.). |
| `OPENAI_MODEL` | Model id used for both agent roles, unless overridden below. |
| `OPENAI_API_KEY` | Bearer token. Passed straight through as an env var to the process — never written into the generated config file. |

## Optional secrets

| Secret | Description |
|---|---|
| `ORCHESTRATOR_MODEL` | Model for the orchestrator role (plans, produces the final answer). Defaults to `OPENAI_MODEL`. Text-only is fine. |
| `WEBSURFER_MODEL` | Model for the web-surfer role (drives the browser). Defaults to `OPENAI_MODEL`. **Needs vision support** — the browser-use agent reads screenshots. If your model can't do vision, point this at one that can, or set `agent_mode: omniagent_only` in `config.template.yaml` to disable browsing entirely. |

## Architecture notes

- **No Quicksand VM sandbox.** Magentic-UI normally isolates the browser/code-execution agent inside a lightweight QEMU VM ([Quicksand](https://microsoft.github.io/quicksand/)), which needs KVM/nested virtualization — not available on standard HF Spaces hardware. This deployment sets `sandbox: type: "null"` instead (note: must be the literal *string* `"null"` — Magentic-UI's config is a Pydantic `Literal["null"]`, and YAML's unquoted `null`/`None` doesn't match it, silently falling back to Quicksand and crashing since `quicksand-cua` isn't installed in this image). With the sandbox disabled, the agent's browser and code execution run **directly in this container**, unisolated. This is an explicit, documented Magentic-UI mode ("dev/testing only" per their docs) — reasonable for a single-tenant personal Space, but keep in mind a compromised/prompt-injected page could interact with the container directly.
- **No noVNC, but screenshots work.** The live-browser-view requirement is partly met: Magentic-UI has a generic `browser_screenshot` message type that streams periodic screenshots to the chat UI regardless of sandbox type, so you can see what the agent's browser is doing. What you *don't* get without Quicksand is the smoother continuous noVNC video feed — that's wired specifically to the Quicksand VM's own VNC server, which doesn't exist in the null-sandbox path.
- **Internal nginx reverse proxy for the Host-header check.** Magentic-UI hardcodes a Host-header allowlist of only `localhost`/`127.0.0.1` (a DNS-rebinding defense) with no config override — so it flatly rejects requests proxied in under this Space's public hostname (`Bad Host header`, HTTP 400). `start.sh` runs magentic-ui bound to `127.0.0.1:8081` (not exposed) behind an nginx instance on `0.0.0.0:7860` (the actual exposed port) that rewrites the `Host` header to `localhost` before forwarding, including WebSocket upgrade support for the real-time chat stream.
- **Runs as a non-root user.** Chromium (launched by Playwright, for the browser-use agent) refuses to start as root without `--no-sandbox`, which Magentic-UI's local browser path doesn't pass. The Dockerfile creates and runs as `appuser` to sidestep this instead of patching Chromium flags.
- Both model roles are configured as generic `OpenAIChatCompletionClient`s — any server speaking the OpenAI chat completions API works.

## History

This Space is a fresh deployment of the same configuration that was
previously proven working on `Leon4gr45/webagent` before that Space got
auto-paused by Hugging Face's abuse-detector (a literal process-cmdline
match against a since-abandoned Camoufox-based browser swap — unrelated
to anything in this Dockerfile). A separate attempt to add a
credential-vault feature (stored login/signup secrets so the agent could
log in to sites) also got auto-paused, before it even built, by a
different (static content-scan) abuse rule — that feature was dropped
rather than deployed here. This Space intentionally carries **no stored
credentials** and no browser-engine swap: just plain Playwright-Chromium,
the configuration already confirmed to run cleanly end-to-end.