Company OS desktop app

Company OS desktop is the native macOS application for working with a company through Company OS. It is a window into a Company OS host, not a second company database.

Status. The desktop app is a preview. The packaged build is not published, is not notarized, and the desktop release gate is blocked. See Download and install status.

What it is

• The customer desktop shell is the Zeron-based native GPUI application built from external/company-os-desktop/apps/zeron as the company-os-desktop binary. It is the only customer shell. This was decided in ADR 0004 (2026-09-16); the earlier GPUiX port (apps/gpuix/) is abandoned and is not a product surface.
• Names on disk: macOS bundle Company OS.app, bundle id com.hsmii.companyos.desktop, data directory ~/.company-os-desktop.
• The Company Console in a browser remains the internal and operator web UI. It is not a fallback update channel for the desktop.

Authority and local cache

Company OS is authoritative for companies, principals, permissions, tasks, approvals, evidence, receipts, and terminal outcomes. The desktop's local store is a viewport and session cache only; Company OS objects are projected into it and are not written as business truth.

• Bearer and principal tokens stay in the authenticated host. They are not placed in ACP frames, process arguments, transcripts, or the local cache.
• An approval is never granted in the desktop. When policy requires one, the app shows Authorization required with the options Review in Company OS and Cancel governed work. The signed decision returns through Company OS.
• Sessions and their local records survive an app restart. Company OS remains the record for company tasks, approvals, evidence, and outcomes.
• If the app stops safely with Authorization required, ask the Company OS administrator to connect the company and your authority. Do not switch to an ungoverned runtime.

Download and install status

The download page copy (web_interface/company-os-site/pages.json, key download) says:

Item	Exact text
Page title	"Download Company OS Desktop"
Status label	"Preview build not yet published"
Status note	"The packaged desktop build will appear here as soon as it is published to this site. Until then, use the Company Console or build the app from source."
Platform	"Apple silicon, macOS 12 or later"
First launch	"This preview build is not notarized. On first launch, right-click the app and choose Open."

When a build is published, the page shows these steps: open Company OS.dmg, drag Company OS into Applications and launch it, then "The Company Passport commissions your first company. Then pick a template and hand off the first task."

No published release manifest is in web_interface/company-os-site. ADR 0004 records the download manifest as published: false and states that no Developer ID signing or notarization is configured (the packaging script ad-hoc signs unless CODESIGN_IDENTITY is set) and that no clean-machine lifecycle evidence exists. Start here describes the desktop as a native preview, "not a verified public App Store or notarized-download release". The release evidence procedure is in Desktop release runbook.

Run it from a source checkout

./company-os desktop

This starts or reuses the local stack through the Zeron app, waits up to 30 seconds for the API, the AgentChat health route, and the Workspace page, then opens Company OS.app and the Workspace URL. If no app is installed, a source checkout builds and packages a local preview app. The source-preview bundler supports macOS on Apple silicon only. See Workspace and chat launch for ports and failure output.

First launch and autostart

When the app opens it starts or reuses the Company OS service:

Situation	What the app does	On quit
The API is already healthy	Attaches to it.	Leaves it running.
A source checkout is known (HSMII_HOME)	Starts scripts/company-os --no-open.	Stops it only if this app started it.
No source checkout	Runs the published installer, which pulls, provisions, and starts a Docker stack.	The stack keeps running; only an installer still mid-run is stopped.

Set COMPANY_OS_DESKTOP_AUTOSTART to 0, false, or off to stop the app from starting a service. Use this when an operator owns the service lifecycle separately. It does not enable local provider execution. Other values leave autostart on.

The first run is a guided sequence: Company, Identity, Model, Proof task, Receipt, then complete. Each step is derived from Company OS authority and setup-readiness receipts; a local button click does not advance it. Technical build and authority details are in the desktop fork note.

Main surfaces

The sidebar has Home, Lessons, Workflows, Agents, Skills, and Connectors. These are projections of Company OS records; the app does not create a local task database.

Home

