fix(installer): one-command keyless install with proper flag handling (P0-1)

.github/workflows/ci.yml

@@ -64,6 +64,43 @@ jobs:
       - name: Syntax-check MCP sources
         run: find mcp -name '*.js' -not -path '*/node_modules/*' -print0 | xargs -0 -n1 node --check
 
+  shellcheck:
+    name: shellcheck (installer scripts)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+      - name: Lint installer scripts
+        run: |
+          shellcheck --severity=warning \
+            scripts/self-host/install.sh \
+            scripts/self-host/remote-install.sh \
+            scripts/self-host/bootstrap-server.sh \
+            scripts/self-host/uninstall.sh \
+            scripts/self-host/status.sh \
+            scripts/self-host/smoke-test.sh
+
+  installer-args:
+    name: installer args smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: install.sh --help exits 0
+        run: ./scripts/self-host/install.sh --help
+      - name: install.sh --version exits 0
+        run: ./scripts/self-host/install.sh --version
+      - name: remote-install.sh --help exits 0
+        run: ./scripts/self-host/remote-install.sh --help
+      - name: remote-install.sh --version exits 0
+        run: ./scripts/self-host/remote-install.sh --version
+      - name: Unknown arg exits non-zero
+        run: |
+          if ./scripts/self-host/install.sh --unknown-arg 2>/dev/null; then
+            echo "Expected non-zero exit for unknown arg"
+            exit 1
+          fi
+
   compose-build:
     name: docker compose build
     runs-on: ubuntu-latest

README.md

@@ -29,13 +29,47 @@ DeepSQL Desktop first ship + Agent/Brain/Editor hardening. Notes:
 curl -fsSL https://deepsql.ai/install.sh | bash
 ```
 
-This checks prerequisites, clones the latest release to `~/deepsql`, and guides you
-through configuration. See [`scripts/self-host/remote-install.sh`](scripts/self-host/remote-install.sh)
-for options (`--yes` for noninteractive, `--branch` for a specific version).
+This clones the latest release to `~/deepsql`, runs the full install, and prints the
+login URL and credentials location. The only input you need is an LLM API key — or skip
+it and configure the key later during onboarding in the web UI.
+
+**Options:** `--non-interactive`, `--fresh` (clean install), `--no-seed-demo`,
+`--ref v1.3.0` (specific version). See
+[`scripts/self-host/remote-install.sh`](scripts/self-host/remote-install.sh) for the
+full list.
 
 > The script source of truth is [`scripts/self-host/remote-install.sh`](scripts/self-host/remote-install.sh)
 > in this repository. `deepsql.ai/install.sh` serves a copy for the homepage CTA.
 
+### For AI agents
+
+If you are a coding agent (Claude, Cursor, Codex) setting up DeepSQL for a user:
+
+1. **Ask the user for one input:** their LLM API key (OpenAI `sk-...`, Azure, etc.).
+   This is optional — the stack runs without a key and the user can add it later.
+
+2. **Run the install:**
+   ```bash
+   DEEPSQL_LLM_API_KEY=<key> curl -fsSL https://deepsql.ai/install.sh | bash
+   ```
+   Or without a key:
+   ```bash
+   DEEPSQL_INITIAL_ADMIN_EMAIL=admin@example.com curl -fsSL https://deepsql.ai/install.sh | bash
+   ```
+
+3. **Verify the install:**
+   ```bash
+   curl -fsS http://localhost:8080/api/actuator/health
+   ```
+
+4. **Tell the user:**
+   - Login URL: **http://localhost:3000**
+   - Login email and password: stored in `~/deepsql/.env`
+   - If no LLM key was provided: configure it during onboarding in the web UI
+
+The installer prints `NEEDS_USER_INPUT: ...` lines for any missing optional inputs,
+then exits 0 with all services running.
+
 ### Step-by-step
 
 Five steps, in order. Budget about fifteen minutes, most of it waiting on the first build.

agent/docker-entrypoint.sh

@@ -33,11 +33,18 @@ API_KEY="${DEEPSQL_CHAT_API_KEY:-${AZURE_OPENAI_KEY:-}}"
 ENDPOINT="${DEEPSQL_CHAT_ENDPOINT:-${AZURE_OPENAI_ENDPOINT:-}}"
 MODEL="${DEEPSQL_CHAT_MODEL:-gpt-5.4}"
 
+# Keyless start: allow the agent to start without an LLM key. It will serve
+# health endpoints but agent operations will fail with a clear message.
+KEYLESS_MODE=0
 if [[ -z "$API_KEY" ]]; then
-  log "ERROR: DEEPSQL_CHAT_API_KEY (or AZURE_OPENAI_KEY) must be set."
-  exit 1
+  log "WARNING: No LLM key configured. Agent will start in degraded mode."
+  log "         Configure DEEPSQL_LLM_API_KEY and restart to enable AI features."
+  KEYLESS_MODE=1
+  # Use placeholder values so the runtime doesn't crash on startup.
+  API_KEY="not-configured"
+  ENDPOINT="${ENDPOINT:-https://api.openai.com/v1}"
 fi
-if [[ -z "$ENDPOINT" ]]; then
+if [[ -z "$ENDPOINT" && "$KEYLESS_MODE" -eq 0 ]]; then
   log "ERROR: DEEPSQL_CHAT_ENDPOINT (or AZURE_OPENAI_ENDPOINT) must be set."
   exit 1
 fi
@@ -46,6 +53,8 @@ if [[ -z "${AGENT_PROVISION_SECRET:-}" ]]; then
   exit 1
 fi
 
+export DEEPSQL_KEYLESS_MODE="$KEYLESS_MODE"
+
 if [[ ! -x "$VENV_PY" ]]; then
   log "ERROR: agent runtime venv missing at $VENV_PY"
   exit 1

docs/QUICKSTART.md

@@ -1,90 +1,106 @@
 # Quick Start Guide
 
-## ✅ Frontend Status
-**Frontend is currently running on:** http://localhost:3000
+## One-liner install
 
-You can access it in your browser now!
+```bash
+curl -fsSL https://deepsql.ai/install.sh | bash
+```
+
+This runs the complete install: clones the repo, builds the stack from source, and
+starts all services. The only input needed is an LLM API key — or skip it and
+configure later during onboarding in the web UI.
 
-## 🚀 Starting the Backend
+## What you need
 
-The backend requires Java 17+ and Maven. Here's how to set it up:
+- **Docker** with Compose v2 and buildx >= 0.17.0
+- **~4 GB of memory** available to Docker
+- **An LLM API key** (optional — can configure later)
 
-### Step 1: Install Java 17
+On a fresh Ubuntu/Debian server:
 
-**macOS (using Homebrew):**
 ```bash
