Documentation / Desktop Ide

ACE IDE — configuration and database usage

v1.0 Beta

ACE IDE — configuration and database usage

This document describes what you configure on your side to run and ship the Desktop IDE, and which Laravel database tables exist specifically for IDE telemetry (versus shared tables used when users log in or use Get Code / AI).

References in the repo:

  • desktop-ide/main.js — env loading and default API URLs
  • desktop-ide/ide.env.example — copy to ide.env for local overrides
  • desktop-ide/README.md — dev and production URL notes
  • routes/web.php — /desktop-ide/auth/*, /desktop-ide/telemetry/*
  • database/migrations/2026_04_28_131900_create_desktop_ide_telemetry_tables.php

Part A — Configuration on your side

1) Desktop app (ide.env)

The Electron app reads desktop-ide/ide.env or .env.ide (same folder as main.js). Only keys whose names start with BDL_IDE_ are applied from that file, plus APP_URL is allowed. Variables already set in the process environment take precedence. See loadLocalIdeEnvFromFiles() in desktop-ide/main.js.

Minimum — point the IDE at your Laravel app

Variable Role
APP_URL or BDL_IDE_APP_URL Base HTTPS (or local) URL of your Laravel site. Most default AI URLs are built from this unless you override each endpoint.

Optional — override individual backend routes (defaults are {BASE}/get-code/...)

Variable Typical default (under IDE_BASE_URL)
BDL_IDE_AI_ENDPOINT /get-code/generate
BDL_IDE_AI_CHAT_ENDPOINT /get-code/ai-chat
BDL_IDE_AI_CHAT_STREAM_ENDPOINT /get-code/ai-chat-stream
BDL_IDE_AI_CHAT_RESUME_ENDPOINT /get-code/ai-chat-resume
BDL_IDE_AI_CHAT_TERMINAL_RESUME_ENDPOINT /get-code/ai-chat-terminal-resume
BDL_IDE_COMPOSER_AGENT_PLAN_ENDPOINT /get-code/composer-agent/plan
BDL_IDE_AI_STREAM_ENDPOINT /get-code/generate-stream
BDL_IDE_DIAGNOSTICS_ENDPOINT /api/ide/diagnostics
IDE_MANIFEST_* BDL_IDE_MANIFEST_URL, BDL_IDE_MANIFEST_BETA_URL (legacy updater manifest)

User profile / login

Variable Role
BDL_IDE_USER_PROFILE_URL Override if the profile JSON API is not on the same origin as APP_URL.
BDL_IDE_LOGIN_LEGACY_POLL 1 enables legacy poll-based bridge.
BDL_IDE_LOGIN_HTTP_CALLBACK 0 disables HTTP localhost token callback (deeplink only).
BDL_IDE_ACCOUNT_URL, BDL_IDE_DOCS_URL Open account / docs in the system browser.
BDL_IDE_USER_UUID Dev shortcut only; production users authenticate via the browser flow.

Auto-updates (packaged builds only)

Variable Role
BDL_IDE_AUTO_UPDATE_URL Base URL for electron-updater generic provider (code default: https://storage.googleapis.com/bdl-releases). Must serve latest.yml and artifacts for your platform.
BDL_IDE_AUTO_UPDATE_INTERVAL_MS Check interval (default 6 hours; minimum enforced in code).
BDL_IDE_USE_LEGACY_MANIFEST_UPDATER Set to 1 to use legacy manifest flow instead of Electron auto-updater.

Observability

Variable Role
BDL_IDE_SENTRY_DSN, BDL_IDE_SENTRY_ENV, BDL_IDE_SENTRY_DEBUG Electron (main + renderer via Sentry SDK).
BDL_IDE_SENTRY_TEST_TOKEN Settings UI test path to backend Sentry.
BDL_IDE_OPEN_DEVTOOLS 1 opens DevTools (development).

Tasks / Composer / HTTP

Variable Role
BDL_IDE_DEV_SERVER_URL Tasks panel “open dev server” in browser (default http://localhost:5173).
BDL_IDE_COMPOSER_BUNDLE_MAX_CHARS Cap size of local codebase bundle sent to Composer Agent.
BDL_IDE_HTTP_USER_AGENT Custom User-Agent for backend HTTP requests.
BDL_IDE_SSE_FIRST_RESPONSE_MS Tuning for SSE / first-byte expectations.
BDL_IDE_VERTEX_* Vertex credential env names mapped in main to secure OS storage (see ENV_TO_SECURE_KEY_MAP in main.js).

Build / release (CI or maintainer)

Variable Role
BDL_IDE_GPG_KEY_ID Optional Linux .deb / .AppImage signing (scripts/after-all-artifacts-build.js).

2) Laravel server (.env)

The packaged IDE does not read Laravel’s .env. You still need a correct server configuration for anything the IDE calls:

  • DESKTOP_IDE_CLIENT_ERROR_TOKEN — shared secret with BDL_IDE_CLIENT_ERROR_TOKEN in ide.env; enables POST /api/ide/client-errors. If empty, the API returns 503 and the IDE skips DIY reporting (no DB rows).
  • DESKTOP_IDE_ERROR_ALERT_EMAILS — comma-separated addresses for DIY error alert mail (requires working MAIL_*).
  • APP_URL, APP_KEY — encryption for desktop bearer tokens (App\Services\DesktopIdeAuthTokenService).
  • Database — session/user data and telemetry tables below.
  • Session + cache — browser login bridge uses Laravel session and Cache:: keys (for example desktop login handoff); configure SESSION_DRIVER, CACHE_DRIVER appropriately.
  • Get Code / Gemini — Composer and chat need API keys configured in Laravel (services.get_code / .env; see App\Services\ComposerAgentService).
  • Tool agent (optional) — per desktop-ide/ide.env.example, set BDL_IDE_ENABLE_TOOL_AGENT=true in Laravel .env (server side), not in Electron ide.env.

For local development, ide.env.example notes using APP_ENV=local where appropriate so Get Code POST routes can work without CSRF issues for the desktop client.

Routes (see routes/web.php) include:

  • /desktop-ide/auth/* — bridge, poll, web-start, handoff
  • /desktop-ide/telemetry/* — session start, heartbeat, session end, events

3) End users after install

  • No database connection is configured inside the Electron app for project work.
  • Settings and encrypted credentials live under Electron user data paths and OS secure storage where used.
  • Per-workspace local cache (drafts, composer checkpoints) lives under .bdl_ide/ inside the opened folder — not in Laravel.

Part B — Database tables

B0 — DIY client error reports (1 table) — optional

When you set a shared token on the Laravel side (DESKTOP_IDE_CLIENT_ERROR_TOKEN in .env) and the same value in desktop-ide/ide.env as BDL_IDE_CLIENT_ERROR_TOKEN, the Electron app POSTs main/renderer errors to POST /api/ide/client-errors. Rows are stored for admin review; if DESKTOP_IDE_ERROR_ALERT_EMAILS is set (and MAIL_* is configured), the team receives an email per report.

Migration: 2026_05_14_120000_create_desktop_ide_client_errors_table.php

Table Purpose
desktop_ide_client_errors Message, stack, context JSON, app version, platform, optional user_uuid, source_ip, mail_sent.

Handler: App\Http\Controllers\Api\DesktopIdeClientErrorController.

B1 — Desktop IDE–specific telemetry (2 tables)

Migration: 2026_04_28_131900_create_desktop_ide_telemetry_tables.php

Table Purpose
desktop_ide_sessions One row per telemetry session_id (device id, app version, platform, heartbeats, active seconds).
desktop_ide_events Optional discrete events keyed by session_id.

Written through App\Http\Controllers\Homepage\DesktopIdeTelemetryController.

Count — dedicated Desktop IDE telemetry tables: 2.

B2 — Shared tables when users use login or AI

Desktop clients use many of the same code paths as the web app. Typical shared persistence includes (exact set depends on your production config):

  • Laravel sessions (file/DB/Redis depending on driver).
  • Cache entries for desktop auth handoff (not always a relational table).
  • User / registration models used after login (DesktopIdeAuthController integrates with existing auth).
  • get_code_activity and related models when GetCodeController logs generations (GetCodeActivity).
  • Billing, abuse, chat, or subscription tables — if enabled for Get Code flows.

Building the Electron installer does not talk to MySQL. The Laravel deployment backs sign-in and AI endpoints the IDE calls at runtime.

Part C — File API (/api/file/*)

Read/write/delete endpoints are handled by App\Http\Controllers\Api\FileController and are guarded by X-Active-Project-Folder (and related session/header rules). That path is geared toward browser/API workflows. The Electron IDE applies most edits locally to the workspace; AI and Composer still use Laravel for generation/planning.

Quick summary

Question Answer
Do I configure something for the Electron app? Yes — minimally APP_URL / BDL_IDE_APP_URL in desktop-ide/ide.env (plus optional overrides in the same file).
Do I configure the server? Yes — Laravel .env: APP_URL, APP_KEY, DB, sessions, cache, Get Code/Gemini keys, optional BDL_IDE_ENABLE_TOOL_AGENT.
How many IDE-specific DB tables? Three if you enable DIY errors: desktop_ide_client_errors, plus telemetry desktop_ide_sessions, desktop_ide_events.
Is that the entire database footprint? No — login and AI reuse broader application tables/services.

For a commented template of all common BDL_IDE_* keys, keep desktop-ide/ide.env.example beside this document.

Was this helpful?