diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..c8864445 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,35 @@ +name: Bug report +description: Something is broken in Cortex Desktop (alpha) +labels: [bug] +body: + - type: markdown + attributes: + value: | + Cortex Desktop is alpha software. Never paste API keys, tokens, cookies or private paths. Report security issues privately, see SECURITY.md. + - type: textarea + id: what + attributes: + label: What happened? + description: What you did, what you expected, what you saw. + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + validations: + required: true + - type: input + id: version + attributes: + label: Commit or version + placeholder: git rev-parse --short HEAD + validations: + required: true + - type: input + id: os + attributes: + label: OS and architecture + placeholder: macOS 26, arm64 + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..3ba13e0c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..f2df5e6d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,21 @@ +name: Feature request +description: Suggest an improvement +labels: [enhancement] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What are you trying to do, and what gets in the way? + validations: + required: true + - type: textarea + id: idea + attributes: + label: Proposed solution + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered diff --git a/AGENTS.md b/AGENTS.md index 4ee9dd03..52f21b58 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -198,7 +198,7 @@ handoff and main-only implementation sequence are tracked in [`docs/connection-m | Command | Does | | --- | --- | | `bun run build` | `build:app` (Vite → `packages/app/dist`) + `build:desktop` (esbuild → `packages/desktop/dist/{main,preload}.cjs`) | -| `bun run start` | `electron .` (needs a build). Headless Linux: `DISPLAY=:1 bun run start -- --no-sandbox` | +| `bun run start` | `electron .` (needs a build). Headless Linux: `xvfb-run -a bun run start` (keep the sandbox; only e2e tests pass `--no-sandbox`) | | `bun run dev:app` | Vite on `:5299`, proxies `/api` to `:5298` | | `bun run dev:api` | Engine on `:5298` for the browser dev loop (in-memory keys) | | `bun run typecheck` | `tsc -p tsconfig.json` | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c073626f..63682873 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to Cortex -Bun workspaces monorepo; Electron 44 desktop app; React 19 renderer; local engine in main. +Cortex Desktop is alpha software. It's a Bun workspaces monorepo: Electron 44 desktop app, React 19 renderer (Base UI, Vite 8), local engine in main. Setup and docs: [docs/README.md](./docs/README.md). Read [AGENTS.md](./AGENTS.md) and [`.rules/`](./.rules/) first. Keep changes small, typed, and tested. @@ -73,4 +73,4 @@ issues, PRs or logs. ## Questions -GitHub Issues for bugs; Discussions for design questions when enabled. +Use [GitHub Issues](https://github.com/CortexLM/desktop/issues) with the bug and feature templates. Source copy is English; other locales come from `node scripts/translate-locales.mjs`. diff --git a/README.md b/README.md index 8d7b0f6f..27187b7f 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,160 @@ -# Cortex +

Cortex Desktop

-Cortex desktop: Chat, Work, Bots, Files and Cortex Code on a local agent engine. +

+ + + Real macOS screenshot of the Cortex Desktop window in dark theme: sidebar and a conversation with the Nova Bot, with message bubbles and typing dots (demo data) + +

-One Electron 44 app. The engine runs inside the app's main process, stores sessions and -settings in local SQLite (`node:sqlite`), and talks to the model providers you configure. -Provider keys use a separate main-process credential store. No account is needed. -Cortex Cloud (`cortex.foundation`) and self-hosted settings save a preference, probe servers -and support email-code sign-in through main. Sign-in lasts until Cortex closes; prompts -still use the local engine and configured providers. +

+ The desktop app for Chat, Work, Bots and Code, built on an agent engine that runs on your machine. It's for people who want to talk to models they choose, keep their sessions and keys local, and optionally sign in to Cortex Cloud for Bots and remote workspaces. +

-## Quick start +

+ license Apache-2.0 + version 0.2.0 + status alpha + Electron 44 + React 19 + Bun 1.4 + platforms macOS, Windows, Linux + CI +

+ +

+ Documentation · + Website · + Getting started · + Configuration · + Architecture · + Connection modes · + Providers · + Testing · + Contributing · + Security · + License +

+ +> [!WARNING] +> **Alpha, not stable.** Cortex Desktop is under active development: screens, settings and stored data can change or break between commits, and nothing is guaranteed to be stable. Builds are **unsigned** (no code signing, no notarization). Do not use it in production or for anything you can't afford to lose. + +--- + +## What is Cortex Desktop + +Cortex Desktop is one Electron app. The agent engine lives in the app's main process, keeps sessions and settings in local SQLite (`node:sqlite`) and calls the model providers you configure. You don't need an account. + +Three ideas hold it together: + +1. **The engine is local.** Sessions, tools, permissions, MCP servers and skills run on your machine. The renderer is sandboxed and only talks to the engine through a small preload bridge. +2. **Keys stay in the main process.** Provider keys go into a separate credential store. They are write-only from the UI, and the renderer only ever sees the last four characters. +3. **Cloud is optional.** Sign in to Cortex Cloud (or a self-hosted server) with an email code to use Bots and the signed-in Work, Chat and Code screens. Local mode keeps working without it. + +The banner is a real screenshot of the app: an unedited native macOS window capture (`screencapture -l` on macOS 26.6.2, Electron 44, dark theme, English), taken as is with the native window shadow and no mockup or recomposition. The Bot conversation is live code, but the screenshot feeds it **demo data**: a made-up Bot named Nova and invented messages, instead of a real Cortex Cloud account. No keys, emails or private paths appear. + +## How it works + +The renderer is a sandboxed React app. It never opens a socket and never sees a key: it calls `window.cortex`, a small preload bridge, which forwards requests over IPC (`cortex:fetch`) to the engine's route table in the main process, and events come back as a stream. Provider calls and the optional Cortex Cloud connection are made from the main process, and keys live in a separate credential store there. Details: [docs/architecture.md](./docs/architecture.md). + +In the Bot conversation (signed in), you send a message and the Bot runs a job while typing dots show. If a tool needs permission it waits as a pending approval in the thread: Allow once lets it run, Deny skips the tool. Only safe metadata crosses to the renderer. See [AGENTS.md](./AGENTS.md) and [docs/connection-modes.md](./docs/connection-modes.md) for the exact contract. + +--- + +## Features + +What works today (see [Status](#status) for the exact boundaries): + +- **Chat** on the local engine, streaming, with reasoning and image input for models that support them. +- **Work** tasks and approvals. +- **Bots** with mascots and an iMessage-style conversation. These screens need a Cortex Cloud sign-in. +- **Cortex Code** on a local folder. +- **Providers and models** from the public [models.dev](https://models.dev) catalog (Anthropic, OpenAI, Google and OpenAI-compatible endpoints). +- **MCP servers**, skills (a `summarize` skill ships in [`skills/`](./skills)) and optional [computer use](./docs/computer-use.md). +- **Eight locales** (`en fr es de ja zh-Hans pt-BR ko`), English by default, dark and light themes. + +## Install + +There are no signed releases yet. Build from source. + +You need [Bun](https://bun.sh) 1.4 and Node 22 or newer. ```bash +git clone https://github.com/CortexLM/desktop.git +cd desktop bun install node node_modules/electron/install.js # Bun skips Electron's postinstall bun run build -bun run start # headless Linux: DISPLAY=:1 bun run start -- --no-sandbox +bun run start ``` -Then Settings → Providers & models: pick a provider, paste your key. +On a Linux machine without a display, install Xvfb and run `xvfb-run -a bun run start`. Keep the Chromium sandbox on: if Electron refuses to start because `chrome-sandbox` is not set up, run `sudo chown root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox`. Only the automated Linux end-to-end tests pass `--no-sandbox` (see [`tests/e2e/fixtures.ts`](./tests/e2e/fixtures.ts)); never use it for normal use. -Renderer-only loop in a browser: +### Unsigned packages ```bash -bun run dev:api # engine on :5298, in-memory keys -bun run dev:app # Vite on :5299, proxies /api +bun run pack # unpacked app in dist/, current platform +bun run dist:mac # macOS dmg and zip (x64 and arm64) ``` -## Layout +`electron-builder.yml` also defines Windows (NSIS installer and portable, x64) and Linux (AppImage and deb, x64) targets. CI builds unsigned packages only. -``` -packages/ - schema/ zod contracts (browser-safe) - core/ local engine: storage, bus, catalog, providers, sessions, tools, - permissions, agents, skills, plugins, MCP, bots, scheduler, space, - connection, computer use - protocol/ Hono route table + validation - server/ createServer(core) → app.fetch - client/ typed fetch client + SSE parser - i18n/ catalogs (locales//.json) and loaders - app/ renderer: React 19, @base-ui/react, Vite 8 - desktop/ Electron main + preload, credentials, menu, remote probe and sign-in -vendor/ @cortex/sdk and @cortex/api-types tarballs -tests/ unit/ and e2e/ (Playwright + Electron) -scripts/ i18n audit, translation, smoke test, design comparison, Mac capture -``` +| Platform | Notes | +| --- | --- | +| macOS | Unsigned. Gatekeeper will block the first launch; right-click the app and choose Open, or run `xattr -dr com.apple.quarantine /path/to/Cortex.app`. | +| Windows | Unsigned installers show a SmartScreen warning. | +| Linux | AppImage and deb. Credential encryption needs a keyring; without one the app refuses to persist cloud sign-in. | + +--- + +## Quick start + +1. Start the app (`bun run start`). +2. Open **Settings, Providers and models** and pick a provider. +3. Paste your API key. It is write-only: the app only keeps the last four characters for display. +4. Choose a model and start a chat. + +More in [docs/getting-started.md](./docs/getting-started.md). + +--- + +## Configuration -## Checks +- **Providers:** [docs/providers.md](./docs/providers.md). +- **Connection modes** (local, Cortex Cloud, self-hosted): [docs/connection-modes.md](./docs/connection-modes.md). Pick one in Settings, Connection. +- **Overview and environment variables:** [docs/configuration.md](./docs/configuration.md). + +## Keyboard basics + +| Shortcut | Action | +| --- | --- | +| `Cmd/Ctrl+N` | New chat | +| `Cmd/Ctrl+K` | Command palette | +| `Cmd/Ctrl+B` | Toggle sidebar | +| `Cmd/Ctrl+,` | Settings | +| `Cmd/Ctrl+[` and `Cmd/Ctrl+]` | Back and forward | +| `Cmd/Ctrl+/` | Shortcuts | + +--- + +## Architecture + +| Package | Role | +| --- | --- | +| `packages/schema` | zod contracts, browser-safe | +| `packages/core` | Local engine: storage, providers, sessions, tools, permissions, agents, skills, MCP, bots, scheduler | +| `packages/protocol` | Hono route table and validation | +| `packages/server` | `createServer(core)`, called as `app.fetch` | +| `packages/client` | Typed fetch client and SSE parser | +| `packages/i18n` | Catalogs per locale and namespace | +| `packages/app` | Renderer: React 19, Base UI, Vite 8 | +| `packages/desktop` | Electron 44 main and preload, credentials, menu, Cloud probe and sign-in | + +`vendor/` holds the vendored SDK tarballs, `tests/` holds unit and Playwright suites, `scripts/` holds the i18n audit, smoke tests and Mac capture tools. Details: [docs/architecture.md](./docs/architecture.md). + +--- + +## Development ```bash bun run lint @@ -56,29 +164,56 @@ bun run audit:i18n bun run build && bun run test:e2e ``` +Renderer only, in a browser: + +```bash +bun run dev:api # engine on :5298, in-memory keys +bun run dev:app # Vite on :5299, proxies /api +``` + +Read [AGENTS.md](./AGENTS.md) and [`.rules/`](./.rules/) before you change code. Testing details: [docs/testing.md](./docs/testing.md). + +--- + ## Status -- Live: Chat, Work tasks and approvals, Bots, Cortex Code on a local folder, Settings → - Providers & models; Connection selection, probing and process-lifetime email-code sign-in. -- Preview only: file viewers and other screens without engine wiring (see `#/gallery`). -- Not built yet (waiting on design): Space, Scheduled, Plugins & skills, additional sign-in - continuation screens. Remote prompt routing remains pending. -- Catalogs and preview fixtures exist for `en fr es de ja zh-Hans pt-BR ko`; builtin - `summarize` ships in `skills/`. -- E2E covers 426 registered theme/state renders and UI streaming through a **local fake - provider**. Separate [real image/reasoning evidence](evidence/real-provider.json) and - [native Mac captures](evidence/mac/README.md) exist; [full acceptance remains incomplete](evidence/STATUS.md). -- Release and code signing are not configured; CI builds unsigned packages only. +- Live: Chat, Work tasks and approvals, Bots, Cortex Code on a local folder, Settings, Providers and models, connection selection with probing and email-code sign-in. +- Preview only: file viewers and other screens without engine wiring (open `#/gallery` in a preview build). +- Not built yet (waiting on design): Space, Scheduled, the Plugins and skills management screen, extra sign-in continuation screens. Remote prompt routing is pending. +- Sign-in lasts until Cortex closes. Prompts still use the local engine and the providers you configured. +- Acceptance is incomplete: see [evidence/STATUS.md](./evidence/STATUS.md). + +--- ## Documentation -- [AGENTS.md](./AGENTS.md) and [`.rules/`](./.rules/) — read before contributing -- [CONTRIBUTING.md](./CONTRIBUTING.md) · [SECURITY.md](./SECURITY.md) · [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) -- [docs/architecture.md](./docs/architecture.md) · [docs/engine.md](./docs/engine.md) · [docs/providers.md](./docs/providers.md) -- [docs/connection-modes.md](./docs/connection-modes.md) · [docs/i18n.md](./docs/i18n.md) · [docs/testing.md](./docs/testing.md) · [docs/computer-use.md](./docs/computer-use.md) -- [packages/core/README.md](./packages/core/README.md) · [vendor/README.md](./vendor/README.md) +Start at [docs/README.md](./docs/README.md). Highlights: [Getting started](./docs/getting-started.md), [Configuration](./docs/configuration.md), [Troubleshooting](./docs/troubleshooting.md), [FAQ](./docs/faq.md), [Architecture](./docs/architecture.md). + +## FAQ + +**Is it safe to use for real work?** It's alpha. Try it, don't depend on it. See the [FAQ](./docs/faq.md). + +**Do I need an account?** No. Local mode works without one. + +**Where is my data?** In the app's data directory, in local SQLite. Keys are in a separate credentials file with restricted permissions. + +**Why is the app unsigned?** Release signing isn't set up yet. + +--- + +## Contributing + +Issues and pull requests are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md). Use the issue templates for [bugs](https://github.com/CortexLM/desktop/issues/new?template=bug_report.yml) and [features](https://github.com/CortexLM/desktop/issues/new?template=feature_request.yml). + +## Security + +Report vulnerabilities privately, as described in [SECURITY.md](./SECURITY.md). Don't open a public issue for them. + +## Community + +- [Issues](https://github.com/CortexLM/desktop/issues) for bugs and requests. +- [CortexLM on GitHub](https://github.com/CortexLM) for the other repositories. ## License -Copyright 2026 Cortex Foundation / CortexLM. Licensed under the -[Apache License, Version 2.0](./LICENSE). Third-party notices are in [NOTICE](./NOTICE). +Apache-2.0, see [LICENSE](./LICENSE) and [NOTICE](./NOTICE). Copyright 2026 Cortex Foundation / CortexLM. diff --git a/SECURITY.md b/SECURITY.md index 454397af..eee259d6 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,7 @@ # Security policy +Cortex Desktop is alpha software, not recommended for production. Builds are unsigned. + ## Report a vulnerability Email **security@cortex.foundation** (or open a **private** GitHub security diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..1208b1c4 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,27 @@ +# Cortex Desktop documentation + +> [!WARNING] +> **Alpha software.** Cortex Desktop is not recommended for production use. Features can change or break between commits, nothing is guaranteed to be stable, and builds are **unsigned** (no code signing, no notarization). Back up anything you care about and expect rough edges. + +## Start here + +- [Getting started](./getting-started.md): build, run, add a provider. +- [Configuration](./configuration.md): providers, connection modes, environment variables. +- [Troubleshooting](./troubleshooting.md) +- [FAQ](./faq.md) + +## Reference + +- [Architecture](./architecture.md): processes, packages, build. +- [Engine](./engine.md): the local agent engine. +- [Providers and models](./providers.md) +- [Connection modes](./connection-modes.md) +- [Bot calls](./bot-calls.md) +- [Computer use](./computer-use.md) +- [Internationalization](./i18n.md) +- [Testing](./testing.md) +- [Staging release](./staging-release.md) + +## Project + +- [README](../README.md), [CONTRIBUTING](../CONTRIBUTING.md), [SECURITY](../SECURITY.md), [AGENTS.md](../AGENTS.md) diff --git a/docs/assets/banner-light.png b/docs/assets/banner-light.png new file mode 100644 index 00000000..deffd92d Binary files /dev/null and b/docs/assets/banner-light.png differ diff --git a/docs/assets/banner.png b/docs/assets/banner.png new file mode 100644 index 00000000..a411159f Binary files /dev/null and b/docs/assets/banner.png differ diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..e933ce5e --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,33 @@ +# Configuration + +> [!WARNING] +> **Alpha software.** Cortex Desktop is not recommended for production use. Features can change or break between commits, nothing is guaranteed to be stable, and builds are **unsigned** (no code signing, no notarization). Back up anything you care about and expect rough edges. + +## Providers + +Configure providers in **Settings, Providers and models**. Keys are write-only and stored by the main process in `/credentials.json` (mode `0600`, encrypted with the OS keychain when available). Details: [providers.md](./providers.md). + +## Connection modes + +Settings, Connection chooses where the app connects: + +| Mode | What it means | +| --- | --- | +| Local | No Cortex account. Prompts use the local engine and configured providers, which may be remote. | +| Cortex Cloud | Probes the Cloud origin and signs in with an email code. Bots and signed-in Work, Chat and Code screens use the account. | +| Self-hosted | Same flow against a server you provide. | + +Prompts still use the local engine and your configured providers. Sign-in lasts until Cortex closes. Full contract: [connection-modes.md](./connection-modes.md). + +## Environment variables + +| Variable | Effect | +| --- | --- | +| `CORTEX_DATA_DIR` | Data directory (default: `engine` under the app's user data path) | +| `CORTEX_LOCALE` | Locale override, e.g. `fr` | +| `CORTEX_CATALOG_URL` | Override the models.dev catalog URL | +| `CORTEX_RENDERER_URL` | Load the renderer from a dev server | +| `CORTEX_START_HASH` | Open at a route, e.g. `#/gallery` | +| `CUA_DRIVER_PATH` | Path to the computer-use driver ([computer-use.md](./computer-use.md)) | + +Locale order: Settings choice, `CORTEX_LOCALE`, a supported system language, then English ([i18n.md](./i18n.md)). diff --git a/docs/connection-modes.md b/docs/connection-modes.md index 42f51da4..31062302 100644 --- a/docs/connection-modes.md +++ b/docs/connection-modes.md @@ -406,7 +406,7 @@ successor, precise account/history contract, historical-image hydration or exact import permission appears in that readback. Public instance remains404; model metadata still supplies zero vision-capable Chat models. -The [00:24 UTC successor readback](../evidence/text-live-followup/owner-readback-final/REPORT.md) +The 00:24 UTC successor readback (report not kept in this repository) independently verifies G2 `de3b9dd19baa4239ad5aba00da19b7955f053f37`, canonical blob `232505fc45ba2f506fa891383495592ea7f62de4`. All 422 operation shapes/IDs match the admitted G3 schema; only the VNC-description text differs. Canonical screenshot-schema reconciliation diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 00000000..de42ad5e --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,24 @@ +# FAQ + +> [!WARNING] +> **Alpha software.** Cortex Desktop is not recommended for production use. Features can change or break between commits, nothing is guaranteed to be stable, and builds are **unsigned** (no code signing, no notarization). Back up anything you care about and expect rough edges. + +**What is this?** A desktop app for Chat, Work, Bots and Code with a local agent engine. See the [README](../README.md). + +**Is it production ready?** No. It's alpha. Features change or break, and there are no stability guarantees. + +**Do I need an account?** No. Local mode needs only a provider key. + +**Which providers work?** Anthropic, OpenAI, Google and OpenAI-compatible endpoints from the models.dev catalog ([providers](./providers.md)). + +**Where are my keys?** In the main process credential store, never in the renderer. See [SECURITY.md](../SECURITY.md). + +**Why do Bots need sign-in?** Bot screens talk to a Cortex Cloud account. Local mode doesn't show them. + +**Which languages are supported?** `en fr es de ja zh-Hans pt-BR ko`. English is the default ([i18n](./i18n.md)). + +**Why unsigned builds?** Release signing isn't configured yet. + +**How do I report a bug or a vulnerability?** Bugs: GitHub issues. Vulnerabilities: privately, per [SECURITY.md](../SECURITY.md). + +**How do I contribute?** [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..c3c56b59 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,49 @@ +# Getting started + +> [!WARNING] +> **Alpha software.** Cortex Desktop is not recommended for production use. Features can change or break between commits, nothing is guaranteed to be stable, and builds are **unsigned** (no code signing, no notarization). Back up anything you care about and expect rough edges. + +## Requirements + +- [Bun](https://bun.sh) 1.4 and Node 22 or newer. +- macOS, Windows or Linux. Packages are unsigned. + +## Build and run + +```bash +git clone https://github.com/CortexLM/desktop.git +cd desktop +bun install +node node_modules/electron/install.js +bun run build +bun run start +``` + +Bun skips Electron's postinstall script, which is why the `install.js` step exists. On a Linux machine without a display, install Xvfb and run `xvfb-run -a bun run start`. Keep the Chromium sandbox on: if Electron refuses to start because `chrome-sandbox` is not set up, run `sudo chown root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox`. Only the automated Linux end-to-end tests pass `--no-sandbox` (see [`tests/e2e/fixtures.ts`](../tests/e2e/fixtures.ts)); never use it for normal use. + +## Add a provider + +1. Open **Settings, Providers and models**. +2. Pick a provider from the catalog. Anthropic, OpenAI, Google and OpenAI-compatible endpoints are supported ([providers](./providers.md)). +3. Paste your key. It goes to the main process and is never shown again, only its last four characters. +4. Pick a model and open a new chat (`Cmd/Ctrl+N`). + +The catalog comes from models.dev. Offline, the app falls back to its cached copy. + +## Packaging + +```bash +bun run pack # unpacked app in dist/ +bun run dist:mac # dmg and zip +``` + +## Develop on the renderer only + +```bash +bun run dev:api +bun run dev:app # http://localhost:5299 +``` + +## Next + +[Configuration](./configuration.md), [Troubleshooting](./troubleshooting.md), [CONTRIBUTING](../CONTRIBUTING.md). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..81d173de --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,22 @@ +# Troubleshooting + +> [!WARNING] +> **Alpha software.** Cortex Desktop is not recommended for production use. Features can change or break between commits, nothing is guaranteed to be stable, and builds are **unsigned** (no code signing, no notarization). Back up anything you care about and expect rough edges. + +**Electron fails to start after `bun install`.** Run `node node_modules/electron/install.js`. Bun skips the postinstall. + +**Blank window or sandbox error on Linux.** Without a display, run `xvfb-run -a bun run start`. For a `chrome-sandbox` error, give the helper its required owner and mode: `sudo chown root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox`. Do not disable the sandbox with `--no-sandbox`; only the automated Linux end-to-end tests use it. + +**macOS says the app can't be opened.** Builds are unsigned. Right-click, choose Open, or clear quarantine with `xattr -dr com.apple.quarantine /path/to/Cortex.app`. + +**Windows SmartScreen warning.** Installers are unsigned. Choose More info, then Run anyway. + +**Model list is empty.** The catalog loads from models.dev, then falls back to a cache. Offline with no cache, the engine reports `catalog_unavailable`. Reconnect and refresh. + +**A send is refused.** A missing, disabled or unsupported model refuses the send and keeps your draft. Pick another model in the chooser. + +**Cloud sign-in doesn't persist on Linux.** Persistence needs OS encryption (a keyring). Without it the session stays in memory. + +**Tests fail with a stale build.** Run `bun run build` before `bun run test:e2e`. + +Still stuck? Open an [issue](https://github.com/CortexLM/desktop/issues/new/choose) with your OS, app commit and steps. Never paste keys or tokens.