Run and configure the shell

Beginner walkthrough

Prerequisites: Read the two beginner guides below and finish Desktop local setup, including Rust and operating-system prerequisites. The code block starts both the web app and Tauri in the monorepo; in a desktop-only checkout, use its filtered command only after starting a reachable web backend separately. Tauri loads that backend.

Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.

1. Open apps/desktop/src-tauri/src/lib.rs; ask your agent to change only the named window/tray/hotkey behavior and keep product UI in the web app.

2. Run the shell and test close-to-tray, Quit, and CmdOrCtrl+Shift+Space; test supastack:///settings/appearance?preview=1#main.

3. It should focus the existing window and preserve path/query/fragment. If it opens the wrong page, compare the configured origin and exact route.

For custom code, start with the supplied prompts/README.md and copy the closest prompt: prompts/new-app-screen.md for an app screen or prompts/new-landing-page.md for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md, and matching .ai/ mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.

• Before you start
• Terminal basics
• Desktop local setup
• Agent prompts & project memory

# Monorepo: start the web app and desktop shell together
corepack pnpm dev:desktop

# Desktop-only checkout: start Tauri after a web backend is already reachable
corepack pnpm --filter @supastack/desktop dev

Keep shell behavior in Rust

src-tauri/src/lib.rs creates the main 1200×800 webview window. Closing hides it to the tray; Quit exits. Native menus provide Home/Back/Forward/Reload, zoom/fullscreen and window actions. Window-state restoration preserves size/position.

Handle links and summon

The shell accepts supastack:// routes and resolves them against the exact configured HTTP(S) app origin. For example, supastack:///settings/appearance?preview=1#main becomes /workspace/settings?tab=billing#plans; supastack:///auth/callback?code=... maps to /auth/callback?code=.... Query strings and fragments are preserved.

Startup links are applied before the first window is shown. macOS runtime links use Tauri's on_open_url; Windows and Linux second-instance arguments use the single-instance callback with its deep-link feature enabled. Valid links focus and navigate the existing window.

Only credential-free HTTP(S) links with the exact configured scheme, host, and effective port stay in the shell. Credential-free HTTP(S), mailto:, and tel: links may open externally; malformed links, credentials, unsupported schemes, ports on custom links, and traversal attempts are rejected. The configured backend URL also rejects credentials and falls back to the next valid/default origin.

SUPASTACK_APP_URL=https://your-app.example
SUPASTACK_DESKTOP_HOTKEY=CmdOrCtrl+Shift+Space

supastack:///settings/appearance?preview=1#main
# Opens https://your-app.example/workspace/settings?tab=billing#plans

Verify platform-specific behavior

The injected offline overlay offers Retry, hides on online and reloads the web app. Test focus, shortcuts, menu zoom, tray and deep-link invocation on every target OS; unit URL checks alone do not prove those native interactions.

• Desktop acceptance

Setup and configuration

Install the workspace dependencies and the Rust toolchain plus Tauri's per-OS prerequisites (WebView2 ships with Windows; macOS and Linux need their documented packages). corepack pnpm --filter @supastack/desktop dev runs tauri dev: it builds the Rust core, shows the placeholder UI, and loads the resolved app URL.

SUPASTACK_APP_URL is read at runtime first and falls back to the value baked in at build time. Credential-free HTTP(S) values are accepted; otherwise the next candidate is used. SUPASTACK_DESKTOP_HOTKEY overrides the default CmdOrCtrl+Shift+Space toggle; an invalid value falls back to the default rather than failing startup.

corepack pnpm --filter @supastack/desktop dev
corepack pnpm --filter @supastack/desktop typecheck

SUPASTACK_APP_URL=https://app.example.com \
SUPASTACK_DESKTOP_HOTKEY=CmdOrCtrl+Shift+Space \
corepack pnpm --filter @supastack/desktop dev

Implementation workflow

The main window stays on the exact configured origin, including scheme and port. Credential-free HTTP(S), mailto, and tel links can open in the system browser; unapproved schemes are cancelled.

Registered supastack:// links map their route, query, and fragment onto the configured app origin. Startup and platform open-url/second-instance callbacks use the same validation, so a deep link cannot redirect the shell to another host.

The tray icon and the global shortcut show and focus the single main window. When the shortcut does not register, another application usually owns the combination — pick a different SUPASTACK_DESKTOP_HOTKEY.

Verification and troubleshooting

Run cargo check and cargo test through the package scripts after touching src-tauri. Then verify exact-origin navigation, allowed external URL opening, a supastack:// route opening on the configured origin, tray and hotkey behavior, and sign-in persistence across restarts.