Web viewer

The optional viewer shows what Enso is doing, what is coming up, and what needs your attention. It is read-only: use chat, files, or the CLI to change configuration, move work, or run jobs. In Enso Cloud, open it from a completed instance.

Running it

The managed installer includes the web extra by default. With it installed:

enso web start
enso web status
enso web stop

start runs in the background and prints its URL, normally http://127.0.0.1:8787. For a different port or a foreground process:

enso web start --port 9000 --foreground

The viewer is separate from enso serve, so it can show saved state while chat is stopped. It writes its own log and process lock at ~/.enso/web.log and web.pid. A manually started viewer does not survive reboot; Cloud manages its viewer as a user service, and newer builds can install one locally (below). status exits 0 only while running. Starting an existing viewer or stopping one that is absent is harmless.

If the extra is missing, start explains what is needed; status and stop still work without it. For a source checkout, install it with uv tool install -e '.[slack,telegram,web]' from that checkout. Keep the extras you need; see Installation.

Optional user service

enso web install and enso web uninstall are in Enso’s beta source and are not in the published v0.1.2 release. Run enso web --help to see whether your installation lists them.

enso web install     # supervise the viewer and start it again at login
enso web uninstall   # stop the viewer and remove automatic startup

install writes a launchd agent on macOS or a systemd user unit on Linux, starts the viewer immediately, and brings it back after a crash and at every later login. It starts at login rather than at boot: macOS needs a desktop login, and Linux waits for yours unless the machine is already set to keep a user’s services running without one (systemd lingering), which installing does not change. The supervised viewer writes its output to ~/.enso/launchd-web.log instead of ~/.enso/web.log.

Once it is installed, enso web start and enso web stop control that service, and enso doctor and the Health page report its state. A supervised viewer takes its address from web.host and web.port only, so --host and --port are refused: change the configuration and restart it, or stop it and run enso web start --foreground with the flags you want. uninstall stops the viewer and removes automatic startup, leaving the enso serve service, your home, and its logs alone.

Configuration and recovery mode

web.host and web.port in configuration supply defaults; --host and --port override them for a manual start. Stop and start the viewer to change its address. Restarting enso serve does not restart the viewer.

A missing or invalid configuration falls back to localhost on port 8787 unless flags select another address. Health still opens to explain the problem. Viewing an older database does not migrate it. Before it binds, start warns when config.json is unusable, and again whenever the address it is about to use is reachable from other machines.

The root opens Today. Desktop navigation also includes Tasks, Heartbeats, Runs, Jobs, Workspaces, and Health, in that order. Skills is a section under Workspaces.

On a phone, use Today, Tasks, Heartbeats, Runs, and More in the bottom bar. More contains Jobs, Workspaces, and Health. Search and filters help narrow lists; / focuses search where available.

The knowledge feature adds Knowledge to desktop navigation and the phone’s More menu. The Memory feature adds a separate Memory item in both places.

Pages show when they were rendered and do not refresh automatically. Reload to see new activity. On iPhone, Share → Add to Home Screen adds Enso at the address you opened. Tap the current bottom tab to reload in that full-screen view. It requires live access to the machine and does not work offline.

Today

Today combines Schedule, Activity, and Reliability. Summary tiles show work performed, gated checks, failures, the next scheduled check, and heartbeats needing attention. Follow a tile or failure to its underlying record.

On desktop, the schedule chart offers 6, 12, or 24 hours back and roughly two hours ahead. Future slots are planned work, not completed runs. Unscheduled stage jobs have no future cron slots. On phones, the summary tiles replace the wide chart.

Activity includes job and heartbeat runs; consecutive quiet checks fold together. Summary and activity use a 24-hour lookback from the start of the current hour, independent of the chart range. Activity scans at most 400 retained runs, so a busy home may need the paginated Runs view. Reliability uses up to 30 recent runs per current job from a separate 400-job-run sample; it is not lifetime reliability.

Tasks

The task board groups work in this order:

Group	Meaning
Blocked	A human stage, a blocked task, or a task flagged for attention
Active	Claimed for task execution
Ready	Unclaimed work in an executable stage
Backlog	Parked work that agents cannot claim
Done	Finished or cancelled tasks

Filter by project, stage, or search text. Finished history is capped at 200 displayed tasks, with totals and limits stated above the board. Open a task for its specification, current stage, claim, evidence, worktree details, and timeline. Moves happen through chat or enso task; the viewer never moves a task.

Workflow audit

The following task audit features describe the implemented workflow beta; check availability for your installation. The workflow guide explains the execution and recovery contracts.

The task’s current stage and its latest transaction are separate facts. A submitted handoff remains in its stage while Enso checks or repairs it. The task page identifies working, submitted, checking, repairing, accepted, blocked, and interrupted outcomes, with the recorded reason when attention is needed. A provider’s successful exit does not make the stage accepted. Any recorded operator override is labelled separately from passing checks.

Workflow history lists transactions newest first. Open a transaction to inspect:

The stage, requested destination, submitted handoff, and Enso’s acceptance status.
Required checks, with recorded status, exit code, duration, attempt, candidate, and captured output or diagnostic. Configured checks without results say Not yet run; an unchecked stage says No required checks configured.
Candidate revision, spec and workflow versions, repair budget used, timestamps, and the associated run, when retained.
Integration phase, previous target, and integrated candidate when Git landing was attempted. A ref update that completed before interrupted acceptance is explicitly distinguished from an accepted handoff; recovery still requires fresh verification.

Check output is displayed literally and escaped. The viewer never infers a check pass from agent prose, and it does not label missing evidence as success. Workflow evidence survives provider-run retention; a pruned run is identified without a broken link. Manual check execution is labelled Operator verification in claims, workflow evidence, and timeline entries. It has no provider-run link because no provider ran.

