Using Agentum

Agentum’s window is a command center for the agents running on your Mac. This page walks through what each panel is for and how to do the things you’ll do most often. If you haven’t installed yet, start with Getting Started.

The shell at a glance

Three columns, top to bottom:

  • Sidebar (left, fixed width) — search, agent list, settings cog, license chip.
  • Main panel (center) — whatever you clicked. Dashboard by default; a plugin detail view or the System view when you pick one.
  • Activity rail (right) — a live feed of what your agents are doing. Off by default; toggle it from the system bar at the bottom of the sidebar.

The bottom of the sidebar is the system bar: aggregate health counts, the cog that opens the System view, and a small chip showing your license state.

The sidebar

The sidebar is your launcher.

  • Search at the top filters the agent list as you type.
  • Agents are grouped by category — Productivity, Intel, AI, Bridge, Meta — in that order. Each row has a small health dot (pulsing green when healthy) and a count pill if there are pending items or recent errors.
  • Disabled is a collapsed group of everything you’ve toggled off. Click to expand; click any agent to open its detail view and re-enable it.
  • Catalog is a collapsed group of bundled plugins you haven’t installed yet. Click any entry to open its catalog view and install it — auto-grants the integrations the plugin declares.
  • Cog in the system bar opens the System view (services, settings, schedulers, advanced).
  • License chip in the footer shows Trial — Nd during your trial (amber at 3 days, red under 24 hours) or Lifetime after you upgrade. Hover for the activated email.

Click any agent to open its detail view in the main panel.

Dashboard view

The default landing screen. Pin widgets from any plugin that ships one — they read from each plugin’s /widget-data route, so the data is live, not a snapshot. Edit the layout from the dashboard’s own controls; widgets that aren’t pinned stay available from the plugin’s detail view.

If you’ve never pinned anything, the dashboard shows a starter layout you can keep or clear.

Plugin detail view

Clicked from the sidebar. The header shows the agent name, version, an Enabled toggle, and an Uninstall button. Every installed plugin is uninstallable — you can always reinstall from the catalog if you change your mind, and your data is preserved by default under .user-state/uninstalled/<id>/ for one round of restore.

Below the header is a tab strip:

Tab What it shows
<Plugin> (custom) The agent’s own dashboard panel, if it ships one. This is the default-active tab when present.
Configuration A form generated from the plugin’s manifest.config schema. Edits save to plugins/<id>/settings.json with mode 0600. A collapsible “Raw environment variables” section sits below for power users.
Permissions Two sections: Integrations (which ctx.services.* namespaces the plugin can call — Telegram, AI, calendar, email, host-agent) and Data Reads (which other plugins’ tables this plugin reads). Each row has a green/grey toggle; “Configure first” if the underlying integration isn’t set up yet. A “Reset to defaults” button per section clears your overrides and reverts to the auto-granted manifest defaults.
Improve An LLM-driven chat that edits the plugin’s source for you. Describe what to change (“add a snooze button”, “make the message Markdown-formatted”) and the model patches the right file. Saves on disk; the plugin reloads automatically.

Saving the Configuration tab automatically restarts the running services so your changes take effect — you’ll see a small banner at the bottom of the window when it’s done.

How permissions work

When you install a plugin, the catalog auto-grants the integrations the plugin declares it needs (its manifest.uses list). Those grants show up as green toggles in the Permissions tab. To revoke one, just flip the toggle off — the plugin keeps running, but any call into that integration returns a clear error (“Integration X is not granted to this plugin”). Flip it back on and the plugin re-acquires access immediately, no restart needed.

The Data Reads section works the same way for cross-plugin reads (a digest plugin reading weather forecasts, for example). Revoking a data read returns an empty list to the consuming plugin — handled the same way as an unconfigured integration, so well-written plugins degrade gracefully.

System view

Open from the cog in the system bar. Four tabs.

Services

The container manager. You’ll see one row per service (poller, dashboard, telegram bridge, email transport, etc.) with a status pill — Running, Starting, Unhealthy, Error, or Stopped — and a per-row Restart button. Above the table: Stop all and Restart all for the whole stack.

