mereyabdenbekuly-ctrl/clodex-ide

Model output is untrusted input. Authority comes from explicit policy, isolated runtimes, and user-controlled review.

Current release status: Technical Preview. The architectural core is implemented and tested locally. The public desktop binaries described below are unsigned community test artifacts, not an official stable release. Advanced execution lanes remain feature-gated until their live promotion evidence and manual sign-off are complete.

Community test build

The current public tester build is 1.16.0-communityobserved7, produced from the canonical main commit 981311304fb4c648ebbaa0b85fbed0602aab2c9f by GitHub Actions run 29615260553 and published as a clearly separated GitHub community prerelease. It adds the Русский (beta) interface and a required first-launch privacy choice with Allow anonymous statistics as the primary action and a visible Continue without statistics path. The previous community4 prerelease remains available as the telemetry-free predecessor.

Download SHA256SUMS.txt from the same prerelease and verify the installer before opening it. The exact source manifests, CycloneDX SBOMs, warnings, platform validation reports, and byte-level audit report are retained in the compact evidence archive. Do not use repackaged binaries from an unverified mirror.

Before onboarding, the build requires an explicit allow-or-decline choice. No PostHog client starts before that decision. If anonymous statistics are allowed, only the backend client may send allowlisted counters, bounded timing, enum metadata, app/platform metadata, and a pseudonymous installation ID. Renderer capture, person profiles, GeoIP enrichment, prompts, messages, source code, commands, paths, URLs, API keys, tool arguments, error or feedback text, exceptions, account identification, session recording, full telemetry, and AI tracing are disabled. The choice can be changed later in Settings.

Verify and install

Community packages intentionally have no trusted publisher identity. macOS apps are ad-hoc signed and not notarized, Windows packages are not Authenticode-signed, and Linux packages have no CLODEx release signature. Open source makes the source inspectable; it does not authenticate a downloaded binary.

1. Confirm that the bundle manifest records the expected version, platform, architecture, and source commit.

2. Verify the selected file before installation. For example:

   # macOS: replace FILE with the downloaded DMG name
   grep "  FILE$" SHA256SUMS.txt | shasum -a 256 -c -
   
   # Linux: replace FILE with the downloaded DEB or RPM name
   grep "  FILE$" SHA256SUMS.txt | sha256sum -c -
   

   On Windows, compare Get-FileHash <installer.exe> -Algorithm SHA256 with the installer entry in SHA256SUMS.

3. Install for your platform:

   • macOS: open the matching DMG and drag the app to /Applications. On first launch, use Finder's per-app Control-click -> Open review only after verifying the bundle. Do not disable Gatekeeper globally.
   • Windows: run the x64 setup. SmartScreen may warn about an unknown publisher; use only its per-file review path after verifying the bundle. Do not disable SmartScreen or Defender globally.
   • Linux: install either the downloaded DEB (apt install ./<file>.deb) or RPM (rpm -i ./<file>.rpm) for your distribution.

The observed community build has a separate application identity. Account sign-in, auto-update, and default protocol registration are excluded. The first-launch privacy choice must be completed before normal IDE use. Install newer community builds manually.

First launch: connect a model

1. Choose System, English, or Русский (beta) in onboarding or Settings -> General, then restart once to verify persistence.
2. Leave anonymous telemetry off, or explicitly opt in after reviewing the description in onboarding or settings.
3. Open a local project or workspace.
4. In onboarding or Settings -> Models & Providers, choose one of:
   • a BYOK API key for a supported provider such as OpenAI, Anthropic, or Google;
   • a custom OpenAI-compatible endpoint; or
   • local Ollama, normally at http://localhost:11434.
5. Test the connection, select a discovered model, and start a small task.

Provider usage and billing remain between you and the provider. Never include API keys, tokens, private source, or unredacted logs in an issue or tester report. See the full community unsigned build policy and support guide.

Start here

Project lineage

Clodex began as a modified version of the open-source Stagewise codebase and has since diverged into an independently maintained project focused on governed execution, evidence, policy enforcement, model routing, runner isolation, and session continuity.

The exact upstream base commit, reproducible diff method, Clodex-specific systems, and continuing upstream-derived areas are documented in CLODEX_VS_UPSTREAM.md. Upstream copyright and license notices are preserved in THIRD-PARTY-NOTICES.md. Clodex is not affiliated with or endorsed by Stagewise.

Why Clodex

A conventional coding assistant produces the next answer or patch. Clodex models engineering work as a durable task with its own state, workspaces, processes, permissions, evidence, and review lifecycle.

A task can:

1. retain context across long-running work and application restarts;
2. operate across files, Git, terminals, browser tabs, MCP tools, and runners;
3. route work between models without changing the surrounding workflow;
4. request approval before high-impact shell, network, browser, or remote actions;
5. execute locally or move to Docker, SSH, or cloud-backed environments;
6. return diffs, receipts, artifacts, and a self-contained final result.

Core capabilities

Architecture

Clodex separates user interface, agent execution, tools, secrets, and policy into explicit process and trust boundaries.

