Coloride
Your code. Your Mac. One IDE.
English · 中文 · 日本語 · 한국어 · Español · Français · Português · Deutsch · Italiano
Open a folder and work with your code, terminals and browser on this computer. Nothing in that path calls a Coloride server.
Coloride is a trademark. The MIT license covers the source code, not the name, logo or domains.
What works today
Coloride runs on macOS with Apple Silicon.
- Edit code: file explorer, editor tabs, CodeMirror language support, completion, diagnostics, search and image previews.
- Run your project: local terminals with job control and sessions that stay up while the local host is alive.
- Preview your work: an embedded Chromium browser and pop-out windows. Localhost points to your computer.
- Start from a blank file: New File opens an untitled buffer. Closing it asks whether to save if you changed it.
Sign-in and the managed agent are off. coloride.dev points here until it has an API. SSH remote workspaces are still in the source and are not exposed in the interface. The roadmap records priorities, not finished work.
Checks
From the repository root, after the setup below:
corepack pnpm typecheck
core/ide-host/.venv/bin/python -m pytest core/ide-host/tests -q
UI and Electron checks are in tests/README.md. How to send a change is in CONTRIBUTING.md.
Start developing
Use Node.js 22, pnpm 9.15.4 and Python 3.12+ (CI uses 3.12). From the repository root:
python3.12 -m venv core/ide-host/.venv
core/ide-host/.venv/bin/python -m pip install -e 'core/ide-host[dev]'
corepack pnpm install --frozen-lockfile
corepack pnpm dev
This starts Vite and Electron, which starts or reconnects to the local Python host. No server provisioning is needed. React changes use Vite HMR. Electron main/preload changes require an Electron restart; a compatible persistent Python host is reused while terminal sessions are active. To load Python changes, close those terminal tabs and restart Electron. Do not terminate user sessions for validation.
Architecture
Electron desktop shell
├─ React UI: editor, explorer, terminals, browser, agent
└─ Authenticated local Python host (HTTP / WebSocket)
├─ Local files, PTYs, language servers and agent tools
├─ Configured model providers / optional cloud services
└─ Optional SSH/SFTP transport to a remote workspace
The Python host owns execution and terminal processes. The renderer consumes API responses and events. Agent tools pass through Coloride's policy and approval layer. The model/tool decision loop uses Coloride’s bundled turn scheduler; provider integration and workspace execution belong to Coloride.
| Directory | Responsibility |
|---|---|
client/ide |
React UI, CodeMirror editor, xterm terminals |
client/desktop |
Native shell, preload bridge, browser, host lifecycle, packaging |
core/ide-host |
Local FastAPI host, files, PTYs, language servers, agents, optional SSH |
packages/contracts |
API definitions and TypeScript contracts |
tooling/dev |
Development launch and environment setup |
tooling/build |
Sidecar and remote runner builds |
tooling/release |
Signing, release and publishing |
tooling/checks |
Structure checks, source audits and test runners |
artifacts |
Generated build caches, screenshots and test results (ignored by Git) |
tests/electron |
Isolated Electron integration and full-IDE smoke tests |
The renderer is grouped into src/app (composition), src/features (IDE functions) and src/shared (reusable code). Shared renderer modules must not depend on features or app composition, and features must not depend on app composition.
Documentation
| Guide | Contents |
|---|---|
| Contributing | Setup, placement, checks and pull requests |
| Phased roadmap | Objectives, scope and exit criteria for phases 0–12 |
| Tests | Suite folders, coverage and commands |
| Performance | Warm-start and file-open checks, and what is not measured |
| Local work | What works offline, and what a crash keeps |
| Security | Security boundaries, threat model and reporting |
Status
The project is licensed under the MIT License. The supported desktop target is macOS on Apple Silicon. Package versions are maintained in the root and Electron package.json files. Build configuration for other systems is not a statement of platform support.
Optional cloud services and community builds
Files, editing and local terminals work without an account. This repository ships
with cloud services disabled: client/desktop/src/cloud-config.json contains
enabled: false and empty endpoints. Run pnpm dev without additional cloud
configuration. Community installers inherit these defaults.
Forks operating a compatible cloud service can set appBase and apiBase in the
same file and enable cloud services explicitly. Runtime overrides are COLORIDE_CLOUD_ENABLED,
COLORIDE_CLOUD_APP_BASE (browser login) and COLORIDE_CLOUD_AUTH_BASE (API);
COLORIDE_CLOUD_API_BASE is an API alias. Endpoints must use HTTPS without embedded
credentials, query strings or fragments. An alternate server must implement the
existing device-login, account, product and managed-model API contracts.
Electron passes the resolved API configuration to its Python host and exposes
only public configuration to the renderer. A standalone Python host uses the same
environment variables; a browser-only Vite build reads them at build/start time.
Changing cloud configuration requires restarting the app. Close its terminal tabs first: an existing host with active sessions is preserved rather than reused with different cloud settings. Refresh tokens for alternate API endpoints use separate files so the official account token is not sent to a fork's server. When cloud is disabled, provider API keys can still be used directly; external model providers require their own credentials and network connection. Configure API keys in Settings → LLM Providers. Paste a key into its provider’s section: Coloride validates access, saves it in the OS credential store, discovers available models and selects a coding default automatically. The agent menu only shows discovered models from Coloride’s supported coding shortlist. Discovery uses model-list endpoints, not billable generation requests; it does not verify remaining quota. Invalid replacement keys preserve the saved configuration. A working provider stays selected when connecting additional providers. You can also register compatible endpoints or local servers in Settings. The agent uses a provider registry with explicit model capabilities; unknown models do not automatically gain tools, vision or reasoning support.
This setting controls account and managed-agent access. Editing, terminals,
search, the embedded browser and local files do not call Coloride. Sign-in and
agent model requests are the calls that use apiBase.
Open-source builds do not register the machine, upload workspace paths, or
report usage to the product dashboard. They also do not download updates from
the official feed unless COLORIDE_OFFICIAL_UPDATE=1.
Crash reporting is separate (COLORIDE_SENTRY_DISABLED=1).
Building installers
Tag pushes (vX.Y.Z, matching the desktop package version) and the Release
Desktop workflow build macOS arm64 and experimental Windows x64 installers.
Release Windows runs the same pipeline for Windows only. Both use Node.js 22
and publish assets to a draft GitHub Release in the current repository using
GITHUB_TOKEN; no VPS or external release repository is required. Review the
artifacts and signing results before publishing the draft.
macOS builds are unsigned and not notarized unless all five repository secrets
are configured: MACOS_DEVELOPER_ID_P12_BASE64,
MACOS_DEVELOPER_ID_P12_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD,
and APPLE_TEAM_ID. Partial credentials fail the build. Signed builds require
successful signature, Gatekeeper and stapling checks. Windows installers are
unsigned. Neither workflow includes voice models or a voice runtime.
For local signed macOS builds, use pnpm desktop:release:signed with the Apple
credentials described in tooling/release/macos-sign-release.sh. VPS deployment
is an optional administrator task via tooling/release/deploy-downloads.sh;
its --help lists the required configuration.
Local publish commands (pnpm desktop:release, pnpm desktop:release:win, and
pnpm desktop:release:signed:publish) use the GitHub provider and create draft
releases. Set GH_TOKEN with permission to publish releases. Forks must change
build.publish.owner and build.publish.repo in client/desktop/package.json
to their own repository before using these local commands. GitHub Actions
always uses the repository running the workflow.