docs: create user quickstart
This commit is contained in:
Jason Woltje
@@ -1,6 +1,6 @@
|
||||
# User Guide
|
||||
|
||||
> **Status:** Scaffold only. No legacy page has been promoted into this book yet.
|
||||
> **Status:** Initial migration active. The quickstart is current; additional user pages remain to be migrated.
|
||||
|
||||
This book is the canonical home for end-user workflows, user-visible behavior, product concepts, and user troubleshooting. Keep installation, deployment, security controls, and recovery procedures in [`ADMIN-GUIDE/`](../ADMIN-GUIDE/); keep implementation detail in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/).
|
||||
|
||||
@@ -8,16 +8,20 @@ This book is the canonical home for end-user workflows, user-visible behavior, p
|
||||
|
||||
- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
|
||||
- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths.
|
||||
- [Quickstart candidate](../QUICKSTART.md) — currently empty; it is not yet a usable guide.
|
||||
- [Quickstart](getting-started/quickstart.md) — install Mosaic, complete setup, and launch a session.
|
||||
|
||||
## Chapter map
|
||||
|
||||
| Chapter | Scope | Status |
|
||||
| ------------------ | ------------------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| `getting-started/` | First-use setup, orientation, and quickstarts. | Scaffold only; `QUICKSTART.md` is the migration candidate. |
|
||||
| `concepts/` | User-facing terminology, product concepts, and mental models. | Scaffold only. |
|
||||
| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Scaffold only. |
|
||||
| `troubleshooting/` | User-visible failures, diagnostics, and fixes. | Scaffold only. |
|
||||
| Chapter | Scope | Status |
|
||||
| ------------------ | ------------------------------------------------------------- | ---------------------------------------------------- |
|
||||
| `getting-started/` | First-use setup, orientation, and quickstarts. | Quickstart is current; additional pages are planned. |
|
||||
| `concepts/` | User-facing terminology, product concepts, and mental models. | Scaffold only. |
|
||||
| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Scaffold only. |
|
||||
| `troubleshooting/` | User-visible failures, diagnostics, and fixes. | Scaffold only. |
|
||||
|
||||
### Current pages
|
||||
|
||||
- [Quickstart](getting-started/quickstart.md) — the verified installed-CLI first-use path.
|
||||
|
||||
Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
|
||||
|
||||
@@ -26,7 +30,7 @@ Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP
|
||||
These are source candidates, not current user guidance:
|
||||
|
||||
- [`_old_structure/guides/user-guide.md`](../_old_structure/guides/user-guide.md) — historical source; verify every claim before promotion.
|
||||
- [`QUICKSTART.md`](../QUICKSTART.md) — incomplete zero-byte placeholder.
|
||||
The former root `QUICKSTART.md` was an empty placeholder and has been replaced by the current page above.
|
||||
|
||||
Do not link to the quarantine as a current user path. Create a new page only after classifying its audience, status, and evidence in the migration report.
|
||||
|
||||
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user