---
title: Mosaic Stack Quickstart
type: guide
audience: user
status: current
source_of_truth: 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](../../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

> **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/mosaic@0.0.49`. Pin the exact package version and verify its published artifact integrity before installation:

```bash
registry='https://git.mosaicstack.dev/api/packages/mosaicstack/npm/'
package='@mosaicstack/mosaic@0.0.49'
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](https://git.mosaicstack.dev/mosaicstack/-/packages/npm/%40mosaicstack%2Fmosaic/0.0.49) 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:

```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)