# 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](#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](../adr/0004-zeron-desktop-is-canonical.md) (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](./CONSOLE_GUIDE.md) 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](./COMPANY_OS_START_HERE.md) 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](./DESKTOP_RELEASE_RUNBOOK.md). ### Run it from a source checkout ```bash ./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](./COMPANY_OS_AGENT_CHAT_LAUNCH.md) 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](../../external/company-os-desktop/COMPANY_OS_FORK.md). ## 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](./DESKTOP_CONNECTOR_SIGN_IN.md). 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](./DESKTOP_COMPUTER_CONTROL.md). ## 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](./COMPANY_OS_START_HERE.md): the desktop workflow and the Console - [Company Console guide](./CONSOLE_GUIDE.md) - [Connect agents](./CONNECT_AGENTS.md) and [CLI reference](./CLI_REFERENCE.md) - [Canonical product path](./CANONICAL_PRODUCT_PATH.md)