Desktop App¶

The Openbase Coder desktop app is the main Mac interface to the product. It bundles the openbase-coder CLI runtime, walks you through first-time setup, and then presents the dashboard: projects, coding threads, reports, approvals, routines, skills, service health, and settings.

The dashboard pages described here are the same pages the web console serves in a browser — the desktop app and console share one UI. Electron-only additions (guided onboarding, auto-update, screen sharing, deep links) are called out below.

Throughout this page, On iPhone notes describe what the iOS app can do for the same feature area.

Product Analytics and Diagnostics¶

Share anonymous product usage is off until you opt in. When enabled and the app build has an analytics key, the desktop app sends a restricted set of events to Amplitude: app sessions, onboarding progress and failures, voice-call start/connect/end timing and outcomes, approval decisions and response timing, and diff views. Events include a randomly generated persistent device ID, session and event IDs, timestamps, platform, surface, and environment. They do not include prompts, code, audio, file paths, or repository content. Turning collection off removes the stored analytics device ID; the desktop also respects Do Not Track and Global Privacy Control.

Diagnostic logging is separate from this preference. Electron writes main-process, renderer, and screen-sharing companion logs under ~/.openbase/logs/, including console output, update activity, load failures, and renderer termination details. Structured secret-like fields are redacted, but the logger does not scrub arbitrary strings or error stacks. These are local diagnostic files, not Amplitude events.

On iPhone: the equivalent usage toggle is under Settings → Diagnostics. See iOS Settings for collection and log-upload details.

Install and First-Run Setup¶

Download the Apple Silicon DMG from Downloads and open the app. On first run it shows a guided setup flow:

1. Welcome — overview of the steps ahead.
2. Check this Mac and connect your phone — verifies macOS and the bundled CLI, then offers Openbase VPN (Recommended) or Openbase Direct. The full Openbase experience requires a VPN. Openbase VPN is built on Tailscale networking technology and lets the phone securely reach the Mac, including agent-created sites. Openbase Direct is the fallback when an organization or device policy blocks VPNs; core Openbase traffic works, but agent-created sites cannot open in other phone apps. Electron onboarding never asks users to install the separate Tailscale app.
3. Choose coding setup — asks whether the Mac already uses the Codex CLI or Claude Code CLI. Choose No for the normal Openbase Cloud path: managed Claude Code plus managed speech-to-text and voice output, with free monthly allowances and no third-party provider keys. Choose Yes to bring an existing Codex or Claude Code subscription.
4. Sign in to the coding agent when needed — appears only after choosing Codex or Claude Code. The app starts the provider's secure browser sign-in and detects completion automatically. Openbase Cloud skips this stage.
5. Configure voice keys when needed — appears only after choosing provider-key audio through developer or advanced setup. The normal Openbase Cloud path is already configured.
6. Sign in to Openbase — always required to link the Mac and phone and provide managed voice audio. The app opens browser OAuth and detects completion automatically.
7. Get Openbase on your phone — scan a QR code to open the downloads page, install the iPhone or Android app, and sign in with the same account. You can skip phone setup.
8. Pair devices privately — connect the selected Openbase transport on the Mac and phone, then register the Mac so the phone can find it. Openbase VPN bundles Netmesh (Openbase-operated Headscale plus Tailscale-compatible open-source clients), needs no Tailscale account, collects no VPN traffic or usage analytics, and sends no VPN analytics to Tailscale. Its full-device route enables every feature, including opening agent-created websites in the phone browser. Publish those sites with openbase-coder service publish <name> <port> so the agent gives you a tailnet URL instead of unusable phone-side localhost. Openbase Direct carries Openbase app traffic without a VPN but cannot expose those sites to other phone apps. You can skip pairing.
9. Verify — confirms the local service, voice configuration, and Openbase login. Technical health URLs, versions, diagnostics, and CLI maintenance actions stay under Advanced.

The normal Openbase Cloud flow has one authentication stage: Openbase sign-in. Bringing your own Codex or Claude Code adds exactly one provider sign-in, for two stages total. Setup does not add a separate voice-provider sign-in.

Technical details are collapsed under Advanced throughout onboarding: raw commands and output, configuration paths, exit codes, manual fallbacks, and diagnostics. Advanced also identifies ~/.openbase as the runtime working directory; when setup is failing, open Terminal, run cd ~/.openbase, then launch codex or claude there and ask it to diagnose the failure. When macOS System Settings approval is required, onboarding shows an inline screenshot guide before opening the relevant settings page.

