agentwebui-lite

AgentWebUI Lite

One small web page to chat with AI models and with command-line agents, on your own server. Open it and chat: there is no setup screen and no accounts. Everything is configured in .env.

• Models: any OpenAI-compatible API (OpenAI, OpenRouter, NVIDIA, Groq, Ollama, LM Studio, vLLM, …).
• Agents: anything that speaks the Agent Client Protocol over stdio: Claude Code, Codex, Hermes, Pi, Gemini CLI, OpenCode, … Pick the agent, then its model and effort, then the folder it works in. It streams its thinking, plan, tool calls and diffs, and asks before it acts.

The server is about 3,000 lines of Python with one dependency (aiohttp) and uses about 40 MB of memory. The web client is Preact through htm with no build step. Nothing loads from the internet unless you pick a font other than Geist.

What you can do

Run it on your computer

Needs Python 3.11+.

python3 -m venv .venv && .venv/bin/pip install -e .
cp .env.example .env        # then turn on a model provider or an agent
.venv/bin/agentwebui-lite  # http://127.0.0.1:3000

Run the tests with .venv/bin/pip install -e '.[dev]' && .venv/bin/pytest.

Or install the released package: pip install agentwebui-lite (that is how Atlas Agents' servers get it).

Put it on a VPS

Two ways; both end with the app behind Caddy on HTTPS. Point a DNS name at the server first.

Install script (systemd, lightest)

On a fresh Ubuntu 22.04+ or Debian 12+ server:

git clone https://github.com/SovereignML/AgentWebUI-Lite.git && cd AgentWebUI-Lite
sudo DOMAIN=chat.example.com ./deploy/install.sh

It creates an agentwebui user, installs the app in /opt/agentwebui-lite, Claude Code and Codex with their ACP adapters (AGENTS=claude,codex, or AGENTS= for none), writes /etc/agentwebui-lite/.env with a new password, starts the agentwebui-lite service, puts Caddy in front for HTTPS (with streaming left unbuffered), and adds a daily backup. It prints the address and the password. Then sign the agents in once, as the app's user:

sudo -iu agentwebui claude                     # then /login
sudo -iu agentwebui codex login --device-auth

Agents work in /home/agentwebui/work (FILES_ROOTS). Clone your repositories there from the Files page, or with sudo -iu agentwebui git clone …. For pushing, give that user a deploy key: sudo -iu agentwebui ssh-keygen -t ed25519, and add the public key to the repository. Run the script again to update.

Change settings in /etc/agentwebui-lite/.env, then sudo systemctl restart agentwebui-lite. Logs: journalctl -u agentwebui-lite -f. Without DOMAIN the app answers only on 127.0.0.1; reach it with ssh -L 3000:127.0.0.1:3000 your-server or Tailscale.

Docker

cp .env.example .env    # set PASSWORD and your providers; agents are already installed in the image
DOMAIN=chat.example.com docker compose up -d --build
docker compose exec app claude                  # sign Claude Code in once
docker compose exec app codex login --device-auth

Data lives in the data volume, the agents' sign-ins in home, and your projects in ./work. The image is large (about 2.8 GB) because Claude Code and Codex come with it; build with --build-arg AGENTS= to leave them out.

Keep it safe

Whoever has the password can make an agent run commands on the server, as the app's user. Use a long password (the install script makes one), keep FILES_ROOTS narrow, and consider putting the page behind Tailscale or Cloudflare Access. Wrong passwords are limited to 8 per address per 10 minutes. Uploaded and agent-written files are served sandboxed, so an HTML or SVG file can't run as the page.

Backups

agentwebui-lite backup [FILE] writes a consistent copy of the database while the server runs (to DATA_DIR/backups/ by default). The install script adds this cron line; add it yourself for other setups:

17 3 * * * agentwebui cd /var/lib/agentwebui-lite && AWL_ENV_FILE=/etc/agentwebui-lite/.env /opt/agentwebui-lite/.venv/bin/agentwebui-lite backup

Configure

Every setting is in .env.example. A value may name a variable from your shell as ${NAME}.

PROVIDER_OPENROUTER_URL=https://openrouter.ai/api/v1
PROVIDER_OPENROUTER_KEY=${OPENROUTER_API_KEY}

AGENT_CLAUDE_COMMAND=npx -y @agentclientprotocol/claude-agent-acp
AGENT_CLAUDE_MODEL=sonnet          # where new chats start, until the browser remembers a choice
AGENT_CODEX_COMMAND=npx -y @agentclientprotocol/codex-acp
AGENT_HERMES_COMMAND=hermes acp

FILES_ROOTS=~/code,~/notes         # what Files shows and where agents may work

• An agent runs as the server's user, with this server's environment, so its own sign-in applies. Each agent chat has a folder inside FILES_ROOTS; the agent's file requests through ACP stay in that folder.
• An agent process stays up while you use it and stops after AGENT_IDLE_MINUTES (10) with nothing to do. Agents are much larger than this server (Claude Code about 370 MB, Codex about 580 MB), so this matters on a small machine.
• Without PASSWORD the server only answers on localhost. Set PASSWORD to listen on another address.
• To show the page inside another site, such as your own dashboard: list that site in FRAME_ANCESTORS, set EMBED_SECRET, and have the site open the frame at a one-time /embed?token=… link it signs (the format is in .env.example). LOCK_MODEL and LOCK_FOLDER hide the model and folder choices when the site decides them.
• Models and agents come only from .env; the browser switches between them, hides models you don't use, and remembers your defaults (Settings › Chat has "Reset to defaults").

What it does not do

No accounts, roles or sign-up, no RAG or memory, no prompt library, no workflows, no MCP management, no sandbox, no terminal and no web search of its own. Agents bring their own tools, memory, MCP servers and web search. See docs/PLAN.md.

The client

Built from the AgentWebUI redesign: docs/DESIGN.md maps every board to what is built and where Lite departs from the boards.

Releases

Bump __version__ in agentwebui_lite/__init__.py, merge to main, then tag it: git tag v0.1.1 && git push origin v0.1.1. The Release workflow runs the tests, checks the tag matches the version, builds, and publishes to PyPI through trusted publishing (no token is stored). Atlas Agents pins the version it installs, so a release reaches agents only when the app's pin moves.

License

Proprietary. Copyright (c) 2026 SovereignML, L.L.C. All rights reserved. The package is on PyPI so our servers can install it; that grants no license to use it. See LICENSE.