--- title: Mosaic Stack Quickstart type: guide audience: user status: current source_of_truth: false --- # Mosaic Stack Quickstart Get the Mosaic CLI installed, complete first-run setup, connect to a gateway, and launch an agent session. This page covers the supported installed-CLI path with the default local storage tier. > **Scope:** This is an end-user installation route. It does not authorize PostgreSQL setup, production deployment, or starting Gateway/Web directly from a source checkout. Use the [administrator guide](../../ADMIN-GUIDE/README.md) for deployment and the [developer guide](../../DEVELOPER-GUIDE/README.md) for contributor setup. ## Requirements - Node.js 20 or newer. - npm, for the global Mosaic CLI installation. - At least one supported agent runtime: - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - [Codex](https://github.com/openai/codex) - [OpenCode](https://opencode.ai) - [Pi](https://pi.dev) - Credentials for the runtime or model provider you plan to use. ## 1. Install Mosaic The stable installer installs the Mosaic framework and the `mosaic` CLI, then launches the setup wizard by default: ```bash curl -fsSL https://mosaicstack.dev/install.sh | bash ``` If your security policy requires reviewing the script before execution, download it first and inspect it. The installer also supports the direct repository URL: ```bash curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh -o /tmp/mosaic-install.sh less /tmp/mosaic-install.sh bash /tmp/mosaic-install.sh ``` To install without automatically launching the wizard: ```bash bash /tmp/mosaic-install.sh --no-auto-launch ``` The installer places framework files under `~/.config/mosaic/` and installs the CLI under the configured npm global prefix, `~/.npm-global/` by default. Ensure that prefix is on your `PATH` if your shell cannot find `mosaic`. ## 2. Complete first-run setup If the installer skipped the wizard, run it manually: ```bash mosaic wizard ``` The wizard guides framework setup and gateway installation. It can collect your agent identity, preferences, provider configuration, and gateway administrator details interactively. For a separately installed or existing gateway, skip local gateway installation and use its URL in the login step below. ## 3. Verify and sign in For a gateway installed on this machine, check its health and setup state: ```bash mosaic gateway status mosaic gateway verify ``` Sign in without putting your password in shell history or process listings: ```bash mosaic gateway login ``` The command prompts for the gateway URL, email, and password as needed. Do not pass passwords with `--password`. For a remote gateway, provide its URL explicitly: ```bash mosaic gateway login --gateway https://gateway.example.com ``` ## 4. Launch Mosaic Open the interactive terminal interface: ```bash mosaic tui ``` The TUI defaults to `http://localhost:14242` and can prompt for login if no valid session is saved. To connect it to another gateway: ```bash mosaic tui --gateway https://gateway.example.com ``` You can also launch a supported runtime through Mosaic: ```bash mosaic pi mosaic claude mosaic codex mosaic opencode ``` Use the launcher matching the runtime you installed and authenticated. ## 5. Inspect configuration and health These commands are safe diagnostics and do not change the product requirements or active task ledger: ```bash mosaic config show mosaic doctor mosaic gateway logs ``` If the gateway is unhealthy, run `mosaic gateway status` and `mosaic gateway logs` before attempting a reinstall. If your session expires, run `mosaic gateway login` again. ## Storage and deployment boundary The default local gateway tier uses embedded PGlite and does not require an external PostgreSQL or Valkey service. This quickstart intentionally does not configure `DATABASE_URL`, PostgreSQL, pgvector, or a federated deployment. For standalone or federated storage, deployment topology, secrets, SSO, backups, or recovery, stop here and use the [administrator guide](../../ADMIN-GUIDE/README.md). For work from a repository checkout, keep `DATABASE_URL` unset and follow the [developer guide](../../DEVELOPER-GUIDE/README.md); do not use root `pnpm dev` as a local PGlite route while the current dotenv safety hold remains active. ## Related - [User Guide](../README.md) - [Documentation atlas](../../README.md) - [Administrator Guide](../../ADMIN-GUIDE/README.md) - [Developer Guide](../../DEVELOPER-GUIDE/README.md) - [Repository README](../../../README.md)