Fabric Desktop

Fabric Desktop brings chat, projects, model controls, memory, and skills into one app. It uses the same profile as the CLI, TUI, web dashboard, API, and messaging gateway, so your provider accounts, sessions, and approvals carry across instead of living in a desktop-only database.

The app targets macOS, Windows, and Linux. See Platform Support for the distinction between a source build, an unsigned CI artifact, and a signed production release.

Distribution status

Do not infer that a signed Fabric installer exists from the presence of packaging code. A public package is released only when it appears under ObliviousOdin/fabric releases with checksums and the required platform signature.

Install and launch

Install the engine from the public Fabric checkout as described in Install Fabric, then run:

fabric desktop

The first source build installs workspace dependencies and downloads Electron, so it is slower than later launches. Fabric reuses the build while its content stamp is current.

Useful launch controls:

Flag	Behavior
--cwd PATH	Open chat in a specific project directory
--source	Run against the development renderer instead of the packaged app
--skip-build	Launch an existing build without rebuilding
--force-build	Ignore the content stamp and rebuild
--build-only	Build without launching
--ignore-existing	Ignore an existing CLI found on PATH during backend resolution
--fabric-root PATH	Select an engine source checkout for development
--fake-boot	Exercise deterministic startup states for development/QA

--fabric-root is a development interface. Desktop installer/process handoffs are internal, not user-configurable, and must not be added to .env.

Interfaces that share the profile

• Desktop — native chat, project navigation, previews, and visual settings.
• CLI — fabric, optimized for scripting and direct terminal work.
• TUI — fabric --tui, a full-screen terminal experience.
• Web dashboard — fabric dashboard, a browser management surface.
• Gateway — fabric gateway, messaging channels and long-running sessions.

All use the selected profile under FABRIC_HOME (normally ~/.fabric). A named profile stays isolated from the default profile across every surface.

First-run onboarding

On first launch, choose one account/model route or select Choose provider later. The supported ownership lanes remain distinct:

