GoogleCloudPlatform / GoogleCloudPlatform/scion
feat: streamlined onboarding and first-run bootstrap experience
- Dominant language
- Go
- Stars
- 1.7k
- Forks
- 263
- Avg merge
- 7h 6m
- Merged PRs (30d)
- 447
Description
## Problem
Getting Scion running for the first time requires high-friction CLI orchestration: manually cloning repos, building/pulling images, editing environment files, and seeding databases. The onboarding flow immediately exposes users to abstract concepts like "projects" and "brokers" when they just want to spin up their first coding agent on their local files.
Even with a working GCP account, valid service account keys, and prior experience on an existing hub, the setup process took **multiple hours of debugging with an AI coding agent assisting** and was ultimately unsuccessful. The gap between "I have credentials" and "I have a running agent" is far too wide.
## Proposal: Interactive CLI Onboarding (like `claude` CLI)
The best reference for what this should feel like is the **Claude Code CLI onboarding flow** — when you first run `claude`, it walks you through authentication, preferences, and workspace trust in an interactive TUI that feels lightweight and guided. Scion needs the same.
### `scion init` — Interactive First-Run Setup
A guided CLI/TUI onboarding flow that:
1. **Asks where your hub will run** — local Docker, remote GCE VM, Kubernetes, NAS, etc. Tailors subsequent steps to the chosen deployment target.
2. **Walks through authentication** — asks how you'll authenticate agents (Vertex AI, API key, OAuth token, auth file). Accepts a service account JSON key path and validates it in real time (checks Vertex AI API permissions, confirms the GCP project is reachable).
3. **Sets global defaults along the way** — as the user answers questions, the wizard writes a complete `settings.yaml` with sensible defaults. No separate "edit this YAML file" step. This directly addresses the config fragmentation in #511.
4. **Explains key concepts interactively** — brief, contextual explanations of projects, brokers, agents, and the configuration hierarchy *as they become relevant* during setup. Not a docs dump — just a sentence or two when the user first encounters each concept:
> "A **project** groups related agents and their configuration. Most users start with one project. You can add more later."
> "A **broker** is the runtime that runs your agent containers. Your local Docker daemon is the default broker."
5. **Validates the full stack before finishing** — after setup, runs verification checks (Docker accessible? Broker reachable? Auth working? Can we pull/build the agent image?) and shows a green/red checklist. If something fails, offers actionable next steps, not just an error message.
6. **Includes best practices** — GCP access patterns for local vs remote hardware, broker placement recommendations, when to use workstation mode vs hub mode.
7. **Ends with a running agent** — the final step should be "Start your first agent? [Y/n]" and spin up a coordinator or hello-world agent, proving the setup works end-to-end.
### Why CLI/TUI, not a web UI
- Runs before the hub is up (the hub can't serve a web wizard if it's not configured yet)
- Meets the user where they already are (terminal)
- Can be re-run (`scion init --reconfigure`) to update settings later
- The Claude CLI and `gh auth login` prove this pattern works well
### Stretch: GCP Verification Panel in Hub UI
Once the hub is running, a "System Health" panel in the web UI that shows:
- Service account permissions status
- API connectivity (Vertex AI, Cloud Trace, etc.)
- Broker and container runtime status
- Image sync status
This complements the CLI onboarding for ongoing operational visibility.
## Related Issues
- #511 — Unified configuration schema (the wizard should write this config)
- #245 — Not able to build images (setup tutorial)
- #137 — `build-images.sh` quickstart commands fail with 403 on first run
- #224 — Pull access denied on first run
- #254 — gemini-cli → antigravity-cli naming confusion during setup
- #182 — Docs for localhost registry
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the proposed `scion init` entry point and the unified configuration work in #511, then review the setup-related issues #245, #137, #224, and #182. Define a smaller first milestone covering target selection, credential validation, `settings.yaml` output, and verification checks. Done requires agreed scope and acceptance checks for the onboarding flow.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, gcp, kubernetes, yaml
- Domain
- cli, cloud, devops, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100