Prefer running these steps yourself from a terminal? Follow Manual Setup; the app detects completion and skips its own setup flow.

On your phone: the iOS and Android apps have the same mirrored onboarding flow ("Link Your Computer") that waits for your Mac to sign in and pair. See iOS App; the Android app pairs the same way.

The Dashboard¶

After setup the app shows two columns on the left:

• The rail — a narrow strip of icons for each destination (Dispatch, Threads, Projects, Reports, Approvals, Configure, plus any plugin pages). System pages (Status, Devices, Sync, Instructions, Tools, Services) sit behind the ⋯ More menu, which also shows the service-health summary; Cloud and Settings are pinned at the bottom. Any item except Settings can be hidden via Settings → Sidebar Items.
• The threads sidebar — a New thread entry, then a collapsible Projects section listing every project. Exactly one project is expanded at a time (the active project); click a project to expand it and collapse the previous one, or click it again to collapse it. Under the active project are the threads you have open in the sidebar, which work like terminal tabs: viewing a thread anywhere (the Threads page, a project page, a notification) adds it, New thread starts one in that project, Open thread… picks a recent thread of the project, and the × that appears on hover removes the row without archiving the thread. A running thread shows a green dot. Right-click a thread or project row to open it in a new tab or split pane. The toggle in the top bar (or Cmd/Ctrl+B) hides the threads sidebar; the rail stays. Which threads are open and which project is active are remembered per backend on this device. The footer shows the CLI version and an update indicator.

Overview¶

The home page. Shows up to three recent projects, your eight most recent threads, and a warning banner (with a link to Status) if required services are stopped.

On iPhone: there is no overview page; the iOS sidebar goes straight to Call, Threads, and the other tabs.

Projects¶

Browse every registered project with git branch and status badges. You can add a project by path, search projects, expand a project to see its worktrees and active threads, and create a new thread from a project row. Each project row links to its Diff, Reports, and Skills.

The project detail page shows the project's threads and reports and lets you remove the project from the recent list.

On iPhone: the iOS app does not browse projects directly, but the "New thread" button on the Threads tab creates threads from recent projects.

Threads¶

Threads are coding sessions. The Threads page lists them grouped by day with color-coded status badges (running, waiting, completed, failed). You can create a thread (choosing a project directory), star favorites, archive threads, and jump to sync conflicts when any are detected.

The thread detail page is the live coding view: real-time output streamed over WebSocket (stdout and stderr shown separately), a prompt box (Enter sends, Shift+Enter inserts a newline), a Stop button to interrupt the running turn, and the turn history.

On iPhone: the Threads tab has the same list (favorite via swipe-left, archive via swipe-right), and the thread detail shows turn history, live output, an interrupt button, and a prompt bar. During an active voice call the thread detail also offers Transfer Active Call to route voice to that thread.

Reports¶

Agents write Markdown reports into per-project .reports folders. The Reports page lists them across all projects grouped by date, with search and tag filtering. Open a report to read it, tag it, download it, or delete it.

Sharing a report: the Share button in a report's detail view publishes the report (with any images it references) to your Openbase Cloud account and lets you grant access to specific people by email. Recipients get an email and read the report at app.openbase.cloud under "Shared with me" after signing in with that email address — there are no public links, and every grant can be revoked. While a report stays shared, edits to the local file republish automatically; "Stop sharing" removes the cloud copy.

On iPhone: the Reports tab mirrors this — search, tag chips, date grouping, report detail with Markdown rendering, share sheet export, and delete. Report push notifications open the specific report.

Dispatch¶

A shared chat view of the voice dispatcher thread — the routing agent that answers voice calls and hands them to Super Agents. Use it to read what the dispatcher is doing and to type to it directly.

On iPhone: the Dispatch screen shows the same dispatcher thread, and the waveform button on the new-chat screen starts the call where you actually speak to it. See Voice Routing.

Approvals¶

Pending permission requests from running agents (commands, tool calls) with Accept and Decline buttons. The queue covers every computer you're signed in on: requests pending on another desktop appear with a device chip, and answering one goes directly to that computer. The page receives authenticated live snapshots from the local approval queue and refreshes the fleet-wide list every 5 seconds.

On iPhone: the Approvals tab shows the same queue with approve/deny buttons, and approval push notifications deep-link straight to it — so you can unblock an agent from anywhere.

Routines¶

Scheduled agent runs. Create a routine with a prompt (agent kind) or shell command (command kind), a daily time + timezone or an interval in seconds, an optional target thread (or a fresh thread per run), working directory, model, and reasoning effort. Routines show their last run status and next run time, and can be edited, disabled, run immediately, or deleted.

