4.5 KiB
title, type, audience, status, source_of_truth
| title | type | audience | status | source_of_truth |
|---|---|---|---|---|
| Mosaic Stack Quickstart | guide | user | current | 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 for deployment and the developer guide for contributor setup.
Requirements
- Node.js 20 or newer.
- npm, for the global Mosaic CLI installation.
- At least one supported agent runtime:
- 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:
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:
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 /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:
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:
mosaic gateway status
mosaic gateway verify
Sign in without putting your password in shell history or process listings:
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:
mosaic gateway login --gateway https://gateway.example.com
4. Launch Mosaic
Open the interactive terminal interface:
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:
mosaic tui --gateway https://gateway.example.com
You can also launch a supported runtime through Mosaic:
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:
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. For work from a repository checkout, keep DATABASE_URL unset and follow the developer guide; do not use root pnpm dev as a local PGlite route while the current dotenv safety hold remains active.