Quick Start (3 steps)

With just the CLI, you can have StarNion running in 3 steps.

Table of contents

• Prerequisites
• 3-Step Quick Start
  • Step 1: Install the CLI
  • Step 2: Run the Initial Setup Wizard
  • Step 3: Start the Services
• AI Provider Setup
  • Claude Code Subscription (Recommended)
  • Other Providers
• Your First Conversation
• Quick Reference Commands
• Next Steps

---

Prerequisites

Requirement	Minimum Version	How to Check
Node.js	20+	node --version
pnpm	latest	pnpm --version
uv	latest	uv --version
Docker Engine	24+	docker --version
Docker Compose	v2	docker compose version

# Install prerequisites if missing
npm install -g pnpm
curl -LsSf https://astral.sh/uv/install.sh | sh

Docker Desktop includes Docker Engine and Docker Compose.

---

3-Step Quick Start

Step 1: Install the CLI

curl -fsSL https://jikime.github.io/starnion/install.sh | bash

The installation script automatically installs:

• starnion CLI → /usr/local/bin/starnion
• starnion-gateway → ~/.starnion/bin/
• TypeScript agent → ~/.starnion/agent/
• Next.js web UI → ~/.starnion/web/
• Docker files → ~/.starnion/docker/

Step 2: Run the Initial Setup Wizard

starnion setup

The setup wizard guides you through 7 steps:

Step	Configuration Item
1	Language selection
2	System dependency check (Node.js, pnpm)
3	Database connection and migration
4	Create admin account (email + password)
5	File storage setup (MinIO)
6	Service configuration (ports, public URL)
7	AI provider detection (Claude Code auto-detect)

Step 3: Start the Services

Choose one of the following:

Option A — Binary mode (recommended):

starnion start

Option B — Docker mode:

starnion docker up -d

Option C — systemd (Linux production):

sudo cp ~/.starnion/scripts/starnion.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now starnion

---

AI Provider Setup

Claude Code Subscription (Recommended)

claude        # Start Claude Code CLI
/login        # Authenticate via browser

Credentials are saved to ~/.claude/.credentials.json and auto-detected on service start.

Other Providers

Configure Gemini, OpenAI, Ollama, and other providers in the web UI at Settings → Models after logging in.

Start for free: You can get a Gemini API key for free from Google AI Studio. https://aistudio.google.com

---

Your First Conversation

Open the web UI in your browser:

http://localhost:3893

Log in with the admin account you created during setup, then try:

Hello! Please introduce yourself.

---

Quick Reference Commands

# Start services
starnion start              # Binary mode (foreground)
starnion docker up -d       # Docker mode (background)

# Stop services
starnion docker down        # Docker mode
# Ctrl+C                    # Binary mode

# View logs
journalctl -u starnion -f   # systemd
starnion docker logs -f      # Docker

# Check status
starnion doctor              # System health check

# Update to latest version
starnion update

---

Next Steps

• Installation Guide — Detailed installation options and troubleshooting
• Configuration — Environment variables and advanced settings