docs: create user quickstart

2026-08-10 16:40:14 -05:00
parent bcd174f89e
commit 571a3d54b5
6 changed files with 153 additions and 11 deletions
@@ -0,0 +1,134 @@
+---
+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)