Operations

Production Operations Runbook

Use this page after quickstart. It focuses on stable daily operations: channels, gateway, safety policy, observability, and regression gates.

1. Baseline profile and model policy

mosaic --project-state configure --show
mosaic --project-state models status
mosaic --project-state models aliases list
mosaic --project-state models fallbacks list

Keep at least one fallback model for network/provider instability scenarios.

Detailed setup: Models & Profiles.

2. Delivery channels (terminal/slack/telegram)

# add channels
mosaic --project-state channels add --name local-terminal --kind terminal
mosaic --project-state channels add --name team-slack --kind slack_webhook --endpoint https://hooks.slack.com/services/XXX/YYY/ZZZ
mosaic --project-state channels add --name team-telegram --kind telegram_bot --chat-id <chat_id> --token-env MOSAIC_TELEGRAM_BOT_TOKEN

# validate channels
mosaic --project-state channels list
mosaic --project-state channels test <channel_id>
mosaic --project-state channels capabilities
mosaic --project-state channels status

Detailed walkthrough: Channels Guide.

3. Gateway lifecycle

mosaic --project-state gateway install --host 127.0.0.1 --port 8787
mosaic --project-state gateway start
mosaic --project-state gateway status
mosaic --project-state gateway probe
mosaic --project-state gateway discover
mosaic --project-state gateway call status

Lifecycle details: Gateway Guide. Call contract details: Gateway Call API.

# maintenance operations
mosaic --project-state gateway restart
mosaic --project-state gateway stop

4. Safety controls (approvals + sandbox)

mosaic --project-state approvals get
mosaic --project-state approvals set confirm
mosaic --project-state approvals allowlist add "git status"

mosaic --project-state sandbox get
mosaic --project-state sandbox set standard
mosaic --project-state sandbox explain --profile restricted

Detailed setup: Approvals & Sandbox Policy.

5. Observability and diagnosis

mosaic --project-state status
mosaic --project-state health
mosaic --project-state doctor
mosaic --project-state dashboard

mosaic --project-state logs --tail 120
mosaic --project-state logs --follow
mosaic --project-state system presence
mosaic --project-state system event deploy.started --data '{"env":"prod"}'

6. Optional hardening checks

mosaic --project-state memory index --path . --namespace ops --incremental --stale-after-hours 24 --retain-missing
mosaic --project-state memory search "retry"
mosaic --project-state knowledge ingest --source local_md --path docs --namespace ops-kb --incremental
mosaic --project-state knowledge search "incident retry window" --namespace ops-kb

mosaic --project-state security audit --path . --deep
mosaic --project-state security audit --path . --min-severity medium --category supply_chain --category crypto_hardening --top 20
mosaic --project-state --json security audit --path . --sarif --sarif-output reports/security.sarif.json

7. Machine-readable operation mode

mosaic --project-state --json status
mosaic --project-state --json channels list
mosaic --project-state --json gateway probe
mosaic --project-state --json doctor

8. Regression gates (before release)

• At least one profile passes setup, models list, and ask.
• Main channel passes channels test and one real channels send.
• Gateway is healthy in status/probe/call.
• status/health/doctor/logs output contains no blocking errors.
• --json outputs are parsable by your CI scripts.

cd cli
./scripts/run_regression_suite.sh
./scripts/tutorial_regression.sh
# optional live smoke
LIVE=1 BASE_URL=https://api.openai.com MODEL=gpt-4o-mini ./scripts/tutorial_regression.sh

Full regression tutorial: Regression Guide.