flowchart TB
    USER["Developer"] --> UI["Electron renderer"]
    UI <--> IPC["Karton typed IPC"]
    IPC <--> MAIN["Electron main process"]

    MAIN <--> AGENT_HOST["Agent Host process"]
    MAIN <--> MCP_HOST["MCP Host process"]
    MAIN <--> SANDBOX["Sandbox workers"]

    AGENT_HOST --> CORE["Agent Core"]
    CORE --> TASKS["Task lifecycle and goals"]
    CORE --> MEMORY["Evidence memory and context ledger"]
    CORE --> FABRIC["Model Fabric"]
    CORE --> POLICY["Guardian and Zero-Trust policy"]

    POLICY --> EXECUTION["Local, SSH, Docker, or cloud execution"]
    EXECUTION --> ARTIFACTS["Artifacts, receipts, and checkpoints"]
    ARTIFACTS --> MEMORY

Important packages

apps/browser/                 Electron desktop application
apps/website/                 Public project website
agent/runtime-node/           Isolated Node.js agent runtime
packages/agent-core/          Agent lifecycle, memory, routing, and policy
packages/agent-shell/         Shell and execution contracts
packages/clodex-contracts/    Shell-independent Stage 0 kernel contracts
packages/mcp-runtime/         MCP transport and protocol runtime
packages/runner-sdk/          External runner integration SDK
packages/karton/              Typed state and RPC transport
packages/stage-ui/            Shared interface components

For a complete map, see docs/developer/repository-map.md.

Security model

Clodex does not rely on a prompt asking the model to behave safely. Sensitive operations pass through deterministic controls outside the model runtime.

• Fail closed: ambiguous or invalid authorization results do not execute.
• Isolated hosts: agent turns, MCP servers, and sandboxed workloads run outside the renderer.
• Explicit capabilities: possessing a tool does not automatically grant authority to use it.
• Controlled egress: network destinations are evaluated independently of model intent.
• Protected storage: credentials use OS-backed storage; sensitive task artifacts use context-bound authenticated encryption.
• Human review: pending edits, permission prompts, protected merge flows, and high-impact approvals keep final authority with the user.
• Supply-chain checks: extension identity, signatures, integrity, compatibility, rollback, and quarantine are verified before activation.
• Privacy-aware audit: operational events avoid storing prompts, source code, audio, credentials, or other unnecessary sensitive content.

Read the detailed model in docs/developer/security-and-data.md. Report vulnerabilities through SECURITY.md, not through a public issue.

Capability status

The status labels are deliberate: implemented foundations are not presented as stable production capabilities until real installation evidence, monitoring, rollback, and manual promotion checks are complete.

Run from source

Requirements

• Node.js 22.23.1
• pnpm 10.30.3
• Git
• macOS, Linux, or Windows for development
• macOS for DMG packaging and notarization

Setup

git clone https://github.com/mereyabdenbekuly-ctrl/clodex-ide.git
cd clodex-ide

corepack enable
corepack prepare [email protected] --activate

cp .env.example .env
cp .env.example .env.dev

pnpm install --frozen-lockfile
pnpm build:packages
pnpm --dir apps/browser start:fast

Use the checked development command when you want type checking to run in parallel with Electron:

pnpm --dir apps/browser start

Environment and provider configuration are documented in docs/developer/local-development.md. Never commit .env, credentials, signing keys, or local runtime state.

Validation

Run the complete local validation suite before opening a pull request:

pnpm check
pnpm typecheck
pnpm test
pnpm security:secrets

Validated baseline on July 12, 2026:

CI and signed release evidence remain the source of truth for a published artifact. See docs/developer/testing-and-release.md and VERSIONING.md.

Extending Clodex

Clodex exposes several integration surfaces:

• MCP: connect local stdio or remote Streamable HTTP/SSE servers;
• Skills: package reusable agent instructions and workflows;
• Plugins: distribute signed capabilities and optional executable runtimes;
• Runner SDK: integrate Docker, SSH, cluster, or custom execution backends;
• Generated Apps: create task-owned interactive tools with explicit grants;
• Automations: schedule bounded tasks with declared capabilities.

Start with docs/developer/extensions-and-integrations.md.

Contributing

Contributions should be scoped, testable, and reviewable.

1. Read CONTRIBUTING.md.
2. Follow the commit and versioning rules in VERSIONING.md.
3. Sign commits according to the repository DCO.
4. Run formatting, type checking, tests, and secret scanning.
5. Include focused tests for changed behavior.

Use the repository issue templates for bugs, feature proposals, documentation, installation and provider problems, security questions, and independent tester reports. Use GitHub Discussions for design questions and community proposals.

The contributor trust ladder, maintainer responsibilities, and access policy are defined in GOVERNANCE.md. Scoped compute grants and longer-term collaboration paths are described in COLLABORATE.md.

Maintainers and community

Clodex is currently maintained independently by Merey Abdenbekuly and welcomes external contributors, testers, security reviewers, research collaborators, and integration partners. Current roles and upstream credits are listed in CONTRIBUTORS.md.

Follow project updates on X · @CLODEx_lab.

Support independent development

If Clodex is useful to you, the current support options and their terms are listed on the Clodex website. Financial support does not buy roadmap priority, repository access, or merge decisions.

License

Clodex is distributed under the GNU Affero General Public License v3.0. Third-party components and notices are listed in THIRD-PARTY-NOTICES.md.