Agent Console 🤖

Mission Control For Your AI Agents

A clean operating surface for agentic systems.

Perseon AI · Quick start · Tailscale · Features · Mobile flow · Screenshots · Configuration · Adapter prompts · For agents · Security · Upgrade path · Full stack

Agent Console keeps the same mission-control layout while the selected profile controls the role, avatar seed and accent color. The gallery below shows clean demo profiles with empty sessions, empty cron jobs and no private workspace content.

Agent Console is a free, single-agent console from Perseon AI for builders who are tired of operating useful AI agents from scattered terminals, chat threads, logs and scripts.

CEO green	COO cyan	Assistant gold

Developer blue	Researcher purple	Copywriter orange

Reviewer red

Why this exists

Most agentic systems become powerful before they become presentable. They live across terminals, chat windows, logs, local scripts and half-finished dashboards.

Agent Console gives that power a cleaner front door:

Stop running your agents from terminals and messy chats. Give them a real mission control.

Use it when you want:

• a clean single-agent operating surface
• a quick local console for a Hermes profile
• a focused browser UI your collaborators can understand
• a small Python app with no frontend build pipeline
• a repo you can understand before you customize it

What you get

Area	Included in Agent Console
Single-agent console	One selected Hermes profile at a time
Runtime/status panel	Safe profile metadata, gateway status and voice capability flags
Chat surface	Hermes gateway chat through /chat and streaming replies through /chat-stream
Mission surface	Optional delegated mission path, disabled by default and hardened against shell/file-write/MCP tools when enabled
Sessions panel	Read-only recent session summaries from the selected profile state.db
Cron panel	Read-only profile-local cron jobs from cron/jobs.json
Skills panel	Read-only skill inventory scoped to configured safe namespaces
Voice controls	Browser speech fallback, optional ElevenLabs TTS and optional transcription endpoints
PWA support	Web manifest and generated icon routes for home-screen install
Mobile operator view	Phone-friendly tabs, contained panel scrolling and slide-in detail panes for sessions and workspace files
Setup docs	Local commands, configuration notes and security boundaries

Mobile-first operator flow

Agent Console is built for the moment when you need to check an agent from your phone, not just from a wide desktop monitor.

┌──────────────────────┐      tap session       ┌──────────────────────┐
│ Sessions             │  ───────────────────▶  │ Session transcript   │
│ ├─ Morning brief     │                        │ messages + composer  │
│ ├─ Client follow-up  │  ◀───────────────────  │ Back to sessions     │
│ └─ Debug run         │        back            └──────────────────────┘
└──────────────────────┘

┌──────────────────────┐        tap file        ┌──────────────────────┐
│ Workspace Files      │  ───────────────────▶  │ File preview         │
│ ├─ AGENTS.md         │                        │ markdown / HTML / img│
│ ├─ README.md         │  ◀───────────────────  │ Back to files        │
│ └─ docs/             │        back            └──────────────────────┘
└──────────────────────┘

On mobile, the list is the primary screen. Detail views slide in from the right and take over the viewport. Long lists scroll inside their own container, so the page chrome stays stable.

What this is not

Agent Console is not an agent framework, a SaaS starter kit or a broad multi-agent operations platform. You bring your agent runtime. Agent Console gives it a focused operating surface.

The free tier does not include:

• a multi-agent production plugin stack
• advanced Kanban, backlog or workflow plugins
• production deployment packaging
• commercial Full Stack templates
• private Perseon personas, memory, prompts or internal operating canon
• credentials, logs, customer data or host-specific runtime state

Architecture

This repository is deliberately small.

agent-console/
├── agent_console.py       # Python stdlib server, HTML, CSS and JS in one file
├── .env.example           # Safe local configuration template
├── README.md              # GitHub landing surface and setup guide
├── SECURITY.md            # Security and disclosure notes
├── CONTRIBUTING.md        # Small contribution guide
├── docs/                  # General docs and user guides
├── prompts/               # Copy/paste prompts users and agents can run
└── screenshots/           # README screenshots

Runtime shape:

Browser
  ↓
ThreadingHTTPServer in agent_console.py
  ↓
Selected Hermes profile and local Hermes gateway
  ↓
Read-only profile artifacts, optional voice providers

Important implementation details:

• No frontend framework.
• No bundler.
• No database owned by this app.
• No writes to profile sessions, cron jobs or skills from the default console.
• Secrets are resolved server-side and returned only as presence/status values.
• Profile selection accepts a slug, path or URL and resolves it to the configured local profile root.

