LocalWebAgent / README.md
ereniko's picture
v0.10.0: installable as a Progressive Web App
92ed407 unverified
|
Raw History Blame Contribute Delete
12.9 kB
metadata
title: LocalWebAgent
emoji: 🐧
colorFrom: green
colorTo: purple
sdk: static
app_file: index.html
pinned: false
license: apache-2.0
short_description: Local AI agent driving a real Linux VM, fully offline
models:
  - LiquidAI/LFM3-1.7B-ONNX
  - LiquidAI/LFM3-Omni-2B-ONNX
  - onnx-community/Qwen3.5-0.8B-Text-ONNX
  - onnx-community/Qwen3-1.7B-ONNX
  - onnx-community/Qwen3.5-2B-ONNX
  - onnx-community/granite-4.0-1b-ONNX-web
  - HuggingFaceTB/SmolLM3-3B-ONNX
  - onnx-community/Llama-3.2-3B-Instruct-ONNX
  - onnx-community/Qwen3.5-4B-ONNX
  - onnx-community/Jan-nano-ONNX
custom_headers:
  cross-origin-embedder-policy: require-corp
  cross-origin-opener-policy: same-origin
  cross-origin-resource-policy: cross-origin

LocalWebAgent

An AI agent with its own Linux computer, entirely inside one web page.

  • Model: LFM3-1.7B by default, or one of several other local models, running on your GPU through WebGPU with transformers.js. If your device can't run them, you can use an API model instead.
  • Computer: a real Debian 12 (i386) machine running in the browser on CheerpX, the engine behind WebVM, loaded with languages and tools (see below). It always runs on your device, whichever model you use.
  • Agent harness: the model calls run_command, write_file and read_file tools. Commands run in the same terminal you see, so you can watch and take over at any time.
  • File viewer: browse the machine's files and open code (syntax highlighted), text, Markdown, images, audio and video. HTML pages open as sandboxed live previews together with the stylesheets, scripts, images and data files they reference, and links between pages work.
  • Model Manager: download, remove and switch local models, and save any number of API models from 15 providers, all in one place.
  • Offline: setup installs only the Linux machine (about 440 MB to download and to store). Local models are downloaded separately in the Model Manager. Once downloaded, everything works with no internet connection.

Install as an app: LocalWebAgent is a Progressive Web App. Use the Install button (setup screen, title bar or Settings → App), or your browser's "Install app" / "Add to Home Screen". It then opens in its own window with a launcher icon and works offline; right-click the icon for a Model Manager shortcut.

Getting started: open the app, install Linux, and the Model Manager opens. Download a local model or add an API model, press Use, and start a task. Open the Model Manager again any time from the chip icon in the title bar, the model name next to the logo, or Settings → Model.