Home opens on "What needs you today?" with the tabs Today, Bots, Company overview, Company AgentChat, Model chat, Beads, and Traces.

• Today lists work that needs you and a composer to start new work.
• Company AgentChat starts a governed Company OS chat on the harness and model you choose in the model picker. It uses the same run pipeline as a new chat from the composer.
• Bots lists Company OS bots. Its bottom bar has Bots, AgentChat, Sessions, and Tasks. Chatting with a bot opens a durable local 1:1 chat. In group rooms, each visible agent reply comes from a Company OS task run for that room member.
• Beads and Traces show the task graph and the tenant-scoped trace explorer (flight-recorder table, span drill-down, and fleet questions).

Chat, harnesses, and models

The default harness is Company OS. Codex, Claude Code, Pi, and Oh My Pi are separate picker choices, and OpenRouter models are selected inside a harness. Each is admitted as its own Company OS provider run, so identity, policy, scoped tools, approvals, memory, and receipts stay outside the provider runtime.

• The production desktop has no direct provider mode. The legacy COMPANY_OS_DESKTOP_RUNTIME variable is ignored.
• The governed provider lane needs the installed company-os-provider-broker (or the path in COMPANY_OS_PROVIDER_BROKER_EXECUTABLE). A missing or invalid broker is shown as unavailable; the app does not fall back to a direct CLI.
• A Governed subagents option is Off by default. Turning it on grants only the signed company_os_delegate_subagent capability for that run. Delegation creates a Company OS child task and run; a provider's native Task or subagent action stays refused.
• Cursor, Grok, Hermes, and local OpenAI-compatible servers are not available in the customer desktop until a governed broker adapter exists.
• Installed harnesses are managed per device in Settings → Providers.

For a run to count as using Company OS, it must have a Company OS run identity and a durable receipt. A local harness session outside this boundary is not evidence that Company OS operated the company.

Connectors and account sign-in

Connectors → Accounts links a provider account: select an app such as Outlook or Gmail, press Connect, approve access with the provider in the system browser, and return to the account shown in Company OS. This flow does not open the localhost Console. Check again only re-checks availability and never starts OAuth; Administrator details lists the missing server configuration. Custom MCP servers and other integration setup are under Advanced.

Company OS owns OAuth state, code exchange, scope validation, encrypted credentials, refresh, and receipts; tokens never appear in the UI. The administrator registers the provider's OAuth app once per installation. The connected account apps expose 24 read-only native tools; none send, modify, delete, or publish. Registration steps, environment variables, and the recorded verification status are in Desktop connector sign-in. That document's September 7 record notes that live provider consent, token refresh, and API reads were not verified.

Computer control

Computer control lets an admitted provider run observe and act on allowed local macOS apps through a separate desktop MCP process and a pinned native helper. It is off unless the desktop host's launch environment sets COMPANY_OS_DESKTOP_COMPUTER_CONTROL=1 and the backend has a configured adapter for the same company and the exact principal. The helper requires macOS 14 or newer, needs Accessibility and Screen Recording granted by the operator, and the installed allowlist starts with TextEdit only.

Two limits apply. The Computer control status panel was built in the abandoned GPUiX shell and does not exist in the Zeron app yet. And the governed TextEdit action test and a provider-driven chat proof were recorded as not run, blocked by macOS permissions. Setup, the stop file, and the permission command are in Desktop computer control.

For developers

external/company-os-desktop is the canonical desktop directory. It is a fork of zeronsh/comet (MIT) pinned to a specific upstream commit; the toolchain is pinned to Rust 1.97.0. Build with cargo build --release -p company-os-desktop from that directory, and package with scripts/package-macos.sh.

Inside it, apps/gpuix/ is abandoned (ADR 0004). Other directories named external/company-os-desktop-* sit beside it in the checkout; no repository document designates them as product surfaces, so build and ship from the canonical directory only.

Related

• Start here: the desktop workflow and the Console
• Company Console guide
• Connect agents and CLI reference
• Canonical product path