Requirements

• Python 3.11 or newer recommended
• requests Python package
• A local Hermes profile and gateway if you want live chat
• Optional API keys for ElevenLabs TTS and OpenAI transcription

The app uses Python standard library HTTP primitives. requests is used for outbound provider calls.

Quick start

Clone the repository and create a local config:

git clone https://github.com/Perseon-Lab/agent-console.git
cd agent-console
cp .env.example .env
python3 -m venv .venv
. .venv/bin/activate
pip install requests

Run locally:

AGENT_CONSOLE_HOST=127.0.0.1 AGENT_CONSOLE_PORT=4200 python3 agent_console.py

Open:

http://127.0.0.1:4200

Health check:

curl -s http://127.0.0.1:4200/health

Recommended: run Agent Console behind Tailscale

Agent Console is a private dashboard for your agent runtime. It can show runtime status, sessions, cron jobs, skills and chat controls. Do not put it straight on the public internet by default.

The beginner-friendly setup is:

1. Install Tailscale on the machine running Agent Console.
2. Install Tailscale on the laptop, desktop or phone that will open the dashboard.
3. Log into the same Tailscale account on both devices.
4. Start Agent Console on the server.
5. Open the dashboard using the server's Tailscale IP or MagicDNS name.

Why this matters: Tailscale gives you a private network without making you set up public firewall rules, reverse proxies or HTTPS certificates on day one.

Read the full guide: docs/tailscale-setup.md. More user guides live in docs/.

Private access example:

# On the server
AGENT_CONSOLE_HOST=0.0.0.0 AGENT_CONSOLE_PORT=4200 python3 agent_console.py

tailscale ip -4

Then open this from another device on your Tailscale network:

http://<tailscale-ip>:4200

Keep it private unless you have added your own authentication, HTTPS and network controls.

If you are running inside Hermes and need the gateway key loaded from your Hermes environment, run through the Hermes env loader instead:

PYTHONPATH=/path/to/hermes-agent \
HERMES_HOME=/path/to/hermes/profile \
/path/to/hermes-agent/venv/bin/python -c 'from hermes_cli.env_loader import load_hermes_dotenv; load_hermes_dotenv(); import runpy; runpy.run_path("agent_console.py", run_name="__main__")'

Configuration

Start with .env.example and set only what your local runtime needs.

Common settings:

Variable	Purpose	Default
AGENT_CONSOLE_HOST	Bind host	0.0.0.0
AGENT_CONSOLE_PORT	Bind port	4200
AGENT_CONSOLE_PROFILE_URL	Default profile slug, path or URL	selected local profile slug
AGENT_CONSOLE_PROFILES_ROOT	Local Hermes profiles directory	your local Hermes profiles path
AGENT_CONSOLE_PROFILE_DIR	Optional single-profile Hermes directory, for stock ~/.hermes installs	unset
AGENT_CONSOLE_MISSIONS_ENABLED	Enables delegated /mission execution	false
AGENT_CONSOLE_HERMES_API_URL	Hermes chat completions endpoint	resolved from selected profile
AGENT_CONSOLE_HERMES_API_KEY	Optional gateway key override	unset
AGENT_CONSOLE_HERMES_MODEL	Optional model/profile override	selected profile slug
AGENT_CONSOLE_CUSTOM_SKILLS_ROOT	Safe skill inventory root	your local skills path
AGENT_CONSOLE_ELEVENLABS_API_URL	ElevenLabs API base URL	https://api.elevenlabs.io/v1
AGENT_CONSOLE_OPENAI_TRANSCRIPTIONS_URL	OpenAI transcription endpoint	https://api.openai.com/v1/audio/transcriptions

Secrets should live in your local environment or selected Hermes profile .env, never in git.

Adapter prompts

Agent Console ships Hermes-first: the default profile selection, status surfaces and chat path are built around a local Hermes profile and gateway. For the public repo, portability is handled through high-quality adapter prompts rather than pre-building every runtime integration.

Paste one of these prompts into your coding agent when you want to port the runtime layer:

• prompts/adapt-for-claude.md, adapt Agent Console to a Claude API or Claude CLI workflow.
• prompts/adapt-for-openclaw.md, adapt Agent Console to an OpenClaw gateway or local OpenClaw workflow.
• prompts/adapt-for-custom-agent-runtime.md, adapt Agent Console to another local or hosted agent runtime.

