Home

Agent8088 Wiki

Agent8088 v1.2 documentation. These pages describe the public AGENT8088-v1.2 branch and are published to its repository wiki.

Complete reference for Agent8088 — a local-first AI agent with fine-tuned tool calling, an enforced permission layer, OS-level sandboxing, MCP in both directions, and messaging gateways.

Everything here was verified against the code in this repository rather than copied from the README. Where the two disagree, the wiki notes it explicitly.

This directory is the source of truth. It is versioned with the code and reviewed in PRs. The GitHub Wiki tab is a generated mirror — run python scripts/sync_wiki.py after changing a page here to republish it. Edits made in the wiki UI are overwritten by the next sync.

Start here

New to Agent8088? Getting Started takes you from install to your first prompt. In a hurry, the FAQ answers most first-day questions.

Guides

Read these to understand how a subsystem behaves.

Guide	Covers
Permissions & Security	What the agent may do, approvals, the always-on floor, network controls
Sandboxing	How commands are isolated, and why there is no unsandboxed fallback
Model Providers	Provider profiles, custom endpoints, keys, fallback chains
MCP	Connecting MCP servers, and exposing Agent8088 as one
Messaging Gateway	Slack, WhatsApp, Discord, Telegram and Email
Skills & Sub-agents	Bundled profiles, isolation, skills, personas
Docker	Run in a container without a system-wide install

Reference

Look things up here.

Reference	Contains
CLI Reference	Every flag, slash command, keybinding and exit code
Configuration	Every config key, the .env store, key resolution order
Tools	All 56 built-in tools, their modes and arguments
Memory	Persistent memory: what it stores, how retrieval works, /memory
FAQ	Short answers to the common questions
Troubleshooting	Symptom-first fixes

Development

Page	For
Architecture	How the agent loop, front ends and permission layer fit together
Testing & Verification	The local gates to run before opening a PR
Contributing	Isolation rules, PR conventions, publishing the wiki

What Agent8088 is

A single-process agent that runs on your machine. It talks to any OpenAI-compatible endpoint (local Ollama or a hosted API), calls tools to get real work done, and puts a permission layer around every side effect. It starts in full-auto; switch to readonly to approve each action yourself.

At a glance, verified against the current tree:

Built-in tools	56
Built-in model providers	12 (plus custom OpenAI-compatible and litellm)
Permission modes	3 — readonly, full-auto, plan-only
Sub-agent profiles	6 — auditor, coder, explore, general-purpose, researcher, test-writer
Bundled skills	39 packages in src/agent8088/skills_installed/, each an installable SKILL.md + tools.txt bundle
Slash commands	45
Gateway platforms	5 — Slack, WhatsApp, Discord, Telegram, Email
Python	3.10+

The design idea worth knowing up front

Agent8088 assumes the model will sometimes be wrong, and sometimes be manipulated by content it reads. So the safety properties do not live in the prompt — they live in code that runs regardless of what the model decides:

• Full-auto by default, readonly on request. Out of the box the agent acts without asking, inside the workspace and the always-on floor. In readonly, writes, shell, network, cron and browser actions each need your approval.
• An always-on floor. Some things are refused in every mode, even full-auto, even after you approve an escalation: reading or writing credential files, writing shell startup files, a shell git push/reset --hard, and requests for the agent's own system prompt.
• External content is fenced. Anything fetched from the web or an MCP server is wrapped in <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers with chat-template tokens stripped, so a page cannot forge a system turn.

Permissions & Security covers all of it.

Re-deriving the numbers

The counts above drift whenever someone adds a tool, a command or an adapter, so derive them from the tree rather than trusting this page:

export AGENT8088_CONFIG=/nonexistent AGENT8088_HOME="$(mktemp -d)"   # never import bare

grep -c '^[a-z]' src/agent8088/tools.txt                             # 56 tools
uv run python -c "import agent8088.cli as c; print(len(c.COMMANDS))" # 45 commands
ls src/agent8088/gateway/platforms/*.py | grep -vc 'base\|__init__'  # 5 platforms
ls src/agent8088/agents/ | wc -l                                     # 6 sub-agents
uv run python -c "import agent8088.providers as p; print(len(p.BUILTIN_PROVIDERS))"  # 12
ls src/agent8088/skills_installed/ | grep -vc '_references\|LICENSE' # 39 bundled skills

The snippet is POSIX (export, grep -c, ls, wc -l); on Windows run it under WSL or Git Bash, or use the PowerShell equivalents ($env:, Select-String, Get-ChildItem | Measure-Object).

The AGENT8088_CONFIG / AGENT8088_HOME line is not decoration: importing agent8088.cli bare reads — and can migrate — your real ~/.agent8088/config.txt. See Testing & Verification.

Claude now has a built-in anthropic provider profile alongside the other 11 — see Model Providers for that and the OpenRouter/litellm alternatives.

---

Source of truth: docs/wiki/ in the main repository. Edits here are overwritten by the next sync.