Installation

This guide covers downloading and installing StudioBrain, system requirements, first-run setup, and connecting to cloud services.

Desktop App (All Tiers)

The StudioBrain desktop app is built with Tauri 2.0 and available for Windows, macOS, and Linux.

Downloads

Download the latest release from the StudioBrain website or from the GitHub Releases page.

System Requirements

Installing on Windows

1. Download the .msi installer.
2. Double-click the installer and follow the setup wizard.
3. StudioBrain installs to C:\Program Files\StudioBrain\ by default.
4. Launch StudioBrain from the Start menu or desktop shortcut.

Installing on macOS

1. Download the .dmg disk image.
2. Open the .dmg and drag StudioBrain to your Applications folder.
3. On first launch, macOS may prompt you to allow the app. Open System Settings > Privacy & Security and click Open Anyway if needed.
4. Launch StudioBrain from Applications or Spotlight.

Installing on Linux

AppImage (universal):

1. Download the .AppImage file.
2. Make it executable: chmod +x StudioBrain-*.AppImage
3. Run it: ./StudioBrain-*.AppImage

Debian/Ubuntu (.deb):

1. Download the .deb package.
2. Install: sudo dpkg -i studiobrain_*.deb
3. Launch from your application menu or run studiobrain in a terminal.

First Run

StudioBrain always starts at the login screen. After signing in, you land on the Project Selection screen — the app never auto-opens a project. From here you either pick an existing project or create a new one.

First-Time Setup Wizard

New users (or users with no projects) are guided through a setup wizard:

1. Welcome — Brief orientation and plan tier confirmation.
2. Pick or Create a Folder — Choose an existing folder of StudioBrain-compatible files, or select an empty folder to start fresh. The folder you choose is your project — StudioBrain stores everything there as human-readable files, not in hidden application directories.
3. Template Packs — Select one or more template packs to install (e.g. Fantasy RPG, Film Production, Recipe Collection). If you skip this step, the core-essentials pack is installed automatically.
4. Storage Configuration — Choose how your files are stored. See Storage Modes below for details. The default is Local (files on your machine only).
5. Quick Tour — Interactive walkthrough of the sidebar, entity editor, and AI Workshop.
6. Done — Your project opens and you can start creating.

Returning Users

Returning users see the Recent Projects list on the Project Selection screen. Each project shows:

• Project name and folder path
• Last opened date
• Availability status — whether the project folder is accessible (e.g. an external drive may be disconnected, or a network share may be offline)

Click any available project to open it. Unavailable projects are grayed out with a tooltip explaining why.

Initial Content Scan

After selecting a project folder (new or existing), StudioBrain performs an initial scan:

1. Template discovery — Reads all files in _Templates/ to determine available entity types, following the inheritance order.
2. Rules loading — Reads all files in _Rules/ to load validation and generation rules.
3. Entity indexing — Parses all entity Markdown files and builds the local SQLite cache in .studiobrain/content.db.
4. Asset scanning — Discovers images, audio, video, and other media files associated with entities.

The scan typically takes a few seconds for small projects and up to a minute for large ones (1,000+ entities). Subsequent launches use the cached database and are much faster.

Configure AI Providers (Optional)

If you plan to use AI features, open Settings from the sidebar and enter your API keys:

On the Free tier, you must provide your own API keys (BYO keys). Paid tiers include managed AI through StudioBrain’s orchestration service, with BrainBits credits for usage.

Storage Modes

StudioBrain supports three storage modes. You choose a mode during first-run setup or later in Settings > Storage.

Local Mode

All files live on your local disk. No network required. This is the default and works on every plan, including Free. Your project folder is the single source of truth.

FileServer Mode

Your desktop app acts as a file server, making your local project available to the StudioBrain web and mobile apps through an encrypted relay tunnel. Your files never leave your machine — the desktop serves them on demand.

• Source of truth: Your local disk (desktop must be online for web/mobile access)
• Background service: The FileServer keeps running even when the app window is closed
• LAN optimization: When your desktop and another device are on the same network, files transfer directly without going through the relay

Cloud Storage Mode

Files are stored in a third-party cloud provider. This enables access from web and mobile without your desktop being online.

Storage credentials are saved to your StudioBrain cloud account so all your clients (desktop, web, mobile) can access the same files.

Desktop-to-Desktop Sync