Requirements for local models: desktop Chrome or Edge with WebGPU, about 2.5 GB of free disk space, and 8 GB or more RAM. Open the app at its own URL (https://<owner>-localwebagent.static.hf.space), because the embedded view on huggingface.co can't enable the cross-origin isolation CheerpX needs.

The Linux machine

Debian 12 (bookworm), 32-bit x86, with no network access (everything is preinstalled):

Python 3.11 numpy, pandas, scipy, sympy, matplotlib (renders to PNG files you can open in the Files view), pillow, networkx, openpyxl, beautifulsoup4, lxml, jinja2, pyyaml, rich, pytest
Other languages Node.js 18 with TypeScript (tsc), PHP 8.2, Lua 5.4, Perl, Bash
C / C++ gcc / g++ 12, make, cmake, autotools, nasm, pkg-config
Data & documents sqlite3, jq, ImageMagick, gnuplot
Shell git, vim, nano, tmux, htop, ripgrep (rg), fd, bat, tree, ncdu, shellcheck, zip / 7z / zstd, man pages

Your home directory has a README and runnable examples (~/examples: plotting, pandas, TypeScript, a Makefile). About 620 MB of the 2 GiB disk is free for your files (CheerpX limits a disk to 2 GiB); they persist in the browser. When a new image is published, the app offers to update; updating starts a fresh machine, so download files you want to keep first.

The image is built reproducibly by image/build.sh (debootstrap, the packages in image/packages.txt, the files in image/overlay/, then an ext2 image split by image/chunk.py into the 4 MiB gzipped chunks in disk/; all-zero chunks are skipped, so free space costs nothing to download). Chunks stay compressed in browser storage and are decompressed by the service worker when the machine reads them.

Local models

Download, remove and switch them in the Model Manager. Downloads are fast: large files are fetched in 16 MB pieces over several connections at once (8, or 4 on low-memory devices), with automatic retries. They show their progress and speed, can be cancelled, and resume where they stopped, even after closing the tab. Everything is stored in the browser so the model also works offline. Switching models doesn't reload the page. The first model you download is put to use automatically. All are 4-bit (q4f16) ONNX builds loaded straight from their Hugging Face repositories.

Model Maker Download Context Reasoning Notes
LFM3 1.7B (default) Liquid AI 1.40 GB 256k yes Fast hybrid model, good at tool use.
LFM3 Omni 2B Liquid AI 1.43 GB 125k yes Language part of the omni model; text only, its image and audio parts aren't downloaded.
Qwen3.5 0.8B Qwen 0.49 GB 256k yes Smallest. Best chance on weak GPUs and phones; less capable.
Qwen3.5 2B Qwen 1.40 GB 256k yes Text only; the vision encoder isn't downloaded.
Qwen3 1.7B Qwen 1.44 GB 40k yes Previous Qwen generation.
Granite 4.0 1B IBM 1.25 GB 128k no Hybrid model built for tool calling.
SmolLM3 3B Hugging Face 2.14 GB 64k yes Fully open model.
Llama 3.2 3B Meta 2.42 GB 128k no Calls tools with plain JSON. Llama 3.2 Community License.
Qwen3.5 4B Qwen 2.82 GB 256k yes Most capable Qwen here; needs about 4 GB of GPU memory. Text only.
Jan-nano 4B Menlo Research 2.84 GB 40k no Qwen3 4B tuned for agentic tool use; needs about 4 GB of GPU memory.

Qwen3.5 2B and 4B are published as vision-language models; the app loads only their text parts (token embeddings and decoder), so the vision encoder is never downloaded. Models dropped from this list are deleted from the browser automatically. Without f16 shaders: Chrome on Linux often exposes WebGPU without shader-f16, even on GPUs that have it on Windows. The app detects this and uses each model's q4 build instead (4-bit weights with full-precision math): downloads are 15 to 40% larger and generation is a bit slower. Qwen3 1.7B and Jan-nano have no usable q4 build and need f16.

The context size setting is capped at each model's own window.

Phones and low-memory devices

The default model needs about 1.4 GB of graphics memory. Most phones can't give that much to a browser tab, so the app warns you on phones and suggests an API model or the smaller Qwen3.5 0.8B instead. Linux installs either way, and you can still try any local model. If one fails to load, the app explains why (out of graphics memory, no WebGPU support, or a failed download), keeps Linux running, and offers the Model Manager or another try. The raw error is under "Technical details".

To make the local model fit on more devices, the weights are kept on disk and read tensor by tensor while they are copied to the GPU, instead of being held in memory all at once. On phones and devices reporting less than 8 GB of RAM, the model also loads before Linux starts, so the two don't compete for memory.

API models

Fastest start: Sign in with Hugging Face. In the Model Manager's API tab, press Sign in with Hugging Face, approve in the pop-up, and the agent starts using openai/gpt-oss-120b through Hugging Face Inference Providers, billed to your Hugging Face account. There is no key to copy: the sign-in (OAuth with PKCE, entirely in the browser) only grants permission to run inference, and the session refreshes itself. You can pick any other tool-capable model from the list, or use an access token instead. Sign-in works in LocalWebAgent's own tab (https://<owner>-localwebagent.static.hf.space); inside the Space page on huggingface.co the browser keeps the app's storage separate, so the app offers to open its own tab for signing in (access tokens work in both).

Any number of API models can be saved; use Add API model in the Model Manager. Pick a provider, paste your key, and choose a model ID. Load list fetches the provider's models to choose from, and Test sends a tiny request to check everything works.

Provider Base URL Notes
Hugging Face https://router.huggingface.co/v1 Sign in with Hugging Face, or a token with the Inference permission. Only tool-capable models are listed.
OpenRouter https://openrouter.ai/api/v1 Models from every major lab behind one key.
OpenAI https://api.openai.com/v1
Anthropic https://api.anthropic.com/v1 Through Anthropic's OpenAI-compatible endpoint.
Google Gemini https://generativelanguage.googleapis.com/v1beta/openai
Groq https://api.groq.com/openai/v1
Mistral AI https://api.mistral.ai/v1
DeepSeek https://api.deepseek.com/v1
xAI https://api.x.ai/v1
Together AI https://api.together.xyz/v1
Fireworks AI https://api.fireworks.ai/inference/v1
Cerebras https://api.cerebras.ai/v1
Ollama http://localhost:11434/v1 On your computer. Set OLLAMA_ORIGINS to the app's address.
LM Studio http://localhost:1234/v1 On your computer. Turn on CORS in the server settings.
Other any Any OpenAI-compatible Chat Completions API that allows requests from web pages (CORS).

Every hosted provider above was checked to accept requests from web pages. Pick a model that supports tool calling. Only the model moves to the provider: the Linux machine and its files stay in your browser. That also means the agent needs an internet connection, and the provider receives your messages and the output of the commands the agent runs.

Each API model keeps its own key, only until you close the tab unless you turn on "Remember key on this device", which saves it in this browser's local storage. Keys are sent only to that model's provider.

Settings

  • Context size: how much of the conversation the model sees, in thousands of tokens. The defaults are 32k for local models (longer prompts are slower and use more GPU memory; capped at each model's window) and 128k for API models (set it to your model's context window). Each backend keeps its own value. A single command's output can use up to about 15% of it; older output is trimmed only when the conversation no longer fits.
  • Reasoning: let the model think before each step. Slower, more reliable on multi-step tasks.
  • Approve commands: ask before running each command or writing a file.
  • Max steps per task and command timeout.

Licenses

  • This app: Apache-2.0.
  • LFM3-1.7B and LFM3-Omni-2B: LFM Open License v1.0. Llama 3.2: Llama 3.2 Community License ("Built with Llama"). Qwen3, Qwen3.5, Granite 4.0, SmolLM3 and Jan-nano: Apache-2.0. No weights are re-hosted here: your browser downloads them directly from the repositories linked above.
  • CheerpX: proprietary, free for personal and open-source projects. It is not included in this Space. Each visitor's browser loads it from Leaning Technologies' CDN and caches it locally.
  • The Debian disk image (disk/) contains Debian packages under their respective free licenses.
  • Provider and model-maker icons are each organization's own Hugging Face avatar, bundled with the app so they work offline. They are trademarks of their owners and are shown only to identify them.