-brew install openjdk@17
+curl -fsSL https://raw.githubusercontent.com/DeepSQLAI/deepsql/main/scripts/self-host/bootstrap-server.sh | sudo bash
 ```
 
-**Or download from:**
-- https://adoptium.net/ (recommended)
-- Select Java 17 LTS for macOS
+## With an LLM key
 
-**Verify installation:**
 ```bash
-java -version
-# Should show: openjdk version "17.x.x"
+DEEPSQL_LLM_API_KEY=sk-your-key curl -fsSL https://deepsql.ai/install.sh | bash
 ```
 
-### Step 2: Install Maven
+## Without an LLM key (keyless start)
 
-**macOS (using Homebrew):**
 ```bash
-brew install maven
+DEEPSQL_INITIAL_ADMIN_EMAIL=admin@example.com curl -fsSL https://deepsql.ai/install.sh | bash
 ```
 
-**Verify installation:**
-```bash
-mvn -version
-```
+Chat and AI features are disabled until you configure a key during onboarding in the web UI.
 
-### Step 3: Start the Backend
+## After install
 
-**Option A: Using the helper script**
-```bash
-./start-backend.sh
-```
+1. **Open** http://localhost:3000
+2. **Log in** with the email and password from `~/deepsql/.env`
+3. **Connect a database** (Postgres or MySQL)
+4. **Start asking questions** in the Agent tab
+
+## Verify the install
 
-**Option B: Manual start**
 ```bash
-cd backend
-mvn spring-boot:run
+curl -fsS http://localhost:8080/api/actuator/health
 ```
 
-The backend will start on: **http://localhost:8080**
+## Options
 
-### Step 4: Verify Both Services
+- `--non-interactive` — never prompt (use with env vars)
+- `--fresh` — remove existing volumes before install
+- `--no-seed-demo` — skip demo database seeding
+- `--ref v1.3.0` — install a specific version
 
-1. **Backend**: Open http://localhost:8080/api/connections
-   - Should return: `[]` (empty array)
+Example:
 
-2. **Frontend**: Already running at http://localhost:3000
-   - You should see the DBA Agent interface
+```bash
+curl -fsSL https://deepsql.ai/install.sh | bash -s -- --fresh --ref v1.3.0
+```
 
-## 🎯 Next Steps
+## Ports
 
-1. Open http://localhost:3000 in your browser
-2. Click the Settings icon (⚙️) in the left panel
-3. Connect to your MySQL or PostgreSQL database
-4. View schema visualizations and DBA stats!
+| Service  | Port | Override                |
+|----------|------|-------------------------|
+| Frontend | 3000 | `DEEPSQL_FRONTEND_PORT` |
+| Backend  | 8080 | `DEEPSQL_BACKEND_PORT`  |
+| Postgres | 5432 | `DEEPSQL_POSTGRES_PORT` |
+| Valkey   | 6379 | `DEEPSQL_VALKEY_PORT`   |
 
-## 📝 Notes
+## Troubleshooting
 
-- The frontend is already running in the background
-- You need to start the backend separately in a new terminal
-- Both services need to be running for full functionality
-- Backend stores encrypted credentials in `backend/data/vault.mv.db`
+**Docker permission denied:**
+```bash
+sudo usermod -aG docker $USER
+newgrp docker
+```
 
-## 🐛 Troubleshooting
+**buildx too old:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/DeepSQLAI/deepsql/main/scripts/self-host/bootstrap-server.sh | sudo bash
+```
 
 **Backend won't start:**
-- Ensure Java 17+ is installed: `java -version`
-- Ensure Maven is installed: `mvn -version`
-- Check if port 8080 is available: `lsof -i :8080`
+Check `docker compose logs backend` — usually a missing secret or port conflict.
+
+## Development
+
+For local development without Docker:
+
+```bash
+docker compose up -d postgres valkey
+cd backend && ./mvnw spring-boot:run    # http://localhost:8080/api
+npm install && npm run dev              # http://localhost:3000
+```
 
-**Frontend can't connect to backend:**
-- Ensure backend is running on port 8080
-- Check browser console for errors
-- Verify `.env.local` has: `NEXT_PUBLIC_API_URL=http://localhost:8080`
+Requires **JDK 25** and **Node 22**.
 
+## Next steps
 
+- [README.md](../README.md) — full documentation
+- [docs/llms-full.txt](llms-full.txt) — AI agent setup runbook
+- [mcp/README.md](../mcp/README.md) — CLI and MCP server