If you use StudioBrain on multiple desktops, they can sync directly over your local network (LAN) when both are online. This avoids round-tripping through the cloud and is significantly faster for large projects.

Web Access (Indie+ Tiers)

Paid subscribers can access StudioBrain through the browser at studio.braindead.games.

Signing In

1. Navigate to studio.braindead.games.
2. Sign in with your StudioBrain account (created during subscription).
3. Your cloud-synced projects appear on the dashboard.

Connecting Desktop to Cloud

To sync your desktop project with the cloud:

1. Open Settings > Cloud Sync in the desktop app.
2. Click Connect Account and sign in with your StudioBrain credentials.
3. Choose a sync mode:
   • Push — Upload your local project to the cloud for the first time.
   • Pull — Download an existing cloud project to your local machine.
   • Two-way Sync — Keep local and cloud copies synchronized automatically.

Google Drive Integration (Indie+ Tiers)

StudioBrain can sync entity files to Google Drive for additional backup and sharing. See Storage Modes above for the full list of supported providers.

Setting Up Google Drive

1. Open Settings > Storage Providers in the desktop or web app.
2. Click Connect Google Drive.
3. Complete the OAuth consent flow — StudioBrain requests access to a dedicated folder in your Drive.
4. Choose which project folders to sync.

StudioBrain creates a StudioBrain/ folder in your Google Drive and mirrors your project structure there. Only entity Markdown files and metadata are synced — large binary assets remain local unless you choose to include them.

What Gets Synced

Enterprise: Self-Hosted Instance

Enterprise customers can deploy StudioBrain on their own infrastructure.

Connecting to a Self-Hosted Instance

1. Open the desktop app.
2. Go to Settings > Cloud Connection.
3. Under Instance URL, enter the URL of your self-hosted StudioBrain server (e.g., https://studiobrain.yourstudio.com).
4. Sign in with your organization credentials.

For self-hosted deployment instructions, see the Self-Hosting Guide.

Desktop Features

The desktop app includes capabilities beyond what the web and mobile apps offer.

Offline-First

StudioBrain desktop works without a network connection for all core workflows — entity creation, editing, validation, local AI, search, and the relationship graph. Cloud features (sync, managed AI, web/mobile access) resume automatically when you reconnect.

FileServer

When FileServer mode is enabled, the desktop app serves your project files to the web and mobile apps through an encrypted relay tunnel. This lets teammates or your own mobile device access your content without uploading files to a third-party cloud provider.

Background Service

The FileServer continues running as a background service even after you close the StudioBrain window. This ensures web and mobile clients can access your files whenever your machine is on.

System Tray

The tray icon provides quick access to the background service:

• Status indicator — green (serving), yellow (syncing), red (error)
• Restart service — restart the FileServer without reopening the app
• View logs — open the service log viewer
• Quit — stop the background service and exit completely

Force Re-Index

If your project files were modified outside StudioBrain (e.g. by a script or git pull), use Markdown Files > Re-index from the sidebar to rebuild the local database cache from disk.

Updating StudioBrain

Desktop App

StudioBrain checks for updates on launch. When an update is available:

1. A notification appears in the app.
2. Click Update to download and install the new version.
3. The app restarts automatically after the update.

You can also check manually in Settings > About > Check for Updates.

Web App

The web app at studio.braindead.games is always running the latest version. No action required.

Troubleshooting Installation

Desktop app will not launch

• Windows: Make sure WebView2 Runtime is installed. StudioBrain requires it for rendering. Download from developer.microsoft.com.
• macOS: If blocked by Gatekeeper, open System Settings > Privacy & Security and click Open Anyway.
• Linux: Ensure webkit2gtk (4.1+) and libjavascriptcoregtk are installed. On Ubuntu: sudo apt install libwebkit2gtk-4.1-dev.

Initial scan is very slow

• Large projects with thousands of files may take longer on the first scan. Subsequent launches use the SQLite cache and are much faster.
• Ensure your project is on a local or fast-access drive, not a network share with high latency.

Cannot connect to cloud

• Verify your internet connection.
• Check that your subscription is active at studio.braindead.games/settings/billing.
• If using a self-hosted instance, confirm the instance URL is correct and the server is running.

Next Steps

• Getting Started — Overview of the application and interface navigation
• Managing Entities — Creating and editing entities with the template system
• Settings & Configuration — Detailed configuration options