The adapter prompts intentionally instruct the coding agent to preserve the existing UI design and page structure, replace only the Hermes-specific runtime/profile calls, avoid exposing private keys/logs/memory and verify the result with real commands.

For AI agents: install this for your user

If your user asked you to install Agent Console, follow the numbered prompt files in /prompts in order. This folder contains actual prompts users and agents can run for specific tasks. General docs and user guides live in /docs.

Default rule: use Tailscale/private access first. Do not expose Agent Console publicly unless the user explicitly asks for a public deployment and approves the extra security work.

Recommended install prompts:

Start with prompts/README.md if you want the full prompt index.

1. prompts/01-understand-agent-console.md — understand the repo, runtime and target machine before changing anything.
2. prompts/02-install-tailscale.md — install or verify Tailscale/private access.
3. prompts/03-clone-and-configure.md — clone the repo, create .env and install the minimal Python dependency.
4. prompts/04-run-local-dashboard.md — run locally and verify /health and /agent-config.
5. prompts/05-verify-private-access.md — open the dashboard over Tailscale and report the private URL.
6. prompts/06-harden-and-handoff.md — confirm the setup, document start/stop commands and list remaining work.

Agent checklist:

• Read README.md, SECURITY.md, .env.example and docs/tailscale-setup.md first.
• Ask for the target machine and runtime if they are unclear.
• Keep secrets out of chat and git.
• Verify with real commands before reporting success.
• Report the exact dashboard URL back to the user.
• Leave public deployment for a separate, explicit approval step.

Runtime endpoints

Useful local checks:

Endpoint	Purpose
/health	Basic app and provider configuration status
/agent-config	Safe selected-profile metadata and resolved runtime status
/agent-sessions	Read-only session summaries for the selected profile
/agent-crons	Read-only profile-local cron jobs
/agent-skills	Read-only safe skill inventory
/site.webmanifest	PWA manifest

Security and privacy

Agent Console is designed to be safe by default, but it still sits next to sensitive agent runtime data. Treat it as a local operator console unless you have added your own auth, TLS and network controls.

Security boundaries in this repo:

• Secret values are not returned to the browser.
• Config endpoints expose presence and safe metadata only.
• Sessions, cron jobs and skills are read-only surfaces.
• Mission execution is disabled by default. If you enable it with AGENT_CONSOLE_MISSIONS_ENABLED=true, the app also disables dangerous shell/file-write tools and blocks MCP tool access in the delegated CLI call.
• This public repo excludes private Perseon agents, internal memory, credentials, logs and customer data.

For disclosure guidance and security boundaries, read SECURITY.md.

Upgrade path

Agent Console is the free single-agent tier. It should feel useful on its own, not crippled.

When your work grows beyond one agent, Perseon Console is the next step: a full command center for teams, consultants and agencies that need multi-agent visibility, plugin-ready workflows, operational dashboards and a cleaner path from prototype to client-ready system.

Upgrade when you need a full mission control stack:

Tier	Best for	Adds
Agent Console	Builders who want one agent out of the terminal and into a clean UI	Basic operating surface, status, sessions, cron jobs, skills and chat
Perseon Console Core	Builders who want a polished paid starting point	Broader app foundation, setup guide, branding and deployment guidance
Perseon Console Full Stack	Consultants, agencies and serious builders running more than one agent	Multi-agent workflows, plugin-ready patterns, deeper docs and commercial packaging
Perseon Console Install Sprint	Buyers who want help installing it fast	Done-with-you setup and handoff support

Upgrade to Perseon Console: get the Full Stack offer through Perseon AI or join the waitlist as the paid Console tiers roll out.

Need the full mission control stack?

Agent Console is the lightweight starting point: one agent, one browser surface, no heavy platform assumptions.

Perseon Console is for teams, consultants and agencies who need the full operating layer: shared dashboards, multi-agent workflows, plugin-ready tools, commercial packaging and a clean path from working prototype to client-ready command center.

See the live Perseon AI site for the paid stack and product path: https://perseon.ai/.

Roadmap boundaries

Good free-tier improvements:

• cleaner setup scripts
• example profile fixtures
• safer screenshot/demo mode
• better health checks
• more read-only status panels
• clearer docs for adapting to your own agent runtime
• clearer novice-friendly install prompts for user-directed coding agents

Intentionally out of scope for this free repo:

• plugin marketplace
• paid Full Stack plugin system
• write controls for cron, files or skills
• private Perseon operating data
• broad multi-agent orchestration

Contributing

Small, focused contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

License

This repository is released under the MIT License. See LICENSE.