• My account / subscription — complete provider OAuth locally and store the resulting credential in the selected profile.
• API key — save a provider key to the selected profile's private auth store; never place it in project config.
• Native Ollama — connect to the native Ollama server root (normally http://127.0.0.1:11434), explicitly refresh installed models, choose one, and apply it without an API key.
• Fabric-managed request — records a profile-scoped access request. It does not make an account ready until the managed control plane reports a verified ready state.

Opening a provider picker is passive: it does not probe local network services or begin OAuth. Discovery and sign-in start only after an explicit action.

Chat and projects

The main window provides:

• streaming assistant output and live tool activity;
• an Agent Live View side panel and picture-in-picture window for Browser and Computer Use actions;
• approval prompts for dangerous actions;
• drag-and-drop attachments;
• a project file browser and preview rail;
• multiple concurrent conversations and profile-aware session history;
• composer history, queued-message editing, and model controls; and
• voice input/output when the platform grants microphone permission.

When the agent asks to run a dangerous action, the inline approval bar offers Run, Reject, and an options menu (Allow this session / Always allow…). Expand Details to review the full context before deciding: the complete, untruncated warning and command, the tool and working directory, why approval was triggered, and a badge when the action looks destructive or irreversible. The panel opens automatically for high-risk approvals. Enable Settings → Notifications → Approval Sound to hear a short cue when an approval needs you and Fabric is already focused on that chat — the one case no desktop notification is shown — respecting the global mute.

Every approval is tied to the exact backend request that raised it. If parallel tool calls need several approvals, Desktop keeps them in arrival order instead of replacing the visible prompt. In-app and native-notification actions carry that request identity, and Desktop dismisses an approval only after the backend receipt confirms the same request. An old notification action therefore cannot approve or clear a newer command in the conversation.

Open Command Center → System for a live host panel (CPU, memory, disk, load, network throughput, and GPU when available). It uses the same /api/system/stats collector as the web dashboard Host card and fabric monitor / fabric top.

The composer model picker changes the active chat/device selection. Set the profile-wide default under Settings → Model. Switching models in a live conversation invalidates the provider prompt cache, so a new chat is often the cheaper choice for a long transcript.

When the agent starts using Browser Automation or Computer Use, Desktop opens the visual target and action timeline beside the conversation. You can pop that same session into an always-on-top window, pause only its visual updates, and dock it again without restarting the task.

Voice notes

Open Voice Notes from the sidebar or Command Center to turn a recording into a reviewed Markdown note:

1. Enable and configure speech-to-text under Settings → Voice. When it is disabled, the Voice Notes setup button opens this panel directly.
2. Choose Start recording and grant microphone access when the operating system asks. Fabric stops automatically at the configured recording limit, which is capped at ten minutes.
3. Choose Stop and transcribe, then correct names or wording in the transcript. A failed transcription keeps the temporary recording available for an explicit retry.
4. Choose Create note with Fabric. Desktop opens a fresh conversation and asks Fabric for a Markdown note containing Summary, Decisions, Tasks, Follow-up, and the reviewed transcript.

The reviewed transcript is treated as source data, not as instructions or workspace context. Literal context-reference text such as @file: or @diff remains part of the note and does not attach files or repository changes.

The audio is sent to the speech-to-text provider configured in the active profile. Desktop does not save a local copy automatically: leaving the view or discarding the draft releases it unless you explicitly choose Save recording.

Design systems and outputs

Open Design to turn a brief into a reviewed /design prompt. The workspace can use the current project's DESIGN.md, start a new visual language, apply a bundled preset, or reuse an exported Claude Design ZIP:

1. Choose Add Claude Design ZIP and select a .zip archive.
2. Select the imported system in the Design system library. Fabric stays on Design and shows a Source preflight for the validated managed revision: filename and revision, file/size summary, detected entrypoints, a bounded file inventory, and a short DESIGN.md excerpt when one exists.
3. Enter the brief, deliverable, and fidelity, then choose Open in a new chat. Import alone never starts the model run.
4. Review the fresh chat. Fabric references the selected, already validated design-system revision, includes a normalized inventory of what was found, and asks the agent to materialize the reusable contract in the project and maintain DESIGN.md.
5. Choose View outputs to open artifacts reported by the design run.

The library is profile-scoped and stored by the Fabric backend, so moving or deleting the original ZIP does not break an imported system. Import validates the ZIP, rejects traversal paths and links, applies bounded entry and size limits, and extracts an immutable revision without executing bundle code. Inspection is also bounded and read-only: it returns at most 200 inventory rows, 40 HTML and 40 token entrypoints, and a 16 KiB DESIGN.md excerpt while showing omitted counts. It never re-extracts the archive in the renderer, never follows symlinks, and never embeds raw archive text into the chat prompt. Replace validates a new revision, Show reveals the managed copy for a local backend, and Remove deletes Fabric's managed entry without deleting the original ZIP. Maintained tokens, components, assets, and rationale still belong in the project and its DESIGN.md; imported revisions are read-only reference snapshots.

Design prompts require an Artifacts handoff with exact output paths. Desktop indexes workspace-relative HTML files, images, documents, archives, and other common outputs, resolves relative paths against the session working directory, and makes them available from Artifacts.

Provider and local-model settings

Open Settings → Providers:

• Accounts contains subscription/OAuth routes.
• API keys contains key-based providers.
• Local models contains native local providers such as Ollama.

For Ollama, the app does not guess that a daemon is available. Enter the native server root, choose Refresh, select an installed model, then Apply. A loopback endpoint can automatically use local_ai policy. A LAN endpoint must be a permitted private literal address and requires a narrowly approved CIDR; public, metadata, credential-bearing, and unsafe URLs are rejected.

See Local Ollama for context-window, tool-capability, egress, and troubleshooting guidance.

Memory and skills

Desktop consumes the same profile-local memory and skill registries as the CLI. Use the visual pages for normal inspection and management; use these CLI checks when diagnosing a mismatch:

fabric memory status
fabric skills list --enabled-only
fabric skills audit

External memory providers remain subject to consent, profile scope, egress, and provider capability limits. Installing a skill remains a trust decision even when it is initiated from a visual catalog.

Updates

The in-app update action currently drives the managed source-update/rebuild path used by fabric update; it is not proof of a signed binary auto-update channel. Preview an engine update from the CLI with:

fabric update --check

Production desktop auto-update remains gated on signed, checksum-published packages, downgrade rules, and rollback evidence. See Updating & Uninstalling.

Uninstall

Open Settings → About → Danger zone, or use the CLI:

fabric uninstall --gui   # remove only desktop build/data
fabric uninstall         # remove engine; choose whether to retain profiles
fabric uninstall --full  # remove engine and user data after confirmation

Removing only the GUI keeps providers, sessions, memory, skills, and the CLI. Create a backup before a full removal.

Connect to a remote Fabric backend

Desktop normally starts a local fabric serve child process. It can instead connect to a Fabric backend on another machine under Settings → Gateway → Remote gateway.

Treat the backend as privileged

The backend can read profile credentials and execute agent tools. Keep it on a trusted VPN/private network, use TLS at the boundary, and enable a configured authentication provider. Never expose a basic-password backend directly to the public internet.

For a trusted VPN test, configure the provider in ~/.fabric/config.yaml:

dashboard:
  basic_auth:
    username: admin
    password: choose-a-strong-password # or use password_hash (preferred)
    secret: replace-with-a-long-random-secret

Credential fields may use config's ${VAR} interpolation if you prefer to keep the underlying values in ~/.fabric/.env.

Then start the backend on the machine's private/VPN address:

fabric serve --host 0.0.0.0 --port 9119

Enter https://<private-host>:9119 (or the protected reverse-proxy URL) in the desktop settings, sign in, and reconnect. The gateway for Telegram/Discord/etc. is a separate process; start it independently if needed.

For an internet-reachable deployment, configure an approved self-hosted OIDC provider and TLS reverse proxy. Fabric does not claim a public hosted desktop-auth service in this guide.

Troubleshooting

Start with the desktop log:

fabric logs desktop -f

The underlying file is normally ~/.fabric/logs/desktop.log.

Symptom	Action
Startup cannot find the backend	Run fabric doctor; confirm the selected profile and engine checkout exist
Local Ollama list is empty	Start Ollama, verify /api/tags, then press Refresh explicitly
Remote connection returns 401	Verify the advertised auth provider and credentials on the remote backend
App is signed out after every backend restart	Configure a stable authentication signing secret
Linux app will not launch	Inspect sandbox/AppArmor errors; do not permanently disable system security as a first step
Windows rebuild reports a locked executable	Exit all Fabric desktop/backend processes before replacing the package

On macOS, reset only the Fabric microphone permission with:

tccutil reset Microphone io.github.obliviousodin.fabric

Build and product branding development

From the repository root:

npm ci
cd apps/desktop
npm run dev

Native packages:

npm run dist:mac
npm run dist:win
npm run dist:linux

apps/desktop/branding/fabric.json is the canonical identity contract. The checked-in Fabric manifest is the sole release identity. Brand assets must be staged inside the desktop package; compatibility protocol aliases do not change the visible Fabric identity.

Before a desktop PR:

npm run --prefix apps/desktop typecheck
npm run --prefix apps/desktop lint
npm run --prefix apps/desktop test:desktop:platforms
npm run --prefix apps/desktop test:ui