The Loops list shows loops from every computer you're signed in on: a loop that lives on another desktop appears with a device chip, and editing, running, or deleting it acts directly on that computer. Creating a loop always targets the computer serving the page you're on.

The Templates tab is browse-only. It shows prompts, commands, schedules, and required skills from the managed registry, but never creates or schedules a routine. Create a routine explicitly from the Loops tab after reviewing a template.

On iPhone: routines are not managed from the iOS app; use the desktop app, the console, or openbase-coder routines ....

Skills¶

Browse installed agent skills, the Openbase catalog, and the Printing Press catalog. An Openbase catalog skill is installable only when its Django-admin registry entry pins a GitHub repository, full commit SHA, safe subdirectory, and optional SKILL.md digest. The confirmation dialog shows that provenance and the selected agent homes; installation never runs catalog dependencies or scripts. Existing skills with the same name are treated as conflicts rather than overwritten.

You can edit installed skill sources here. The Skill settings link jumps directly to Settings → Agents → Skills, where sharing controls live:

• Symlink my skills across backends (Codex/Claude Code) adds missing links between the personal, Codex, and Claude Code skill directories. Existing files and conflicting links are never replaced. Turning it off stops new automatic links and preserves existing links.
• Sync my skills across devices shares ~/.agents/skills and linked skill-source folders under your home directory through device sync. Turning it off removes only the personal skill-folder share and source-folder shares added by this setting; files and independently configured folder shares remain. An explicit off preference prevents peers from re-enabling these shares. Enabling requires a second paired computer when device sync is not already enabled. Existing personal skill-folder shares appear as enabled.

These two settings are independent and initially off on a fresh installation. Plugin caches and backend credentials are not included.

On iPhone: skills are not managed from the iOS app.

Memories¶

Browse the persistent memories your coding agents have saved on this machine, grouped by source: Claude Code keeps per-project memory files (shown as one group per project), and Codex keeps global memories. Open a memory to read it; file-backed memories can be edited or deleted — deleting one also removes its line from the project's MEMORY.md index — while Codex per-thread memories are read-only.

On iPhone: memories are not managed from the iOS app.

Templates¶

BoilerSync project templates. Import the featured Openbase community templates or add any public GitHub template repository, remove local repository checkouts, browse templates by source, and inspect a template's fields (variables and options). The featured repository is optional: dismiss its suggestion on the Templates page, or restore the suggestion under Settings → Interface.

On iPhone: not available; templates are tied to the local filesystem.

Status¶

Service health for the local runtime: each required and optional check has one healthy/unhealthy result with its port or URL. The Netmesh/Tailscale connection, Openbase API Serve route, and LiveKit Serve route are separate checks; the Status page reads the configured routes without asking the local API to reach itself through Serve. It auto-refreshes every 30 seconds. The corresponding command-line diagnostics are available from openbase-coder services status.

On iPhone: the iOS app shows a warning banner when the local runtime is unreachable, and its Console tab can open this Status page in the embedded browser.

Devices¶

Scans your private network and lists Openbase hosts (name, OS, private IP, Openbase URL, online status) alongside other tailnet devices.

On iPhone: Settings → Backend Host has a matching Discover Tailnet Hosts action for picking which Mac the phone talks to.

Instructions¶

