5.2 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
Verify and install the versioned Mosaic CLI package, complete first-run setup, connect to a gateway, and launch an agent session. This page covers the 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
Installation hold: Do not execute the website installer or a script fetched from a mutable repository branch. The current release tooling does not publish an independently verified immutable dependency closure or a signed installer. If your policy requires either property, stop until a release provides it.
The currently published CLI/framework package is @mosaicstack/[email protected]. Pin the exact package version and verify its published artifact integrity before installation:
registry='https://git.mosaicstack.dev/api/packages/mosaicstack/npm/'
package='@mosaicstack/[email protected]'
expected_integrity='sha512-/Zsjdf8Ln2QchQTG9lirpqSxhDbNyBjOvGkWrDWRugxCuqUWP5V0rUNVDivmPvro+Vyq3hxDyA9i4hDfkEFmMg=='
actual_integrity="$(npm view --registry="$registry" "$package" dist.integrity)"
test "$actual_integrity" = "$expected_integrity"
npm install --global --registry="$registry" "$package"
The explicit comparison pins the reviewed top-level package artifact; npm also checks the downloaded tarball against registry integrity metadata. It does not make the package's transitive dependency graph independently immutable. Review the package release before proceeding, and stop if the integrity comparison fails.
The versioned package includes the Mosaic framework and CLI. npm installs it under your configured global prefix. Ensure that prefix's bin directory is on PATH if your shell cannot find mosaic.
2. Complete first-run setup
The versioned package install does not launch 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.