Settings
Settings
Settings (Ctrl+, in the web interface) is where every persistent preference
lives. Its 24 categories are organized into five user-centered sections:
- Personalize — General, Profiles, Appearance, Accessibility, Keyboard Shortcuts, Sounds,
and Speech. - Intelligence & behavior — Providers & Models, Memory, and Autonomy & Permissions.
- Tools & extensions — Capability Center, Commands, Lifecycle Hooks, MCP, and
Plugins & Skills. - Connect & collaborate — Connected Apps, Messaging, Networking, and Holaryn Space.
- Operations & support — Organization Governance, Diagnostics & Logs, System, Advanced, and
About.
The sidebar and Settings search remain available. All settings adds a complete filterable index
of every category and registered control; it is an alternate finding path, not the only one. Direct
routes, browser Back/Forward, category h1 focus, and search-result focus are preserved. On a narrow
window, Settings categories opens the grouped navigation as an accessible disclosure.
This page is the complete reference, one section per category.
General
Agent-wide preferences.
Artifact editor
The command run by an artifact's "Open in editor" action, e.g. code or notepad; the exported file path is appended to the command. Leave it empty (the default) to open artifacts with the operating system's default application for the file type.
Desktop
Preferences for the desktop app; in a plain browser this section just notes they live in the desktop app.
Start Holaryn Agent when you log in launches the desktop app at login, minimized to the system tray — and starting the app starts the agent, so schedules and messaging are live from login. The checkbox always shows the operating system's actual autostart state, even when it was changed outside the app. This starts the agent at login; for a host that runs even before anyone logs in, install the background service instead (holaryn service install, covered in the service runbook).
When I close the window chooses what the window's close button does. Minimize to the system tray (the default) keeps the agent running in the background — reopen it from the tray icon. Exit Holaryn Agent closes the app: an agent the app itself started stops with it, while an agent run by the background service or a terminal keeps running (check with holaryn status). The change applies immediately. The tray's and menu's Quit are unaffected by this setting.
Providers & Models
Providers, the models bound to them, and the default model. See Providers & Models for the full guide.
Connections
Provider endpoints in priority order. Add provider opens a grouped, filterable picker over the built-in provider catalog (major providers, aggregators, subscriptions, local endpoints, and a fully-manual Custom entry); picking one prefills the connection and chains straight into the API key, sign-in, or model-scan step. Each connection names an adapter (Anthropic, OpenAI, OpenAI Responses, Gemini, or OpenAI-compatible), an optional base URL, and an API key. Each connection can be scanned to discover and import the models it serves — the catalog's recommended models sort first with select-all / select-recommended buttons, and a provider without a model-listing endpoint routes to the manual add-model form with its typical model ids prefilled.
Credential pools
Optional organization-approved groups of compatible connections. The card exposes weighted fair
selection, priority reservation, quota/rate/health diagnostics, a dry-run preview, member reordering,
graceful drain, and confirmed revocation without ever displaying credentials. The advanced JSON
editor covers allowlists, validity windows, request/token/spend limits, concurrency, sticky-account
policy, lease expiry, and circuit thresholds. See Providers & Models.
Models
The selectable models, each bound to a connection, with its capabilities (context window, tool calling, vision, and more), an optional nickname, and tags. This is also where you set the session default model; disabled models stay manageable here but never appear in a model picker.
Adaptive routing
Static mode preserves established manual, profile-pinned, sticky, and first-suitable selection.
Adaptive mode applies capability/privacy gates and a quality, reliability, latency, cost, cache,
preference, and role-aware score. Presets cover quality-first, balanced, economy, local-only, and
provider-pinned policies; expert controls add limits, allow/deny lists, role routes, and weights.
Use the no-network dry-run before enabling it. Local-to-cloud movement and aggregate learning are
separate opt-ins. See Adaptive model routing.
Provider recovery
Opt-in pre-response retries, eligible-model fallback, and durable connection/model circuit
breakers. Configure explicit global or per-model chains, attempt/backoff and circuit bounds, and
expert failure-action overrides. Pinned-model fallback is a separate warning-bearing choice.
Diagnostics contain content-free circuit/attempt metadata and have a confirmed reset. Automatic
recovery always stops after partial output or a consequential tool result. See
Provider recovery.
Session status
What this host process is running right now and which model a brand-new session would use. Use it to confirm a registry change actually took effect.
Local inference desk
An offline-first machine ledger for local hardware, runtime discovery, advisory
model fit, source/license/checksum provenance, managed and adopted server health,
role assignment, benchmarks, and storage use. Add an existing Ollama model, adopt
a loopback endpoint, or provide an exact verified artifact download. Destructive
removal is limited to unshared Holaryn-owned bytes and requires confirmation. See
Local models for the guided UI and CLI flows.
Autonomy & Permissions
Posture, approval policy rules, and the allow-all residual categories. See Autonomy & Approvals for the underlying model.
Organization Governance
Effective enterprise identity and tenant scope, RBAC permissions, versioned organization-policy
simulation and lifecycle, plus audit-chain verification and scoped export. A standalone host
explicitly reports this feature as inactive until an enterprise deployment attaches both a
governance service and an authenticated authorization context. See
Organization governance.
Policy profile
Shows whether a policy profile is active and its path, with a button to reload it from the file. Use this after editing the TOML on disk so the running host picks up the changes.
Posture
The session's autonomy mode: ask (everything waits for you), selective (reversible actions proceed, irreversible ones ask — the default), allow-all, or unrestricted. The dangerous two take an explicit confirmation step, and posture is session-only — it is never persisted.
Allow-all residual categories
Comma-separated consequence categories that stay approval-gated even under the allow-all posture. The default is shell, script; shrinking this set weakens the allow-all always-gate guarantee, so only remove categories deliberately.
Policy file
Path to the TOML policy profile loaded at startup and on reload. Empty (the default) means no policy file — the built-in default policy applies.
Policy rules
Per-category and per-tool approval levels: ask, notify, silent, or never. Rules here override the posture's default resolution for the tools and categories they name.
Lifecycle Hooks
Secure lifecycle policy and bounded automation. The registry shows the effective global, profile,
trusted project, plugin, and session definitions in deterministic execution order, including
validation and trust diagnostics.
Use the editor to validate and save a managed global or profile hook. Enable and disable take
effect at the next lifecycle boundary; removal uses a confirmation step. Project trust shows the
canonical .holaryn/hooks.json path and exact SHA-256 digest, and any edit invalidates trust. The
dry-run tool previews matching order without executing handlers. The trace view shows redacted
decisions, duration, failures, timeouts, and output truncation. See
Lifecycle hooks for the schema, hook points, scope precedence, isolation, and
CLI workflow.
Profiles
Named configuration bundles: each person or kind of work gets its own model, persona, autonomy, and settings overrides, switchable per chat.
Profiles
Create, edit, and remove named configuration bundles. Switch a chat to a profile from the chat controls or by starting a message with @<profile-name>.
Default profile
The profile new chats and fresh sessions start on. Chats can still switch away from it at any time.
Memory
Where memory lives and how it is embedded for semantic recall. See Memory for the full guide.
Memory database
Where memory lives: a local SQLite file (the default — zero setup, right for one machine), or a PostgreSQL/MariaDB server shared by multiple Holaryn instances. The server URL carries no password; the password goes in a separate write-only field (or the HOLARYN_MEMORY_DB_PASSWORD environment variable) and is never written to the config file.
Memory path
Where the SQLite memory database file lives when the local backend is active. Empty uses the default location under the host state directory; changes apply on host restart.
Semantic memory
Chooses how memories are embedded for recall: keyword-only (the built-in hash embedder — no downloads, no semantic matching), local FastEmbed (fully offline after a one-time model download; needs the fastembed extra), an Ollama server, or a custom embedder. After switching, run Reindex so existing memories get vectors from the new embedder.
Vector database
Where memory's search vectors are stored: inside the local database via sqlite-vec (the default), or in a Qdrant server for large memories or shared infrastructure. Episodes and entities always stay in the memory database; this only moves the vectors, and Reindex migrates them after a switch.
Store status
Record counts, scopes, and whether the vector index matches the active embedder. A mismatch flag here means a reindex is needed before semantic recall is trustworthy.
Search memory
Hybrid keyword + vector search over stored episodes and entities, right in the browser. Useful for checking what the agent remembers and whether semantic recall is working.
Reindex
Rebuilds all memory vectors with the active embedder. Run it after changing the embedder or the vector backend; the Semantic memory panel flags whenever the index is stale.
MCP
Model Context Protocol servers this agent connects to. See Tools & MCP.
MCP servers
Add, edit, or remove MCP servers, over stdio (a command line) or HTTP/SSE (a URL). Changes apply to new sessions after a host restart, and tools from untrusted servers stay approval-gated. A compatible server's apps capability is a separate authority grant: approve it only when you want its tools to offer sandboxed interactive MCP Apps.
MCP manifest path
The TOML manifest file the server list is stored in. Changes take effect on host restart.
Plugins & Skills
Inspect signed marketplace packages and manage lower-level local plugins and portable SKILL.md
skills. See Trusted marketplace and Skills.
Trusted marketplace
Review package trust tier, publisher/registry provenance, compatibility, permissions, data access,
tests, maintenance, signatures, and advisories. Installed versions remain staged until the exact
version review checkbox is selected and Activate is pressed. Rollback, disable, and pin actions
remain separate. Organization-locked policy is visible but cannot be overridden from Settings.
Installed skills
Every discovered skill with its source, trust state, and enable state. Disable a skill to hide it from the agent without uninstalling it.
Install a skill
Install skills from a local folder or a git URL, with a confirmation step before anything is written. Installed skills appear in the list above.
Commands
Slash commands the composer offers: the built-ins, your own prompt commands, and read-only project commands. See Slash Commands.
Slash commands
Every command the composer's / popup offers, with a per-command enable switch. Disabled commands disappear from the popup but keep their definition.
Create a command
Write your own prompt command with {{placeholder}} arguments. When invoked, the placeholders are filled from what you type after the command name.
Connected Apps
Manage scoped mail, calendar, file, and future business-system accounts. Account cards show the
provider identity, external tenant, granted scopes, health, and default-account selection.
Reads use separate least-privilege scopes from write, send, share, delete, and admin operations.
The activity table records connector/account/tenant/resource/scope/result provenance without
credential values or external content. Revocation requires the displayed
REVOKE <account-id> phrase and removes the provider grant, encrypted credential, subscriptions,
scopes, and pending previews. See Connected Apps.
Messaging
Manage the Channel API identity, policy, delivery-health, revoke, and emergency-stop controls for
Telegram, Slack, and Discord. Telegram remains the bundled live polling path; Slack and Discord
reference adapters require an explicitly attached host or executable-extension transport. See
Messaging channels.
Telegram
Connect a Telegram bot: store its token (a write-only secret), allow specific chats, and test the connection. The channel starts together with the host.
Telegram enabled
Whether the Telegram channel starts with the host. It needs a bot token and at least one allowed chat; the change is applied on host restart. Default: off.
Telegram allowed chats
Comma-separated Telegram chat ids the agent will talk to — everyone else is refused. Message the bot from an unlisted chat and it replies with that chat's id, so you can add it here.
Telegram team chat
The chat id that receives agent-team escalation pushes — a topic blowing its exchange budget, or an unanswered teammate ask. Leave empty to disable the pushes. From that chat you can also ask the agent to post into a team's thread as you.
Networking
Peering between your own machines and the web listener's opt-in inbound surfaces. See Peers & Networking.
Discover instances on this network
Announce this instance on the local network (mDNS), give it a name and description, and pair with discovered instances in one click — no keys to copy. Discovery is opt-in.
Pairing policy
How incoming pair requests are decided: routed to the Approvals inbox for your consent, or auto-accepted. Also controls open network mode, in which registered peers connect without access keys.
Peer inbox token
The shared secret other machines present to message this host. Until a token is set the peer inbox does not exist — requests to it return 404.
This host's identity
The node id this host introduces itself with when it messages a peer; the receiving machine matches it against its own peer registry.
Paired machines
The machines this host can message. Pair with another host's URL and peer token, probe a peer's reachability, or unpair it.
Webhook trigger token
The shared secret that enables POST /api/hooks/<job_id> to run a scheduled job immediately. Until a token is set, webhook endpoints do not exist.
Speech
Talk to the agent and hear it back: local dictation and spoken replies that always defer to an active screen reader. See Voice.
Voice engines
Local speech-to-text (microphone dictation in chat) and text-to-speech. Both install with the voice extra and run fully on this machine — nothing is sent to a cloud speech service.
Speech-to-text model
The Whisper model used for local dictation: tiny, base, small, or medium — bigger is more accurate but slower. The model is downloaded once on first use. Default: base.
Capability Center
How and where capabilities run, plus the effective authority Holaryn has in the
current session. See Capability Center for states,
filters, permission review, CLI/API access, and private-preview fallback.
Execution backend
Where run_shell commands execute: local runs them as subprocesses on this machine; docker wraps each command in a throwaway container with the working directory mounted, which needs a running Docker. Default: local.
Docker image
The container image used by the docker execution backend, e.g. python:3-slim or ubuntu:24.04. It is pulled on first use if missing. Only shown while the execution backend is docker. Default: python:3-slim.
Prompt-injection scan
Screens tool output for prompt-injection patterns before it reaches the model: warn prepends a caution to flagged output, block quarantines it, and off disables scanning. Default: warn.
Effective capabilities
The catalog shows tools, skills, plugins, connectors, commands, provider tools,
workflows, and hosted capabilities with current lifecycle, account, permission,
model, health, and approval states. Inspecting safe metadata or loading a schema
does not grant invocation authority. If the Capability Fabric 2.0 private preview
is off, the page preserves the v0.12.3 active-chat tool availability table.
Appearance
Theme and presentation of the web UI.
Theme
Light, dark, or follow the system preference. The choice is stored in this browser, not in the host config, so each browser can differ. Default: system.
Accessibility
Announcement, sound, and motion preferences. This page currently has no toggles — it documents what is built in and what is coming.
Built in
Holaryn Agent is accessibility-first, from the core out: the web UI ships with a skip link, named landmarks, real labels and descriptions on every control, polite live regions for async work, focus-managed dialogs and page changes, and reorder buttons instead of drag-and-drop. These are always on — they are not settings.
Coming options
Placeholders for options arriving as their backends land: status-announcement verbosity and reduced motion. Sound cues live under Sounds, and the shortcuts reference under Keyboard Shortcuts.
Keyboard Shortcuts
Every keyboard shortcut and what it does — press a new combination to rebind. See Keyboard Shortcuts for the full list of defaults.
Keyboard shortcuts
Every shortcut with its function. Focus a row and press a new combination to rebind it; reset one row or everything back to the defaults. Only user deviations are persisted, and two actions can never share one combination.
View keyboard shortcuts (Ctrl+.)
A dialog listing every shortcut and its function, available anywhere in the app — in the browser and in the desktop app alike. The default binding is Ctrl+. (Cmd+. on macOS).
Sounds
Play a sound effect for agent events — an answer arriving, a permission request, a question, dictation. All off by default. See Sounds for the full guide.
Sound effects
Assign a sound to agent events (answer ready, approval needed, question asked, error, dictation, and more) with a master enable switch and volume. Every event is off by default; enabling one just picks it a sound, and the repeating "thinking" tone has its own interval control.
Custom sound clips
Upload your own short WAV, MP3, or OGG clips (up to 1024 KiB each) and pick them for any event. Removing a clip returns any event that used it to that event's default sound.
Holaryn Space
Connect this agent to Holaryn Space over HACP. The agent is fully standalone; Holaryn Space is optional.
HACP endpoint
The wss:// URL of the Holaryn Space service the agent dials out to. Empty means the agent never connects to Holaryn Space.
HACP scope
personal, or a workspace reference, deciding which Holaryn Space scope this agent registers under.
HACP node id path
Where the agent's stable node id is stored on disk, so Holaryn Space recognizes it across restarts.
Holaryn Space auth token
The Holaryn Space authentication token, supplied environment-only via HOLARYN_HACP_TOKEN or an
owner-protected file named by HOLARYN_HACP_TOKEN_FILE. The page shows whether a token is present;
the value itself is never displayed.
Diagnostics & Logs
Log level, location, format, and rotation.
Log level
DEBUG, INFO, WARNING, ERROR, or CRITICAL. Applies immediately, without a restart. Default: INFO.
Log location
The file the host logs to. Empty (the default) uses host.log (or host.jsonl) under the state directory's logs folder. Applied on host restart.
Log format
text writes plain lines to a .log file; jsonl writes one JSON object per line for machine parsing. Default: text.
Log rotation
How the log file rolls over: size rotates when it reaches a maximum size, time rotates on an interval, and session starts a new timestamped file per host start. Default: size.
Rotation interval
How often time-based rotation rolls the file: hourly, daily, or weekly. Only shown while rotation is time. Default: daily.
Rotation max size (bytes)
Size-based rotation rolls the file when it reaches this many bytes. Only shown while rotation is size. Default: 1000000 (about 1 MB).
Rotated files to keep
How many rotated files to keep before the oldest is deleted; applies to both size and time rotation. Default: 3.
Recent log output
A viewer for the tail of the active log file, so you can check what the host is doing without leaving the browser. See also Troubleshooting.
System
Software updates, version, release notes, paths, encrypted-state health, and security status.
Software updates
Choose how the agent updates itself:
- Update channel — Stable (tested releases), Beta (earlier, less-tested), or Nightly (the latest development builds). A channel is a floor, not a filter: on Beta you also get promoted Stable releases, and on Nightly you get Beta and Stable too, so you are never stranded on an old prerelease.
- Automatically check for updates — turn the background check on or off.
- Check every — how often to check (5 minutes up to once a day).
Check now runs a check immediately and reports the result in place: version Y is available on the {channel} channel, or Holaryn Agent is up to date. When a build is found, two buttons appear: Update now (in the desktop app, hands off to the shell's signed installer — the native download-and-restart flow, so signature verification is unchanged; in a plain browser it opens the release page, and the uv/pip upgrade command is shown) and Skip this version, which stops that specific build from ever being offered again — on this page, in the desktop app's native prompts, and in the browser dialog alike.
How you hear about a background-detected update depends on where you are. In the desktop app the flow is native (see the desktop app's auto-updater): an OS notification announces the build, and the native ask dialog appears at your next interaction with the app. In a plain browser, a dialog offers the release page. An update you have not acted on is offered again (once per app run on desktop, on every check in the browser), so a build published while no window was open is still waiting for you the next time you look — only versions you skipped stay away for good.
Beta and Nightly are unofficial, less-tested builds — use them only if you want early access and can tolerate breakage. On the desktop, all channels are verified against the same signing key, so switching channels is safe.
If an update prompt reappears for a build you just installed, quit the app fully (including any holaryn serve left running in the background or as a service) and reopen it: the desktop attaches to an already-running host if it finds one, and an older host reports its own version. The app re-checks against its real version before offering anything, so it will not install a build you already have.
Version and updates
The host and UI version. Updates arrive via the desktop app's auto-updater or your package manager — the web UI does not update itself. In the desktop app this section also has a Check for updates button; it gives the same channel-aware answer as Check now above (and as the Help menu and tray items — every entry point consults the same detector).
Release notes
The notes for the version you are running (falling back to the latest release, labeled, when your build has no published release — a source checkout, for example). View all release notes… opens a browser dialog like the user guide's: a table of contents of releases on the left — newest first, your version marked "(this version)" — and the selected release's notes on the right. Notes are proxied and cached by the host so the page works without the browser reaching GitHub directly; offline you see the last-fetched set.
Paths
The state directory, config file, memory path, and MCP manifest, all in one place — useful when you need to find where the agent keeps its data.
Encrypted local state
Non-secret health for the optional encrypted-state layer: protected/locked/disabled state,
wrapping provider, per-domain active key versions, migration status, and the last successful
rotation and backup evidence. The key hierarchy is shown as a wrapping-provider-to-domain rail;
no root or data key is sent to the browser.
Key operations stay CLI-only because the host must be stopped. The page shows the exact status,
enable/rotation, backup and verification commands plus prominent recovery responsibility. See
Encrypted local state for enablement, restore drills, the inventory,
and locked-state troubleshooting.
Security status
Whether a LAN auth token and an Anthropic API key are present. Only presence is reported; the values are never shown.
Advanced
Reset and recovery controls for this Holaryn installation.
Reset Holaryn
Reset Holaryn… returns local configuration to its defaults. The page first shows the exact
boundary, then requires you to type RESET HOLARYN in an accessible confirmation dialog. A reset
removes app preferences, provider/model connections, locally stored credentials, profiles,
integrations, MCP servers, custom command state, shortcut and sound choices, update and desktop
preferences, extension enablement choices, and onboarding progress.
It does not delete chats, annotations, memory, generated artifacts, tasks, coding workspaces,
jobs, journals, logs, audit or activity history, installed local models, installed plugin/skill
files, custom sound files, or project files. Settings supplied by environment variables also remain
effective; the page names those variables without exposing their values.
After a successful reset, fully quit and reopen Holaryn Agent. For a browser-hosted installation,
restart the Holaryn host and open its root URL. The existing
first-success onboarding wizard opens automatically and guides the new
configuration. A partial failure is reported as an error with the affected store; Holaryn does not
claim the reset completed.
About
About Holaryn Agent and Synergentic.
Send feedback
Report a bug, ask a question, or make a suggestion to the developers.