Skip to content

Run Subconscious from source

Source-only preview

Packaged installers and marketplace releases are not available yet. The Windows desktop app is the first platform release target. The commands below run the current implementations from source; do not use the reserved subconscious desktop, tui, web, or extension commands, which are not implemented yet.

Prerequisites

  • Git, a subconscious conda environment, and Python 3.11 or newer for the local engine
  • Flutter 3.47.2 or newer with Dart 3.13.2 or newer for app clients
  • Node.js, npm, and VS Code 1.93 or newer for Subconscious Code
  • The repositories checked out as sibling folders: subconscious-dart, subconscious-code, and subconscious-server

1. Install and start the local engine

From subconscious-dart\engine on Windows:

conda run -n subconscious python -m pip install -e .
conda run -n subconscious subconscious start --dev

Development mode listens on port 55681 and uses the development token subconscious-dev-token. Use subconscious start without --dev for a generated token and available port, --detached for a background process, or --no-tray for headless operation. See Local engine before enabling --lan.

2. Run the Windows desktop client

In a second terminal, from subconscious-dart:

flutter pub get
flutter run -d windows -t apps/unified_app/lib/main.dart --dart-define=SUBCONSCIOUS_ENGINE_DEV=true

The desktop client discovers the development engine through its local runtime file. Substitute another Flutter device to exercise a source target; web and remote/mobile clients need an explicitly reachable engine URL and token.

Other source clients

=== "VS Code / Open VSX-compatible"

From `subconscious-code`, run `npm install` and `npm run compile`, then press **F5** in VS Code to open an Extension Development Host. Open the **Subconscious** Activity Bar view and set `subconscious.dev` to `true` for the development engine.

=== "Terminal"

From `subconscious-dart`, pass the engine connection as compile-time values:

```batch
dart run -DSUBCONSCIOUS_ENGINE_URL=http://localhost:55681 -DSUBCONSCIOUS_ENGINE_TOKEN=subconscious-dev-token apps/tui_app/bin/main.dart
```

=== "Chromium"

Open `chrome://extensions`, enable **Developer mode**, choose **Load unpacked**, and select `subconscious-dart\apps\chromium_extension`. Enter the engine URL and joining token in the popup. Chromium asks for access only to the selected engine origin.

Cloud identity and integration service

The separate service in subconscious-server supports accounts, OAuth, API-key connections, and webhooks. To run it locally:

uv sync --extra dev
copy .env.example.dev .env
uv run uvicorn app.main:app --reload --port 5050

Replace development secrets in .env. Staging and production must run uv run alembic upgrade head before startup; see Production cloud service. ```