LocalAGI¶
LocalAGI is an agent platform: configuration, persistence, an HTTP API, a web UI, chat connectors, a scheduler, a knowledge bridge and a tool registry. It is the thing that decides which tools an agent has, where its state is written and how a message reaches it.
It does not implement the agent loop. The reason/act/observe cycle —
iteration, tool selection, planning, retries, loop detection, context compaction
— belongs to github.com/mudler/cogito, a
separate Go library. LocalAGI builds a configuration, hands it to
cogito.ExecuteTools, and gets control back only through three callbacks. This
is the single most useful fact about the project, and it is invisible from the
README.
Who owns what¶
| Concern | Owner | Where |
|---|---|---|
| Iteration cap, tool selection, forced reasoning, planning, retries, loop detection, compaction, streaming events | cogito | cogito.ExecuteTools |
| Which tools exist, their JSON schemas, their Go implementations | LocalAGI | services/actions/, core/action/ |
| Agent configuration and its persistence | LocalAGI | core/state/ |
| Prompt assembly, HUD, filters, knowledge recall, conversation write-back | LocalAGI | core/agent/ |
| MCP connection setup (but not MCP tool execution) | LocalAGI | core/agent/mcp.go |
| MCP tool execution | cogito | via cogito.WithMCPs |
| Embedding, chunking, vector storage | LocalRecall | linked in-process as a library |
| Token generation | a model server, normally LocalAI | over HTTP |
Source-verified against v2.9.0: core/agent/agent.go:1368 is the single call
site where the loop leaves LocalAGI's code.
Two ways it runs, and they are not the same code¶
Standalone¶
The localagi binary. local-agi serve (or the bare binary, which defaults to
serve) starts a Fiber HTTP server, loads pool.json, instantiates every agent
in it and runs them. This is what installation covers.
Version: v2.9.0, released 2026-05-08.
Embedded in LocalAI¶
LocalAI v4.8.2 imports LocalAGI as a Go library — core/state, core/agent,
core/types, core/sse, services, services/skills, webui/collections —
and re-implements the HTTP surface itself. LocalAGI's own web server,
/v1/responses handler, React UI and pkg/localrag HTTP client are not used.
The pinned version there is not v2.9.0. LocalAI's go.mod requires
github.com/mudler/LocalAGI v0.0.0-20260606071251-14aed1ae4336 — an untagged
commit from 2026-06-06. The module path has no /v2 suffix, so Go's import-path
versioning rules make the v2.x tags unusable: the only way to depend on
LocalAGI is to pin a raw commit. Every statement in this chapter about
"LocalAGI v2.9.0" describes the standalone product; the embedded platform tracks
main and can differ.
The two also pin different versions of cogito — v0.9.5 (March 2026) in LocalAGI v2.9.0, v0.11.1 (July 2026) in LocalAI v4.8.2. What that costs is in the agent loop.
Default port is 3000, and the README says 8080¶
LOCALAGI_BASE_URL defaults to :3000 (cmd/env.go:55), and that value is
passed straight to app.Listen (cmd/serve.go:126). Run the binary and it
listens on 3000.
README.md:75 tells the reader to open http://localhost:8080. That is correct
only under the shipped compose file, which publishes the container's 3000 as host
8080 (docker-compose.yaml:83-84, ports: - 8080:3000). Both statements are
individually true; the README does not say which is which. The README's own
environment-variable table (README.md:243) and its curl examples
(README.md:918) use 3000.
Believe the source: 3000 for a local binary, 8080 for the shipped compose stack.
What LocalAGI is not¶
- Not a model server. It has no inference code. It requires
LOCALAGI_LLM_API_URLandLOCALAGI_MODELand refuses to start without them (cmd/serve.go:31-36). - Not an OpenAI drop-in. It serves exactly one OpenAI-compatible route,
POST /v1/responses. There is no/v1/chat/completions, no/v1/models, no/v1/embeddings. See the Responses API. - Not an MCP server. It is an MCP client. Nothing in the tree binds an MCP server to a socket. See MCP.
- Not database-backed. Agent configuration, runtime state and scheduled tasks are JSON files. The only database in the picture is PostgreSQL as a vector store for LocalRecall, and it is optional. See state.
- Not authenticated by default. The API-key middleware is installed only when
LOCALAGI_API_KEYSis non-empty (webui/routes.go:30-36). With no keys set, every route is open — including the ones that accept interpreted Go and shell scripts.
Chapter map¶
| Page | Answers |
|---|---|
| architecture.md | What runs in which process, and how the pieces are wired |
| installation.md | Getting it running, standalone or under compose |
| agents.md | The configuration schema and its traps |
| agent-loop.md | What actually happens between a prompt and an answer |
| tools.md | The built-in actions and how to add one |
| mcp.md | External tools, transports, and the client-only boundary |
| skills.md | Instructions the model reads, versus tools it calls |
| state.md | Every file on disk, and what is lost on restart |
| memory.md | The three unrelated things called "memory" |
| responses-api.md | The one OpenAI-compatible route |
| troubleshooting.md | Diagnostics for the failure modes above |
A note on the citations in this chapter¶
Every claim here is source-verified: read in the implementation, cited
path:LINE. Nothing in this chapter has been executed by us, so no page carries
a tested: block and no page describes observed runtime behaviour.
The reading was done against commit 9a6b32f, three commits past the v2.9.0
tag; the diff over core/, services/ and webui/ in that range is empty.
Links are pinned to the v2.9.0 tag, so a line number may be off by a small
offset in files that changed after the tag.
Upstream references¶
cmd/env.go—LOCALAGI_BASE_URLdefault:3000, full environment surface. Validated against v2.9.0, 2026-08-17.cmd/serve.go— startup order, required model and API URL. Validated against v2.9.0, 2026-08-17.core/agent/agent.go—cogito.ExecuteToolscall site at line 1368. Validated against v2.9.0, 2026-08-17.go.mod— cogitov0.9.5-0.20260315222927, localrecall, skillserver pins. Validated against v2.9.0, 2026-08-17.docker-compose.yaml—8080:3000port mapping. Validated against v2.9.0, 2026-08-17.README.md— thelocalhost:8080instruction at line 75. Validated against v2.9.0, 2026-08-17.- LocalAI
go.mod—LocalAGI v0.0.0-20260606071251-14aed1ae4336, cogitov0.11.1. Validated against v4.8.2, 2026-08-17. - LocalAGI release v2.9.0 — released 2026-05-08. Validated 2026-08-17.