KocoUI · Open source · MIT

KocoUI: your own web interface for Hermes Agent

A self-hosted PHP app that puts a Hermes agent behind your own domain: streaming chat, tool approvals, files and TOTP login. The agent stays on the server and the API key never reaches the browser.

Try the live demo View source on GitHub

Product

What KocoUI is

KocoUI is a custom web interface for Hermes Agent, written in PHP. The browser talks to the PHP app, the app talks to an existing Hermes gateway on localhost, and the API key stays in config.php outside the document root. The web process never runs the agent, and the browser never talks to the Hermes port.

PHP is a deliberate choice: it is what most web servers already run. The backend has no Composer dependencies, so the stack is nginx, PHP-FPM and SQLite. The frontend is Preact and ships as static assets. Login is a password plus a TOTP code, and users are created on the server, not through a signup form.

Capabilities

What the interface does

Streaming chat, rendered Markdown

Replies stream in and render as sanitized GitHub-flavored Markdown, so code blocks, tables and lists stay readable.

Approvals instead of surprises

When the agent wants to run a command, an inline card asks for once, session, always or deny. Approvals stay manual on the Hermes side.

Steer or stop a running turn

Send a correction into a turn that is already working, or stop it, without starting a new conversation.

Models, tools, skills, jobs

Pick the model, see which tools and skills the agent has, and manage scheduled jobs from the same interface.

Files in, files out

Upload by button, drag and drop, or paste. Documents and images the agent sends back land in an album with a lightbox.

Persona, themes, languages

Edit the agent's SOUL.md in place, switch between light and dark, and run the interface in English, German or Spanish.

The interface

Screenshots from the repository: chat on phone and desktop, the files view, and the theme picker. All of it is the same app the demo serves.

  • KocoUI on five phone screens: chat, persona editor, tool approval cards, tools and skills, and files.
    Chat, persona, approvals, tools and files on mobile.
  • Files view with uploaded documents and images in a light theme.
    Uploads and files the agent sends back, in one view.
  • Theme and accent colour picker in the settings panel.
    Light or dark, with an accent colour per operator.

The demo, the code, the install steps and the security notes are all public.

FAQ

Questions before you install

Is KocoUI the agent itself?

No. KocoUI is an interface. It needs an existing Hermes Agent on the same server, with the gateway API bound to 127.0.0.1:8642.

Where does the API key live?

In config.php outside the document root, on the server. The browser never receives it and never connects to the Hermes port.

How do users sign in?

With a password and a mandatory TOTP code. Accounts are created on the server with bin/kocoui; there is no self-registration and no password reset in the browser.

What do I need to run it?

An Ubuntu 24.04 or 26.04 VPS with Hermes already installed, a DNS name for the interface, and Node 20.19+ or 22.12+ on your own machine to build the frontend.

Is it production ready?

It is version 0.x, built for a single operator. Push notifications are best effort, and signing in does not sandbox the agent, so treat the login as the front door of that machine.

What does it cost?

Nothing. KocoUI is open source under the MIT license, and you run it on your own server.

Try it

Open the demo, then read the code

The demo is the real interface with sample data: browse chats, files, tools and the persona page. When you want it on your own domain, the install guide covers the server side.

Try the live demo