pitchblend AI
English
English Spanish

Developer Mode

This page is for contributors running the desktop wrapper from a source
checkout. Installed users should use the normal packaged Pitchblend-managed
runtime instead.

Developer mode does not add an end-user plugin marketplace or unlock Memory
Sync in a source build. The security boundaries used by the packaged app remain
in place.

Choose a runtime mode

Managed mode

Managed mode is the default. Electron starts and supervises Geist, accepts its
dynamic HTTP loopback origin, and uses that same origin for the workspace and
local API.

npm run dev

The explicit equivalent is:

npm run dev:electron:managed

On Windows or Linux, use the platform command on a new checkout so both pinned
llama.cpp runtimes are fetched and verified before launch:

npm run dev:windows
npm run dev:linux

Apple silicon macOS uses the managed MLX dependency instead:

npm run dev:mac

Attach mode

Attach mode connects Electron to one already-running Geist origin from
GEIST_URL. It never starts or stops that external process.

npm run dev:electron:attach

Attach mode is for UI and integration development. Memory Sync is unavailable
and shows:

Memory sync is unavailable in developer attach mode. Launch the normal
packaged Pitchblend-managed Geist runtime.

Use a loopback origin you control. The guest is origin-locked and sandboxed,
but attaching Pitchblend to an untrusted server is still unsafe.

Configure a source checkout

Keep local values in the checkout's untracked .env; never commit it. Common
settings are:

  • GEIST_PATH — Geist checkout used in managed source mode.
  • GEIST_SOURCE_PATH — source checkout used by npm run link:geist.
  • GEIST_UV_EXECUTABLE — uv executable or absolute path.
  • GEIST_URL — the single UI/API origin used only in attach mode.
  • GEIST_HEALTH_PATHS — comma-separated readiness paths.
  • GEIST_REQUEST_TIMEOUT_MS — timeout for an API or health request.
  • GEIST_STARTUP_TIMEOUT_MS — total readiness/health timeout.
  • GEIST_LLAMA_ACCELERATION — auto, vulkan, or cpu.
  • GEIST_LLAMA_CONTEXT_SIZE — llama.cpp context size; default 32768.
  • GEIST_LLAMA_GPU_LAYERS — Vulkan offload count; default 999.

auto attempts Vulkan first and falls back to CPU. These are developer/runtime
knobs, not settings in the customer UI.

Enable source Identity

Identity is off by default in a source build. To test the account control, set:

PITCHBLEND_IDENTITY_ENABLED=true
PITCHBLEND_IDENTITY_ISSUER=https://localhost:64081

An HTTP issuer is accepted only on an explicit loopback address; other issuers
must use HTTPS. The URL cannot contain credentials, a query, or a fragment.

Optional source-only timeouts are:

  • PITCHBLEND_IDENTITY_REQUEST_TIMEOUT_MS
  • PITCHBLEND_IDENTITY_LOGIN_TIMEOUT_MS

The authority must publish a compatible OIDC discovery document and support
Authorization Code with PKCE. Packaged clients ignore source issuer/client
overrides and use the built-in Pitchblend authority.

Open the wrapper diagnostics

Set DEBUG=true in the untracked .env, then restart the desktop app. The
otherwise hidden wrapper shell appears around the Geist workspace.

The header shows:

  • pitchblend AI;
  • Private desktop wrapper for local Geist runtime;
  • a status pill such as RUNNING (managed); and
  • the current status detail and Origin.

Select Admin to open Admin Interface.

Runtime Control

  • Start Geist starts the managed sidecar. In attach mode it returns an
    error because the external server belongs to you.
  • Stop Geist stops a managed sidecar.
  • Refresh Status runs an immediate health check.

Providers and Recent Sessions

  • Providers lists the strings returned by Geist's model-provider endpoint.
    Its empty/error messages are No providers returned. and Unable to load
    providers.
  • Recent Sessions shows up to ten raw JSON session summaries. Its
    empty/error messages are No chat sessions returned. and Unable to load
    sessions.

The wrapper exposes no prompt composer in this admin panel.

Runtime Logs

Runtime Logs collects timestamped Geist/manager output and local wrapper
diagnostics, including health, provider, session, branding, plugin-mount, and
webview failures.

Treat logs and raw session summaries as private. Review and redact them before
sharing; do not post tokens, license keys, memory text, file paths, or customer
data in an issue.

Select Close to close the admin panel. Remove DEBUG=true and restart to
return to the normal full-window workspace.

DEBUG controls the Pitchblend wrapper shell. It is an environment-driven
diagnostic flag and is not the same as Geist's host-plugin Developer setting.

Geist host-plugin Developer settings

Source builds tell Geist that host development is active, so Geist's Developer
settings can list the two active built-in plugins:

  • pitchblend.identity
  • pitchblend.sync

Packaged builds force this Geist setting off. There is no plugin download,
installation, discovery, enable/disable, or marketplace workflow. The two
plugins are compiled into the reviewed wrapper, verified by digest, and granted
narrow per-navigation capabilities.

Memory Sync limits in development

The Memory Sync control is present for UI inspection, but sync mutations are
allowed only when both conditions are true:

  • the app is packaged; and
  • runtime mode is managed.

A source managed build shows Memory sync is available only in a packaged
Pitchblend client in this release. Attach mode shows its separate attach-mode
notice. Do not bypass these checks or point development at a production sync
state.

Runtime setup failures

If GEIST_PATH is missing, the launch gate tells you to run
npm run link:geist. If Windows/Linux llama.cpp assets are incomplete, it tells
you to run the matching npm run dev:windows or npm run dev:linux command, or
the exact runtime:fetch-llama command.

Runtime staging and packaging commands are build tooling, not customer UI:

npm run runtime:fetch-llama -- --target win32-x64
npm run runtime:stage -- --target win32-x64 --geist-dir PATH --llama-cpu-dir PATH --llama-vulkan-dir PATH
npm run runtime:verify -- --target win32-x64

Do not skip runtime verification. Downloaded model weights are managed by
Geist under Pitchblend's per-user model directory and are never staged into an
installer.

The current general-release workflow deliberately creates unsigned Windows
and macOS applications. Do not describe a locally packaged build as a trusted
production release until platform signing is configured and verified.

For customer-facing controls, see
Account and Licenses and
Memory Sync.