Below the table is the Runtime card: app version, container engine state (Podman or Docker), Podman machine status, bundle sync state, and a picker for your agents folder.

Settings

This is where most of your configuration lives. From top to bottom:

  • Profile — your name and the bot persona’s name; the email addresses your agents send from.
  • LLM provider — the API key for your model provider (Gemini, Claude, etc.).
  • Integrations — one card each for Telegram Mini App, Telegram bot, Email (Migadu SMTP), Calendar (Google), Chrome bridge, Research APIs (Exa, Serper), and Remote Access. Each card shows whether it’s configured and lets you edit the values inline. Saving applies through to the running stack automatically.
  • Other detected integrations — a read-only grid of integrations the runtime found in your .env that don’t have a dedicated card yet (Twitter, WhatsApp, Host Agent, etc.). Each card lists the env vars it expects, marks them Set or Missing, and offers a Configure button that opens the in-app .env editor.

Schedulers

A read-only listing of every recurring job your installed plugins have registered. Each row shows:

  • Tick ID — the plugin’s own name for this job, or an auto-generated <plugin>:auto:N when the plugin didn’t name it
  • Cadence — Every 60s, Daily at 07:30 (America/Los_Angeles), etc.
  • Last fire — relative time of the most recent run (12s ago, 3h ago, — if it hasn’t fired yet)
  • Status — green dot for healthy, red for the last tick errored (with the error message inline), grey for not-yet-fired

Rows are grouped by owning plugin and auto-refresh every 5 seconds. Use this when an agent isn’t doing what you expect — if its last-fire time is hours stale, something’s blocking the tick. If its row is missing entirely, the plugin didn’t register the job (a hand-coded plugin forgetting to call ctx.schedule.every).

Advanced

Three cards. Use sparingly.

  • Software update — current version, a status pill (Up to date, Update available, Ready to install), and one button: Check for updates, Download, or Install & restart depending on state.
  • License — status, plan (Trial or Lifetime), account email, expiry, last verified timestamp, and a Reactivate button that re-runs OAuth in your browser.
  • Reset application — re-shows the onboarding wizard. Stops your services, clears the wizard state (onboardingComplete, agents folder, examples-installed), and reloads. Your agent files, .env values, and license are preserved — only the wizard state resets.

Telegram Mini App (optional)

If you turn on Remote Access in System → Settings → Remote Access, Agentum provisions a Cloudflare tunnel for your install and gives you a <your-app>.theagentum.com/tma URL. From your phone you can open the bot, tap the menu button, and reach a phone-friendly UI:

  • Today — what your agents have done since midnight.
  • Inbox — pending approvals you can tap through.
  • Send — a quick compose surface for Telegram or email.
  • Commands — every plugin-registered slash command as a button or single-input form.
  • Status — health, last sync, tunnel uptime.

Only the Telegram user IDs you’ve allowlisted can reach it; everything else returns 404 at the Cloudflare edge.

When the laptop sleeps the Mini App stays usable — it falls back to a cached view of recent data and queues writes for replay when you wake the laptop back up.

Configuration and integrations

Two surfaces, one rule: edit in the UI, never hand-edit .env.

  • Settings cards are the right place for anything that has one. Profile, LLM provider, the named integrations — all of them write through to .env for you.
  • In-app .env editor (System → Services → Runtime → Configure environment, or the Configure button on any “other” integration card) covers the long tail. Untracked lines you add are preserved on every save.
  • Per-plugin settings.json is edited from the plugin’s Configuration tab — you never touch the file directly.

The Integrations registry decides whether each integration shows “Configured” or “Not configured” by checking env-var presence plus filesystem checks (e.g. Calendar’s OAuth file). It refreshes automatically after a save.

Activity and logs

Two places to watch what’s happening.

  • Activity rail on the right side of the window — a feed of recent ticks, sends, approvals, and errors across every agent. Off by default. Toggle from the system bar at the bottom of the sidebar.
  • Per-service logs in System → Services. Click the service row, then the Logs view, for a streaming docker compose logs -f of just that container. Use this when something looks wrong at the runtime level rather than the agent level.

For agent-specific logs (one plugin’s tick output), use the plugin detail view’s Logs tab — it’s pre-filtered.

Where to next