Skip to main content

Use the web dashboard

Task​

Use the web dashboard as a first-class management surface alongside the CLI for managing personalities, memory, cron jobs, and MCP servers.

Result​

A running dashboard at http://localhost:3000 where you can create and edit personalities, browse memory, manage cron jobs, and handle MCP OAuth flows — all from the browser.

Prereqs​

  • ethos installed and a provider configured (Configure an LLM provider).
  • A modern browser (Chrome, Firefox, Safari, Edge).
  • For remote access: an SSH tunnel or reverse proxy to the host running ethos serve.

Steps​

1. Start the dashboard​

ethos serve --web

The dashboard starts on port 3000 by default. To use a different port:

ethos serve --web --port 8080

For remote machines, open an SSH tunnel:

ssh -L 3000:localhost:3000 user@remote-host

Then open http://localhost:3000 in your local browser.

2. Navigate the main tabs​

The sidebar shows five tabs:

TabPurpose
ChatInteractive chat with the active personality.
PersonalitiesCreate, edit, and inspect personality configurations.
MemoryBrowse and search personality memory (MEMORY.md) and user memory (USER.md).
CronView, manage, and test scheduled jobs.
MCPAdd MCP servers, handle OAuth, manage tokens.

3. Create a personality via the wizard​

Navigate to the Personalities tab and click Create Personality. The wizard walks through seven steps:

Step 1 — Basics. Set the personality ID (lowercase, hyphens allowed), display name, and description. The ID becomes the directory name under ~/.ethos/personalities/.

Step 2 — Soul. Write or paste the SOUL.md content. This is the first-person identity document — who the personality is, how it speaks, what it values. The editor supports markdown preview.

Step 3 — Config. Set the model (claude-sonnet-4-20250514, gpt-4o, etc.), memory scope, and optional overrides like temperature and maxTokens. These map to fields in config.yaml.

Step 4 — Toolset. Select which tools the personality can access. The checklist groups tools by category (file, terminal, web, memory, cron). Each selected tool is written to toolset.yaml.

Step 5 — Skills. Attach skills from the discovered skill library. The list comes from ethos skills list — skills installed via ClawHub, Claude Code, or the local ~/.ethos/skills/ directory.

Step 6 — MCP. Attach MCP servers from the registered list in mcp.json. If a server requires OAuth, the wizard prompts you to authenticate now (the token is stored at the per-personality path). See Set up MCP for a personality for the full flow.

Step 7 — Plugins. Attach plugins from ~/.ethos/plugins/. This step is optional — most personalities don't need plugins.

Click Create to write the personality to disk. The personality registry picks it up on the next turn (mtime-cached, no restart needed).

4. Edit a personality​

Click a personality card in the Personalities tab to open its detail view. Each section (Soul, Config, Toolset, Skills, MCP, Plugins) is editable inline. Changes write directly to the corresponding file under ~/.ethos/personalities/<id>/.

The Character Sheet panel on the right renders the same output as ethos personality show <id> — identity, routing, memory scope, toolset, MCP servers, and plugins.

5. Browse memory​

Navigate to the Memory tab. Two independent dropdowns control what you see:

  • Personality dropdown — select a personality to browse its MEMORY.md. This is the rolling project context updated each session.
  • User dropdown — select a user profile to browse USER.md. This is the persistent cross-session, cross-personality user profile.

The memory viewer renders markdown with syntax highlighting. Use the search bar to find entries across the selected memory file.

6. Manage cron jobs​

Navigate to the Cron tab. The table lists all scheduled jobs across all personalities.

ColumnContent
NameHuman-readable job label.
PersonalityThe personality the job runs under.
ScheduleCron expression (e.g. 0 8 * * 1-5).
Statusactive or paused.
Next runTimestamp of the next scheduled firing.
Last runTimestamp and status of the most recent execution.

Actions available per job:

  • Run now — fire the job immediately, outside its schedule.
  • Pause / Resume — toggle the job's active state.
  • View history — expand to see past runs with timestamps and output.
  • Remove — permanently delete the job.

To create a new job, use the chat interface — the cron tool is agent-callable, not form-driven. See Schedule tasks with cron for the full workflow.

7. Add and manage MCP servers​

Navigate to the MCP tab. Click Add MCP Server to register a new server.

For OAuth-protected servers:

  1. Enter the server URL (e.g. https://mcp.linear.app).
  2. The UI runs OAuth discovery and displays the server's metadata.
  3. Select a personality from the dropdown — the token will be stored under this personality's path.
  4. Click Connect to start the PKCE flow in a new tab.
  5. After authorising, the token lands at ~/.ethos/personalities/<id>/mcp/<name>/.

For stdio or bearer-token servers, the form collects the command, args, and headers. No OAuth flow is needed.

The MCP tab also shows:

  • Connection status per server per personality.
  • Token expiry for OAuth-authenticated servers.
  • A Disconnect button that revokes the token and removes the stored credential.

8. Chat with a personality​

Navigate to the Chat tab. Select a personality from the dropdown at the top. Type a message and press Enter.

The chat view streams the agent's response in real time, showing tool calls inline with expandable detail panels. Each tool call shows the tool name, arguments, and result. Slash commands work the same as in the CLI:

CommandEffect
/personality <id>Switch to a different personality mid-session.
/newStart a fresh session (clears conversation history).
/skillsList skills the active personality can access.
/memoryShow the active personality's memory summary.

The session persists across page reloads — the dashboard reads from the same SessionStore the CLI uses. Starting a /new session in the dashboard is visible to ethos chat and vice versa.

9. Remote access​

The dashboard binds to localhost by default. For remote access, use an SSH tunnel rather than exposing the port directly:

# On your local machine
ssh -L 3000:localhost:3000 user@remote-host

Then open http://localhost:3000 locally. The tunnel forwards all traffic securely.

For production deployments behind a reverse proxy (nginx, Caddy), point the proxy at localhost:3000 on the host. The dashboard serves all assets from a single origin — no CORS configuration is needed. See Deploy in production for the full reverse-proxy setup.

The dashboard does not implement its own authentication. Access control relies on the network boundary (SSH tunnel, VPN, or reverse proxy with auth). Do not expose port 3000 to the public internet without an authentication layer in front.

Verify​

Open http://localhost:3000 in your browser. The dashboard loads with the sidebar tabs visible. Click Personalities — your existing personalities appear as cards. If you created a personality via the wizard, ethos personality list in a separate terminal shows the same roster.

Troubleshoot​

Dashboard doesn't load at localhost:3000 — Verify ethos serve --web is running. Check the terminal for errors. If port 3000 is in use, specify a different port with --port.

Personalities tab is empty — No personalities exist yet. Create one with the wizard or from the CLI:

ethos personality create engineer

Memory tab shows "No content" — The selected personality or user has no memory yet. Start a chat session and the agent populates MEMORY.md after the first turn.

Cron tab shows no jobs — No cron jobs have been created. Use the chat interface to create one — see Schedule tasks with cron.

MCP OAuth redirect fails — The browser cannot reach the OAuth provider's authorization endpoint. Check your network connection. If running remotely via SSH tunnel, ensure the tunnel forwards the callback port as well.

Changes made in the dashboard don't appear in CLI — The dashboard writes to the same ~/.ethos/ directory the CLI reads. Changes should appear immediately. If they don't, the personality registry's mtime cache may not have refreshed — run any ethos command to trigger a reload.

Dashboard is slow on first load — The web assets are served from the ethos serve process. The first load compiles and bundles the frontend. Subsequent loads are cached.

See also​