Spaces:
Running
Running
File size: 12,865 Bytes
1f82251 a8f5a2f 1f82251 a8f5a2f 1f82251 40a5fbc a8f5a2f ea31752 40a5fbc 6b1f716 40a5fbc 6b1f716 a8f5a2f 1f82251 a8f5a2f d2880ff 0d56bc3 a8f5a2f d2880ff 0d56bc3 a8f5a2f 92ed407 d2880ff cef9371 ff322b9 0d56bc3 40a5fbc e61da98 40a5fbc 6b1f716 cef9371 40a5fbc ff322b9 d2880ff ff322b9 d2880ff ff322b9 5d3283b 46d9e41 d2880ff ff322b9 d2880ff 46d9e41 d2880ff ff322b9 d2880ff ff322b9 d2880ff ff322b9 d2880ff ff322b9 a8f5a2f 6b1f716 a8f5a2f 0e56f1a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | ---
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](https://huggingface.co/LiquidAI/LFM3-1.7B) by default, or one of [several other local models](#local-models), running on your GPU through WebGPU with [transformers.js](https://github.com/huggingface/transformers.js). If your device can't run them, you can [use an API model instead](#api-models).
- **Computer:** a real Debian 12 (i386) machine running in the browser on [CheerpX](https://cheerpx.io), the engine behind [WebVM](https://webvm.io), loaded with languages and tools ([see below](#the-linux-machine)). 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`](image/build.sh) (debootstrap, the packages in [`image/packages.txt`](image/packages.txt), the files in `image/overlay/`, then an ext2 image split by [`image/chunk.py`](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](https://huggingface.co/LiquidAI/LFM3-1.7B-ONNX) (default) | Liquid AI | 1.40 GB | 256k | yes | Fast hybrid model, good at tool use. |
| [LFM3 Omni 2B](https://huggingface.co/LiquidAI/LFM3-Omni-2B-ONNX) | 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](https://huggingface.co/onnx-community/Qwen3.5-0.8B-Text-ONNX) | Qwen | 0.49 GB | 256k | yes | Smallest. Best chance on weak GPUs and phones; less capable. |
| [Qwen3.5 2B](https://huggingface.co/onnx-community/Qwen3.5-2B-ONNX) | Qwen | 1.40 GB | 256k | yes | Text only; the vision encoder isn't downloaded. |
| [Qwen3 1.7B](https://huggingface.co/onnx-community/Qwen3-1.7B-ONNX) | Qwen | 1.44 GB | 40k | yes | Previous Qwen generation. |
| [Granite 4.0 1B](https://huggingface.co/onnx-community/granite-4.0-1b-ONNX-web) | IBM | 1.25 GB | 128k | no | Hybrid model built for tool calling. |
| [SmolLM3 3B](https://huggingface.co/HuggingFaceTB/SmolLM3-3B-ONNX) | Hugging Face | 2.14 GB | 64k | yes | Fully open model. |
| [Llama 3.2 3B](https://huggingface.co/onnx-community/Llama-3.2-3B-Instruct-ONNX) | Meta | 2.42 GB | 128k | no | Calls tools with plain JSON. Llama 3.2 Community License. |
| [Qwen3.5 4B](https://huggingface.co/onnx-community/Qwen3.5-4B-ONNX) | Qwen | 2.82 GB | 256k | yes | Most capable Qwen here; needs about 4 GB of GPU memory. Text only. |
| [Jan-nano 4B](https://huggingface.co/onnx-community/Jan-nano-ONNX) | 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](https://huggingface.co/docs/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](https://huggingface.co/LiquidAI/LFM3-1.7B-ONNX/blob/main/LICENSE). Llama 3.2: [Llama 3.2 Community License](https://huggingface.co/onnx-community/Llama-3.2-3B-Instruct-ONNX/blob/main/LICENSE.txt) ("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.
|