Using the App
A screen-by-screen guide to the AKOS web and desktop application.
AKOS is available as a web application (multi-tenant SaaS, runs in any modern browser) and as a desktop application (self-hosted, runs on your own machine or private cloud). Both surfaces share the same UI — this guide applies to both unless noted.
App layout
The app is organised around a left-hand navigation rail that groups every screen into sections. Within each screen, a secondary section rail (left sidebar or top tabs depending on screen width) lets you switch between sub-sections without leaving the page.
Every screen has a consistent header: a kicker label, a title, an optional subtitle with live counts, and an actions bar on the right. Content appears in the main area below.
Navigation sections
Nav groups match packages/os-desktop/src/app-nav.ts (NAV_GROUPS / NAV_ITEMS):
| Section | Sidebar screens | Notes |
|---|---|---|
| Home | Home (Assistant), Dashboard | Assistant-first onboarding lives on Home |
| Build | Agents, Workflows, Processes, Automations | Topologies reachable from Agents |
| Run | Activity, Inbox, Results | Activity replaces separate Runs/Traces/Observability nav items |
| Workspace | General, Integrations, Knowledge, Marketplace | Config via top-bar settings; plugins via Marketplace › Installed |
| Governance | Cost, Security, Quality checks, Compliance | Former "Operations" spend/risk surfaces |
| Settings | Access, Teams, Brand & licensing | Audit and break-glass live under Access |
Route-only screens (deep-linkable, not in the sidebar): config, plugins, bundles, topologies, tools, sandbox, coding, templates, oem, flow-editor. See Route-only screens for the full reachability table.
Web vs desktop
| Web | Desktop | |
|---|---|---|
| Authentication | SSO / email sign-in | Workspace config file |
| Workspace | Cloud-managed | Local or private server |
| LLM tokens | Stored in the cloud vault | Stored on the local machine |
| Multi-workspace | Yes — switch in the top bar | Yes — open multiple workspace files |
Workspaces
A workspace is the top-level unit of isolation. Every agent, flow, trigger, secret, and audit entry belongs to exactly one workspace. On the web, you are invited to a workspace by an admin. On the desktop, you open or create a workspace file.
The current workspace name is shown in the top bar. To switch workspaces, use the workspace switcher in the top bar.
Command palette
Press Cmd K (Mac) or Ctrl K (Windows / Linux) from any screen to open the command palette. You can jump to any screen or trigger any registered action without using the navigation. Screen keywords from the nav config (for example copilot, processes, activity) are searchable even when the sidebar label differs.
Feature guides (not sidebar screens)
These guides cover cross-cutting setup flows that do not map 1:1 to a sidebar item:
| Guide | When to read |
|---|---|
| Integration setup | OAuth, app installs, and connection credentials |
| Public automation API | External webhooks and API keys that dispatch workflows |
| Model catalog | Choosing models in agent and flow forms |
| Knowledge | Indexing docs for the in-app assistant |
Documentation map
| Audience | Start here |
|---|---|
| End users (this section) | Screen guides linked above |
| Core vocabulary | Concepts |
| Run path (trigger → audit) | Run lifecycle |
| Operators / CLI | CLI command reference |
| Contributors & IDE agents | Internal agent guides and the docs query CLI (see repository CONTRIBUTING.md) |