Agent UI: a self-hosted chat front end for Agno AgentOS

What Agent UI actually is, and the AgentOS it assumes

Agent UI is a chat front end. The README describes it as "a modern chat interface for AgentOS built with Next.js, Tailwind CSS, and TypeScript", and the repository layout backs that up: a single src/ tree, a package.json whose only runtime dependencies are React, Next.js, Radix primitives, Zustand, Framer Motion and markdown renderers, and no server-side agent code at all. There is no model client, no tool registry, no memory store. Everything that thinks happens elsewhere.

The prerequisite is explicit. Before setup, the README says you need "a running AgentOS instance", and it links to a separate guide, Creating Your First OS. That ordering matters. If you do not already have AgentOS running, Agent UI gives you a chat window that cannot answer anything. The intended reader is someone who has already built an agent on Agno and now wants a presentable way to talk to it, either on a laptop or on a shared internal host.

The topics list adds one more word worth taking literally: self-hosted. Nothing in the README describes a hosted service, an account, or a proxy. You run the Next.js app, you point it at an endpoint, and the browser talks to that endpoint directly.

How the connection to AgentOS works

The data flow is short. Agent UI runs as a Next.js app on port 3000. It holds a configurable endpoint URL, defaulting to http://localhost:7777, which is where an AgentOS instance is expected to listen. When the app loads, the README states it "will automatically attempt to connect", and on success your agents appear in the chat interface. Messages then stream back, and the interface renders tool calls, reasoning steps and references when the agent produces them.

Authentication is optional and handled in one of two places. The recommended route is the NEXT_PUBLIC_OS_SECURITY_KEY environment variable, which the README notes is "the same environment variable as AgentOS", so a single-machine setup only needs it set once. The fallback is a token field in the left sidebar. Either way the token is stored locally in a global store and sent as a Bearer token on API requests, per the README's security note.

Two details deserve attention. The NEXT_PUBLIC_ prefix means the value is compiled into the browser bundle, so anyone who can load the page can read the token. That is acceptable for a local development instance and questionable for anything exposed. Second, the browser is the client of record: requests go from the page to your AgentOS URL, which means AgentOS must be reachable from the user's machine and must allow cross-origin requests. The README does not discuss CORS configuration, and it is the first thing to check when a connection silently fails.

Installing Agent UI and connecting it to a running AgentOS

The README offers two paths. The automatic one is a single npx command that scaffolds the project:

npx create-agent-ui@latest

After it finishes, you have an Agent UI project directory. The manual path is the same thing done by hand: clone the repository, install with pnpm, and start the dev server.

git clone https://github.com/agno-agi/agent-ui.git
cd agent-ui
pnpm install
pnpm dev

The dev script is defined in package.json as next dev -p 3000, so the app serves on port 3000. The README says to open http://localhost:3000 in a browser. You should see the chat shell with an endpoint field in the left sidebar.

Now start your AgentOS instance on its own port, 7777 by default, and leave it running. If your AgentOS requires a token, put it in .env.local before starting the UI:

NEXT_PUBLIC_OS_SECURITY_KEY=your_auth_token_here

With both processes up, reload the page. The README's expected result is that the app connects automatically and your agents appear in the chat interface. If nothing appears, the README points to a troubleshooting guide at docs.agno.com/faq/agentos-connection rather than listing causes itself. To change the target, hover over the endpoint URL in the left sidebar and click the edit option, then enter either a local URL or a production HTTPS URL.

For a production build the repository defines the standard pair, pnpm build and pnpm start, and also a validate script that chains lint, format check and typecheck.

Where Agent UI stops being the right tool

The clearest limitation is the coupling. Agent UI speaks to AgentOS and nothing else. The README frames the whole product around that one integration: "Agent UI connects to AgentOS instances through the Agno platform." There is no documented adapter layer, no pluggable transport, no mention of an OpenAI-compatible endpoint. If your agents run on LangGraph, on a custom FastAPI service, or on a vendor's hosted API, this template does not connect to them, and making it do so means writing the client yourself inside a codebase that was not structured for it.

There is also a version split that is easy to miss. Main supports Agno v2.x, described as recommended, while a separate v1 branch exists for Agno v1.x legacy compatibility. Installing from the default branch against an older AgentOS is a plausible way to spend an afternoon debugging a mismatch that is documented in one line of the README.

The template has no releases. The repository shows no recent releases, and package.json still carries version 0.1.0. That is normal for an application template, but it means there is no changelog to read before upgrading, and the practical upgrade path is git pull plus resolving conflicts in files you have edited. The last push to the repository was on 2026-05-08, so this is not a codebase changing weekly.

Finally, the token handling is a real constraint rather than a nitpick. Because the security key is exposed through a NEXT_PUBLIC_ variable, a deployment that is reachable by anyone you do not trust is a deployment where that token should be treated as public.

Agent UI against building on a general chat component library

The honest alternative is not another agent chat product; it is assembling the interface from a general React component set such as shadcn/ui plus a streaming client, which is roughly what Agent UI already is under the surface. package.json shows shadcn's supporting pieces in use: class-variance-authority, clsx, tailwind-merge, Radix dialog, select, tooltip and slot. So the difference is not the components. It is the parts you would otherwise have to write: parsing a streaming response, rendering tool calls and their results, showing reasoning steps, listing references, handling images, video and audio content types, and keeping the scroll pinned during a long reply, which is what use-stick-to-bottom is there for.

If you are on AgentOS, that work is already done and you inherit it for free. If you are not, you inherit none of it, because the message shapes it renders come from AgentOS. Choosing Agent UI outside Agno means adopting a rendering layer built for a protocol you are not speaking.

A second comparison is worth making explicitly. Agent UI is not a framework and not a protocol. It is a client. The related search phrase "agent ui protocol" describes something this repository does not define; the protocol here belongs to AgentOS, and Agent UI is one consumer of it.

Licence, maintenance and what an upgrade costs

The project is MIT licensed, and the LICENSE file sits at the repository root. MIT is permissive: you can use, modify and redistribute it, including in commercial and closed-source products, provided the copyright notice and licence text are retained. That is the general shape of the licence, not legal advice for your situation, and if you fork it into a product you should read the file rather than this paragraph.

Upgrade cost is governed by the fact that this is a template you are expected to edit. There is no published release history, so there is no version-to-version changelog to follow. The realistic process is to track the main branch, pull, and resolve conflicts in the files you have customised, most likely under src/ and in tailwind.config.ts. The version split adds a second axis: main tracks Agno v2.x and the v1 branch tracks v1.x, so an Agno upgrade may force a branch decision rather than a merge.

On maintenance, the repository is not archived, and the last push was on 2026-05-08. That is the fact to weigh, rather than any adjective. Dependency versions in package.json are pinned with carets and include Next.js 15.5.18 and React 18.3.1, so a fresh install will pull forward within those ranges and you should run pnpm validate, which chains lint, format check and typecheck, after any dependency bump.

Editorial conclusion

Adopt Agent UI if you already run an Agno AgentOS instance and want a chat front end you can restyle with Tailwind, rather than building streaming, tool-call rendering and reasoning-step display yourself. Skip it if you use LangGraph or another runtime, since the README describes it as connecting to AgentOS through the Agno platform and documents no adapter for other backends. Before committing, verify the version split: main targets Agno v2.x and the v1 branch targets Agno v1.x, so check which one matches your AgentOS install.

Frequently asked questions

Official sources

1. agno-agi/agent-ui on GitHub
2. Issues
3. License: MIT
4. Project website
5. README