The shared knowledge base — published guides, policies and reference.
For development and self-administration, webAgent can expose **privileged tools** that go well beyond normal use: reading, writing, editing, and deleting files; running shell commands; and restarting the server. These come from the **Codeba
**App Config** (admin only) is the single control panel for the platform. It's organised into sections, each in its own sidebar area: - **LLM provider & Models** — which AI models the app uses and what each can do (see [[Models & Provide
The app keeps a built-in **flight recorder** — a running record of what it's doing: server log messages, agent-loop problems, tool calls and their outcomes, failed runs, every HTTP request, and WebSocket activity. It's stored in its own ded
# Agent Orchestration Configuration The Agent Orchestration ability lets an agent spawn purpose-built helper agents. This article covers every configuration setting and how they interact. ## Per-Agent Settings These settings appear in th
# App Control Configuration The App Control ability lets an agent change what the user sees in the webAgent window — switch the main view, show or hide the chat panel, and resize it. This article covers every per-agent configuration settin
You're not limited to the built-ins. From the **Agents** tab you can create your own agent and tune everything about it: - **Identity** — name, icon, description. - **Model settings** — which model it uses, its creativity (temperature), an
The app ships with several ready-made agent **templates**. You can use them as-is, clone them, or build your own (see [[Building Your Own Agent]]). The notable ones: - **webAgent** (the default) — the shared do-it-all assistant. It comes w
A single conversation can be **handed off** from one agent to another, mid-thread, without you starting over. The active agent calls a hand-off tool, the session rebinds to the new agent, its tools and instructions load, and the conversatio
The **Agent Orchestration** ability does more than hand a conversation off (see [[Delegation & Hand-off]]) — it lets one agent **spawn brand-new helper agents on the spot** to get work done, and stay on top of them. **Spawning on the spot.
The **optimizer** automatically improves an agent's instructions. Instead of you hand-tuning prompts by trial and error, it runs a small internal pipeline of three specialist helper agents — a **Planner**, a **Worker** trial stage, and a **
The **App Control** ability lets an agent **rearrange your own screen** to match what it's doing — switch the main view (Browser, Pages, Agents, Terminal, etc.), show or hide the chat panel, and resize it. For example, when it starts browsi
Agents don't only respond to you — they can also **run on a schedule** or **react to things that happen**. - **Scheduled tasks** — "every weekday at 8am, summarise my unread email." You describe tasks in plain language in the agent's **A
The **Browser Control** ability lets an agent drive a **real web browser** — navigate, click, type, read the rendered page — not just fetch text. It also lets the agent make direct web requests. The standout feature is the **live Browser p
**Integrations** let an agent act inside your real accounts — email, calendar, files, social, and more — after you connect them with a normal sign-in (OAuth). You stay in control: connecting is per agent, and you can disconnect at any time
Beyond built-in tools, you can attach an agent to your **own data**. Each external data source becomes a tool the agent can query at runtime, plus a note in its context so it knows the source exists. Types available: - **Read-only database
The **Image Generation** ability lets an agent create images from a description. The image model isn't a separate setting — it's whichever saved model you've ticked for **Image-out** in the model grid (see [[Models & Providers]]). The app f
The **Image Vision** ability lets an agent understand images you attach — even when the agent's own model is text-only. It's the read side of images; *making* images is the separate [[Image Generation]] ability, so you can grant one, the ot
The **Web Access** ability gives an agent three everyday, no-account-needed capabilities: - **Web search** — look things up on the open web. - **Weather** — current conditions and forecasts for a place. - **Maps & geocoding** — turn a plac
# Ability-Bundled Skills An ability/feature can ship a **skill** — a how-to playbook — alongside its tools. When the ability is enabled for an agent, its skill is folded into the agent's `# [SKILLS]` catalog automatically: the agent always
# Adding a Plugin Follow [[core-vs-plugins-structure-philosophy]]: a new capability is a new file in the matching plugin folder. You register nothing; discovery finds it. ## Add an integration (most common) 1. Copy `app/integrations/_TEM
# Agent Abilities (drop-in) An **ability** is a host-side capability bundle an agent admin grants to an agent (Codebase Admin, Web Access, Terminal Control, Wiki Control, ...). Abilities are the latest subsystem to join the [[core-vs-plugi
A high-level map for anyone working on the code. (Plain-English; the README has the exhaustive module table.) - **Backend** — a FastAPI web service. The agent loop runs as a **supervised background job** owned by a Run Manager, independe
# Core vs Plugins: Structure Philosophy webAgent separates a small **core** from many **external plugins**. The rule: > **A new capability is a new file in a plugin folder — never an edit to the core.** The app *discovers* plugin files a
# Edition Gating and Packaging Once features declare a [[the-feature-header]], the active edition ([[editions-and-the-production-path]]) decides what actually loads. ## Runtime gating `app/features/gating.py` is the single gate the load
The defining rule of the codebase: **new capabilities are drop-in files, never core edits.** A new integration, ability, event source, communication channel, data connector, secrets vault, encryption method, payment processor, or scheduler
# The Feature Catalog and Discovery The app discovers what code is available to it by scanning the plugin folders and reading each feature's [[the-feature-header]]. The result is one **catalog**. ## Where to see it - **App Config → Featu
# The FEATURE Header Every plugin module may expose a module-level `FEATURE` dict that describes itself. The [[the-feature-catalog-and-discovery]] reads it, and [[edition-gating-and-packaging]] uses its `status` to decide what loads. ## F
The whole app is built from a small set of ideas. Learn these and everything else clicks into place. (This page is the hub — most other pages link back here.) - **Agent** — an AI assistant with its own personality, instructions, model, and
Here's what the first few minutes look like. 1. **Open the app** and you land in **Chat**. A "pill" at the bottom is where you type. 2. **Type a message and send it.** The agent starts working immediately — the pill glows while it think
The app is organised into a row of top tabs. You won't necessarily see all of them — an admin can hide or reorder tabs — but here is what each one is for. | Tab | What it's for | |-----|----------------| | **Chat** | Talk to your agent. Th
**webAgent** is an AI **agent harness** — a place where one or more AI assistants ("agents") can chat with you, use tools, browse the web, drive terminals, remember what matters, and act on your behalf. This wiki is the manual for the whole
webAgent is a self-hostable app that puts a **tool-using AI agent** behind a clean chat interface, plus a set of workspaces around it. The core idea: instead of a chatbot that can only talk, each agent can **take actions** — search the web,
An **ability** is a single switch that unlocks a related bundle of tools for an agent. Abilities are how you decide *what an agent can do* without touching any code. There are two levels: an **app-level** switch (the admin enables an abilit
Each turn runs on **one** model, resolved in this order: the **app default** -> the **agent's** own model (if it sets one) -> the **session's** model (if one was picked in this chat). The most specific wins, so a model you pick in a convers
Everything an agent can do comes from four kinds of building block. Keep them straight and the rest of the app is easy. - **Abilities = what it can do.** An ability is a switch that unlocks a *bundle of tools*. Turn on "Web Access" and t
**Memory** is how an agent remembers things across conversations. Before each reply, the app searches stored memories — by *meaning* and by *keyword* together — and folds the most relevant ones into the agent's context, so it can recall a f
An agent's **prompt** is its standing instructions — the text that sets its role, voice, rules, and any background it should always have in mind. This is *how an agent behaves*, as opposed to what it can do (abilities) or what it knows on d
A **skill** is a knowledge pack — a written playbook for a kind of task. Skills let an agent carry a large library of know-how without stuffing all of it into every message. Remember the slogan: **abilities = tools, skills = knowledge.** E
Every answer is produced by the **agent loop** — a repeating cycle. In plain terms: 1. **Take your message** (and recall relevant [[Memory|memories]], describe any attachments). 2. **Assemble the instructions** — [[Prompts & Context|pro
A **tool** is one concrete action the agent can take. Which tools an agent *has* is decided by its [[Abilities|abilities]]. What this page is about is *how* each tool is presented to the agent — its **exposure mode** — because showing every
webAgent tracks usage so you can meter or bill for it if you want to. Every agent turn records how many tokens it used (in and out) and an estimated provider cost, and the app supports usage strategies like free, credit-based, per-token, an
To run webAgent as an always-on service rather than on your desktop, two common paths are supported: - **Google Cloud Run** — a container that scales to zero when idle. Configuration is read from environment variables (so secrets and dat
# Editions and the Production Path webAgent is **one codebase** that can ship as different **editions** — a curated build for production, a full build for development, or any custom fork — without maintaining separate branches. This works
The recommended path uses **uv** (a fast Python/environment manager) so you don't have to manage Python versions yourself. - **Windows, easiest:** use the desktop launcher — it can install everything from scratch and gives you Launch/Sto
webAgent talks to AI models through providers — by default via **OpenRouter**, which gives access to many models (from various makers) through one connection. You configure which model the agents use in **App Config**. Key ideas: - **Pick
If you run webAgent on a home or office PC, **Remote Access** lets you reach it from your phone or another network — without a fixed address. It supports several methods (secure tunnels via ngrok or cloudflared, a Tailscale private network,
Sensitive values — integration sign-in tokens, provider keys, passwords — are kept in a **secrets vault**, separate from your ordinary data, so a data reset never wipes your credentials. You choose where the vault lives: - **App database**
webAgent keeps all its data in a database, and you choose which kind. The default needs **zero setup** — a simple local file-based store — so the app just works out of the box. When you outgrow that, you can switch without changing how the
webAgent is designed to run in a lot of places. **Where the server can run:** - **Windows** — double-click installer/launcher, or the desktop `webagent.exe` (see [[The Server-Manager TUI & Launchers]]). - **macOS / Linux** — a one-line
With the **Terminal Control** ability, an agent can **open and operate interactive terminal programs** — a coding assistant like Claude Code, a CLI, a REPL, anything. The agent's tools are low-level and program-agnostic: open a program, rea
**Terminal tunnel** is the reverse of [[Agents Driving Terminals|agent terminal control]]: instead of the agent driving a program, *you* drive it — directly from the chat box. While a tunnel is active, what you type in chat is sent straight
The **Terminal** tab is a real terminal, in your browser. It's a full shell (using the native pseudo-terminal on your machine, including Windows), and each terminal session stays alive across reconnects — refreshing the page or closing the
Beyond the web app, webAgent ships **terminal-based desktop apps** that make running and managing the server friendly — no command line required. - **Desktop launcher (`webagent.exe`)** — a polished text-UI launcher for Windows that can
**Attachments.** You can give the agent files — images, audio, video, PDFs, text — using the paperclip button on the chat pill, or by dragging-and-dropping or pasting onto it. Uploads are stored per-session and survive restarts, and show up
Chat is the heart of the app, and it behaves a little differently from an ordinary chatbot. **Your work survives anything.** When you send a message, the agent's turn runs on the **server** as a supervised background job — not in your brow
**Pages** (shown as the **Dashboard** tab) is your *personal* visual workspace — a set of named screens that an agent builds and updates for you. Think home page, a dashboard, notes, or any custom page. Unlike the [[Using the Wiki|Wiki]], p
A **session** is one conversation thread. The session dropdown in the chat header lists them; you can rename, pin, and drag them into the order you want, and that order follows your account across devices. **The database is the real record
**Suggested replies.** Just above the input pill, a row of low-key grey chips suggests what *you* might want to say next. Tap one and it drops into the box, editable, ready to send. These come from a dedicated helper agent that role-plays a
The **Wiki** tab (this thing you're reading) is a **company-wide, shared** knowledge base. Every article is visible to everyone and searched together — it's the place for reference material: how the app works, policies, contacts, anything w
## Overview The Web tab (in-app browser) renders the agent's shared Playwright page so you and the agent see and interact with the same live page. There are three rendering paths, chosen based on deployment environment: | Path | When | Fe