Edit the agent instruction documents for each target: the Openbase base instructions (~/.openbase/instructions/AGENTS.md, delivered to every Openbase session on both backends), your own Codex home AGENTS.md (~/.codex/AGENTS.md, which applies to all Codex sessions including Openbase's), direct LiveKit voice sessions, Super Agents, and the dispatcher.

On iPhone: not available.

Tools¶

Inventory of installed uv tools with versions, environments, and executables; the detail page shows per-executable help and can uninstall a tool.

On iPhone: not available.

Launchctl¶

A manager for macOS launchd services: status, plist details, load/unload, and logs, with Openbase-managed services flagged. An ignore list (Settings → Ignored Launchctl) keeps unrelated services out of view.

On iPhone: not available.

Settings¶

The Settings page groups configuration into sections:

• Openbase Services — start/stop/restart the managed services.
• Coding Backend — switch between Codex, Claude Code, and Openbase Cloud (same setting as openbase-coder backend use ...). The app warns before changing it, then restarts Openbase services and recreates the dispatcher automatically.
• Backend Model, Service Tier, Reasoning — model and reasoning defaults for agents (same as openbase-coder defaults ...). Service tiers (Fast mode) apply to the Codex backend only; on Claude Code the tier cannot be set and turns always run at the standard tier. Reasoning levels apply to both backends and are the Claude speed/quality knob. Fresh Openbase Cloud installs show Claude Haiku as the default for both dispatcher and Super Agents. The model catalog disables models that the account cannot run as named. Free and trial accounts can select Haiku; Sonnet, Opus, and Fable require a paid plan. Older Sonnet configurations retain a Haiku compatibility fallback.
• LiveKit Companion Screen Sharing (desktop app only) — see below.
• Voice Model — which model listens and speaks on calls, picked like the agent model: GPT-Live 1 (the default; a full-duplex model that listens and speaks at the same time while Super Agents do the work) or Classic pipeline (speech-to-text, then the agent's turn, then text-to-speech). GPT-Live runs through Openbase Cloud with your Openbase account; no API key is needed. Changes apply to the next call. Same setting as openbase-coder defaults voice-model.
• Dispatcher Voice — TTS/STT provider and voice selection, voice API keys, local model downloads, and a "Recreate LiveKit thread" action. These providers drive the Classic pipeline only; when GPT-Live is the voice model they stay editable but are marked "Classic pipeline only".
• Ignored Launchctl — services to hide from the Launchctl page.
• Authentication — login status and sign out.
• Agent Instructions — auto-generation options for instruction files.
• Dangerous Confirmation — toggle confirmation dialogs for destructive actions.
• Sidebar Items — show/hide sidebar entries.
• Environment Variables — edit env vars used by services.

On iPhone: iOS Settings covers the phone-side equivalents: account and security (email, password, two-factor, sessions), backend host selection, dispatcher voice picker, call audio behavior (mute sounds, muted-call music, concurrent-agent threshold), and diagnostics log upload.

Screen Sharing (LiveKit Companion)¶

The desktop app bundles a small companion app that shares your Mac's display into the active voice call, so the agent, your phone and the console can see your screen. You start it by asking the agent during a call ("share my screen", "show me the screen"): the agent runs openbase-coder desktop screen-share start, and the live screen appears on your phone or in the console on its own. Settings → LiveKit Companion Screen Sharing keeps a Test Share Screen button for checking the companion on its own.

macOS asks for two permissions the first time, both for OpenbaseScreenShareCompanion under System Settings → Privacy & Security: Screen & System Audio Recording to share the display, and Accessibility to accept clicks and typing. If sharing fails, the phone or console shows which one to grant; grant it and tap Share screen again. The companion needs a fresh launch after a Screen Recording grant, which the next start does for you.

Stopping is real. Stop on the phone or console, hanging up, the app going to the background, or a dropped connection all end the capture on the Mac: the companion stops recording, remote control is torn down, and the purple recording indicator in the menu bar goes away. The Mac also ends a share on its own about ten seconds after the last viewer leaves. You can also ask the agent to stop sharing.

On iPhone and Android: the shared screen appears as a card in the call with a Stop button; tap the card for full screen, pinch to zoom, and tap Remote for a trackpad, keyboard and scroll strip that control the Mac. In the console: the Call page shows the screen with Stop sharing; Remote control lets you click, type and scroll on the video directly.

Auto-Update¶

Packaged builds check for updates automatically. When an update has downloaded, a dismissible corner notice appears with a Restart to update button; failures show a similar dismissible error notice. Development builds never auto-update. The CLI runtime updates separately via self-update, and the dashboard footer shows a yellow dot when a CLI update is available (red when required).

The desktop checks again every six hours while it stays open. Failed checks or downloads retry after one minute with increasing delays capped at fifteen minutes; a downloaded update remains ready for a guarded restart or quit. Incomplete cached archives are discarded and downloaded again. Checks and retries remain disabled for developer installations.

Locally packaged developer builds and desktops serving a developer workspace also disable manual release checks, release installation on quit, bundled CLI activation, and automatic VPN-helper replacement. A missing workspace CLI is reported instead of falling back to an older standalone installation.

On your phone: iOS updates arrive through TestFlight/App Store; Android updates arrive as a new APK from Downloads.

Deep Links¶

The app registers the openbase-coder:// URL scheme, used for OAuth callbacks (openbase-coder://login-complete) and post-subscription flows. Links received while the app is closed are queued and handled at launch.

Where Things Live¶

The app stores Electron state under ~/Library/Application Support/@openbase/coder-desktop and activates the bundled CLI under ~/.openbase/packages/standalone/. See Files and Paths for the full runtime layout and Uninstall for removal.