Agent UI: A Next.js Front End for AgentOS Instances
A modern chat interface for AI agents built with Next.js, Tailwind CSS, and TypeScript.
At a glance
- What is it?
- Agent UI is an MIT-licensed Next.js template that talks to a running AgentOS instance over HTTP, renders streaming responses, tool calls and reasoning steps, and expects you to already have the backend. It is a client, not a framework, and the README is explicit about that dependency.
- Who is it for?
- Adopt Agent UI if you already run an AgentOS instance and want a chat surface without building one, and if your token handling can live with a NEXT_PUBLIC_ variable or a browser-side store. Do not adopt it if you need a backend-agnostic client or a server-side auth boundary.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 130 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap Agent UI fills, and the one it assumes is already filled
AgentOS ships agents, but it does not ship a browser. Agent UI is the missing front end: a Next.js, Tailwind CSS and TypeScript template whose stated purpose is to provide a ready-to-use UI for connecting to and interacting with AgentOS instances. The audience is narrow and clearly defined. You are running Agno, you have an AgentOS process listening somewhere, and you want a chat window in front of it rather than a curl loop or a hand-rolled React app.
That framing matters because the README treats the backend as a prerequisite, not a suggestion. Under Prerequisites it says you need a running AgentOS instance, and a note repeats that Agent UI connects through the Agno platform and that the AgentOS must be running before you attempt to connect. There is no mock server, no demo mode described in the material, and no bundled agent runtime. If you have no AgentOS, this repository gives you a polished shell pointed at nothing.
The template is positioned as a starting point rather than a product. The word template appears in the opening paragraph, and the repository topics include self-hosted and agent, which matches the deployment story: you clone it, point it at your instance, and own the result.
What the chat surface actually renders
The feature list is the most concrete part of the README, and it describes a client that does more than print tokens. Streaming is handled in real time. Tool calls are visualized along with their results, which means the UI has a representation for the intermediate steps an agent takes, not just the final message. Reasoning steps are displayed when the backend makes them available, a qualifier that puts the burden on your AgentOS configuration. References are surfaced so sources used by the agent are visible in the conversation.
Multi-modality is listed as handling images, video and audio, so the message renderer is not text-only. The stack named in the README is Next.js, TypeScript, shadcn/ui and Framer Motion, with Tailwind CSS for styling. That combination tells you what customizing the interface costs: you are editing React components and Tailwind classes, and you inherit the build and upgrade cadence of every one of those dependencies.
The conditional phrasing around reasoning steps is worth reading literally. The README says reasoning is displayed when available. Nothing in the supplied material describes a fallback or an error state when the backend does not emit that data, so treat reasoning display as a feature that depends on your agent's output shape rather than something the UI can conjure.
Connection model: one endpoint, two ways to authenticate
Agent UI does not proxy agent traffic through its own server layer in the way the README describes it. It connects directly to your AgentOS instance. The default target is http://localhost:7777, and the README gives a UI path for changing it: hover over the endpoint URL in the left sidebar and click the edit option to modify connection settings. Local development uses that default or a custom local port; production expects your AgentOS HTTPS URL.
Authentication is optional and has two routes. The recommended one is an environment variable, NEXT_PUBLIC_OS_SECURITY_KEY, set in .env.local or the shell. The README notes this is the same variable AgentOS uses, so when both run on one machine you set it once. The second route is manual: find the Auth Token section in the left sidebar, click the token field, and enter the token. The security note states that tokens are stored locally in global store and sent as Bearer tokens in API requests.
Two details deserve attention. First, the NEXT_PUBLIC_ prefix in Next.js means the value is embedded in the client bundle, which is a deliberate choice for a browser-to-backend connection but is not the same as keeping a secret server-side. Second, the fallback path stores the token in a browser-side global store. The README calls this secure storage; it is local persistence, and the distinction is yours to evaluate against your threat model.
Getting it running: two install paths and one version trap
The automatic path is a single command: npx create-agent-ui@latest. The manual path is four steps. Clone the repository and enter it, run pnpm install, run pnpm dev, then open http://localhost:3000. Note the package manager: the README specifies pnpm, not npm or yarn, for the manual route.
Version support is the sharpest constraint in the document. The main branch supports Agno v2.x and is marked recommended. The v1 branch supports Agno v1.x for legacy compatibility. If you are on an older Agno release and clone the default branch, you are on the wrong code path, and the README does not describe a compatibility shim between them. Check your Agno version before you clone.
There is also a troubleshooting pointer. If the connection fails, the README directs you to check that AgentOS is running and accessible, and links an FAQ page on AgentOS connection. No releases were retrieved for this repository, so there is no changelog to consult for upgrade notes; the branch split is the versioning mechanism you get. That is a real maintenance consideration for anyone pinning this as a dependency rather than forking it.
Where this template is the wrong tool
The direct-connection design is the main limitation. Because the browser talks to AgentOS, the AgentOS endpoint must be reachable from the user's network and must handle CORS and TLS in a way the browser accepts. The README's production guidance is simply to enter your production HTTPS URL, which assumes that endpoint is publicly reachable. If your AgentOS sits behind a private network, a VPN, or an internal service mesh with no public ingress, this template's connection model does not fit without you adding a proxy layer that the README does not describe.
Auth is the second boundary. The recommended variable is client-exposed by construction, and the UI fallback keeps the token in browser storage. If your policy requires that credentials never reach the browser, or that every request be authorized by a server you control, you are looking at rewriting the connection layer rather than configuring it.
Third, this is a chat interface for AgentOS specifically. It is not a general OpenAI-compatible client, and the README names no other backend. If your agents live behind a different runtime, the tool call rendering, reasoning display and reference handling here are shaped around Agno's response format and will not map cleanly onto something else. Finally, there is no mention of multi-user sessions, conversation persistence beyond the browser, or an admin surface. For a single operator or a small internal tool, that is fine. For anything with accounts, expect to build it.
The alternative: build the chat layer yourself on the same stack
The honest comparison is not another chat product. It is the option most teams actually weigh: scaffold a Next.js app and write the AgentOS client yourself. The difference is in what you inherit. Agent UI hands you a working renderer for streaming, tool calls, reasoning steps, references and mixed media, plus shadcn/ui components and Framer Motion already wired in. Writing that from scratch means designing a message schema that survives partial tool call updates, deciding how to render a reasoning block that may or may not arrive, and handling audio and video content types. That is weeks of interface work that this template has already done, and it is the strongest argument for using it.
The counter-argument is control. A custom client lets you put a server route between the browser and AgentOS, keep the token server-side, and normalize whatever backend you like behind one internal API. Agent UI's direct connection model is shorter to set up and harder to lock down. If your deployment already has a backend-for-frontend pattern, dropping this template in unchanged will fight that pattern.
A middle path exists and the README supports it implicitly: fork the repository, keep the components, and replace the connection layer. You lose the npx create-agent-ui@latest upgrade path, but you keep the parts that took the longest to build.
Licence and the cost of staying current
The project is MIT licensed, per the README and the LICENSE file it links. MIT permits commercial use, modification and redistribution with the copyright notice and permission notice retained. This is not legal advice; read the LICENSE file and your own counsel's guidance if you are embedding it in a product.
The practical licence implication is that forking is a legitimate strategy, not a workaround. You can strip the Agno-specific connection code and ship the rest without a copyleft obligation.
Maintenance cost is where the version split bites. The main branch tracks Agno v2.x and the v1 branch serves v1.x. That means an Agno major version bump is a branch decision for you, and no releases were retrieved, so there is no published changelog to diff against. The dependency surface named in the README (Next.js, TypeScript, shadcn/ui, Framer Motion, Tailwind CSS) moves on its own schedule, and shadcn/ui in particular is a copy-in component model rather than a versioned package, so component updates are manual merges. Budget for periodic rebasing against main, or accept that your fork drifts. The endpoint default of http://localhost:7777 and the NEXT_PUBLIC_OS_SECURITY_KEY variable are the two things most likely to need changing in any real deployment, and both are documented.
Editorial conclusion
Adopt Agent UI if you already run an AgentOS instance and want a chat surface without building one, and if your token handling can live with a NEXT_PUBLIC_ variable or a browser-side store. Do not adopt it if you need a backend-agnostic client or a server-side auth boundary. Before wiring it to anything real, confirm which branch matches your Agno version (main for v2.x, v1 for v1.x) and verify whether your AgentOS requires a security key, because the default endpoint is http://localhost:7777 and nothing connects until that instance is reachable.
Community notes