Lifecycle scripts shows each event’s transition, stable event ID, delivery status, and attempts. Open its deliveries for exit codes, timings, and output. Pending delivery and failed reactions remain visible even when the stage handoff was accepted; a failed completion script does not undo the accepted transition.

Worktree history

The worktree panel uses the recorded path, branch, target branch, starting revision, and preparation or cleanup status. External worktree locations are supported. The target is the one recorded for the task, regardless of the branch currently open in the main checkout.

A failed cleanup retains its diagnostic. A bounded read-only Git query counts commits ahead of the recorded target; unavailable Git or a missing worktree shows an unknown count while preserving metadata. After recorded removal, the panel retains ownership history and omits the live commit count. A task with no worktree record has no panel.

Heartbeats

Current shows active and paused beats; Previous shows fulfilled, cancelled, and expired beats until retention removes them. Disabled Heartbeat keeps its saved records visible.

Open a beat’s Overview, History, or Runs for its instructions, allowed actions, completion condition, timing, latest check, event history, and agent output. Quiet checks update the latest-check fields without adding agent runs or timeline noise. Lists and history paginate at 50. Use the CLI lookup shown with clipped event content to read its full record. Pause, edit, or complete a beat through chat or the CLI.

Jobs

Jobs shows schedules, workspaces, agents, recent outcomes, and next runs. A stage job without a schedule says it runs when work is ready.

A job opens to Overview and History: its prompt, settings, validation problems, hook filenames and timeouts, concurrency group, follow-up limit, and run history. Hook script contents are not displayed. With the workflow beta, the job also shows project capacity and configured stage check names; command and integration stages identify Enso engine execution without a model. History shows up to 500 runs; use the filtered Runs page for more when retention is higher.

Runs

View	Shows
Acted	Agent work, excluding `no_work` and `skipped` outcomes
Failed	Errors, timeouts, prerun failures, and interrupted heartbeat assessments
All	Retained history, with consecutive quiet outcomes folded

Filter by source, job, or status; an explicit status overrides the view. Results paginate at 500. Heartbeat checks that never called an agent are absent.

Each row carries one status:

Status	Meaning
`ok`	The provider and any postrun checks finished successfully
`error`	The provider, a postrun check, or the run itself failed
`timeout`	The provider turns ran out of their shared time allowance and were stopped
`no_work`	The prerun exited 1, or a stage job had nothing to claim; the provider never ran
`prerun_error`	The prerun failed; the provider never ran
`skipped`	The concurrency group was busy; the provider never ran
`running`	Still going, or interrupted before it could close
`cancelled`	A heartbeat assessment stopped before it settled, for example on pause, edit, or shutdown

A timeout is drawn amber rather than red, because the run ran out of time rather than failing, but it still counts as a failure wherever the viewer counts them. See Run history.

Open a run for status, duration, agent, trigger, errors, and retained output. Job runs include ordered provider attempts and postrun results. A run remains running while its postrun script validates the result or requests a follow-up. A failed check can fail the run even if its provider exited successfully; see Postrun scripts.

For stage jobs in the workflow beta, Task workflow shows the run’s transactions using the same evidence view as the task page, with a link to the full task audit. Provider completion and stage acceptance are separate outcomes.

Workspaces

Each workspace shows its audit verdict, bindings, jobs, upload size, and findings. Browse knowledge/, drafts/, and uploads/ to read saved files. Text and Markdown render in place; binary, unreadable, or larger-than-2-MiB files show metadata instead. Paths outside those roots, including escaping symlinks, return 404.

The basic file browser escapes raw HTML, keeps images as text, and limits link schemes. A workspace file cannot make the viewer execute its embedded HTML or load remote images.

With the knowledge feature, the workspace’s knowledge card opens the dedicated reader described below.

Knowledge

Available with the knowledge feature, /knowledge browses shared General knowledge and automatically discovered workspace roots. Navigate nested folders with breadcrumbs, search within a folder or across roots, or switch to a paginated flat list or recent files.

Open a page to follow wiki or Markdown links, jump to headings, inspect backlinks, and view its source. Managed page URLs survive moves. The reader displays local images and offers attachment downloads; remote images stay unloaded. Editing happens through chat or the CLI. See Knowledge for the supported format, links, and limits.

Memory

Available with the Memory feature, /memory shows dated conversation summaries, newest event first. Filter by workspace, transport, channel, and date, or search summary text. The timeline groups events by day in the configured Memory timezone and paginates at 50 entries.

Open a memory to read its summary and original user/agent exchanges. Event start and end times are separate from the time the summary was created. Expand exchange details for the sender, workspace, transport, channel, thread, and provider session; a failed exchange shows its diagnostic. A long exchange is shortened with that label and the enso memory show REF --sources command for the whole text. The page is read-only; use the Memory commands for recall and authorized removal.

Skills

Skills is grouped by workspace, Enso home, and external user scope. Filter by workspace, status, or name. Open a skill to see its description, paths, applicable workspaces, and collisions. A user-scope skill remains managed outside Enso.

Health

Health shows the same checks as enso doctor: configuration, home and workspace audits, provider paths, transport extras, service state, jobs, and Heartbeat health. It reads beat state without running gates or assessments.

It also reports the database footprint, supported schema, viewer version, home, and bind address. Log shows the last 200 lines of enso.log.

Access

The viewer has no built-in authentication. Keep it bound to 127.0.0.1, with an authenticated private tunnel or proxy if you need remote access. Cloud supplies its own authenticated gateway; open a fresh view through Cloud when access expires.

Read-only pages still expose private files, prompts, logs, and provider output. The viewer accepts only GET; other methods, including HEAD, return 405. Pages are not cached, and the viewer loads no third-party scripts. Its process opens the database read-only and writes only its log and process lock.