feat: unify --local mode to run user agents alongside Hello World (#10)

README.md

@@ -18,7 +18,8 @@ A Python toolkit for building, managing, and connecting AI agents with full [Age
     - [3. Scaffold the controller](#3-scaffold-the-controller)
     - [(Optional) 4. Configure your Supervaize account \& environment](#optional-4-configure-your-supervaize-account--environment)
     - [5. Start the server 🚀](#5-start-the-server-)
-    - [6. Optional parameters](#6-optional-parameters)
+    - [6. Local mode](#6-local-mode)
+    - [7. Optional parameters](#7-optional-parameters)
     - [What's next?](#whats-next)
   - [Features](#features)
   - [Protocol Support](#protocol-support)
@@ -117,7 +118,22 @@ Once the server is running, you'll have:
 - **A2A discovery**: `/.well-known/agents.json`
 - **ACP discovery**: `/agents`
 
-### 6. Optional parameters
+### 6. Local mode
+
+Run the server locally without connecting to Studio:
+
+```bash
+supervaizer start --local
+```
+
+This starts the server with your agents from `supervaizer_control.py` alongside a built-in Hello World agent. If no `supervaizer_control.py` exists, only the Hello World agent is loaded.
+
+- **No Studio registration** — the server runs fully offline
+- **`SUPERVAIZER_LOCAL_MODE=true`** is set automatically
+- **API key** defaults to `local-dev` (override with `SUPERVAIZER_API_KEY`)
+- **Disable Hello World** by setting `SUPERVAIZER_DISABLE_HELLO_WORLD=true`
+
+### 7. Optional parameters
 
 Configure retry behavior for HTTP requests to the Supervaize API:
 

docs/CHANGELOG.md

@@ -19,7 +19,7 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
-### Added
+### v0.10.27
 
 - **Agent Workbench** — Full-featured testing interface for agents directly from the admin panel. Four-zone layout with agent parameters, job control, execution monitor, and live console log. Supports starting/stopping jobs, real-time case and step tracking via HTMX polling, and Human-in-the-Loop (HITL) form rendering and submission. Job history panel lists all past executions with status badges.
   - Backend: `workbench_routes.py` with 8 FastAPI endpoints (page, start, stop, status, monitor, console, HITL answer, job history)
@@ -44,6 +44,15 @@ All notable changes to this project will be documented in this file.
 
 - **CI** – Python package workflow: dependency install now uses `uv sync --extra dev --extra deploy` (adds deploy extras for CI).
 
+### Unit Tests Results
+
+| Status     | Count |
+| ---------- | ----- |
+| ✅ Passed  | 433   |
+| 🤔 Skipped | 0     |
+| 🔴 Failed  | 0     |
+| ⏱️ in      | 50s   |
+
 ## v0.10.19
 
 ### Added
@@ -134,7 +143,6 @@ All notable changes to this project will be documented in this file.
 ### Added
 
 - **🚀 Cloud Deployment CLI** - Complete automated deployment system for Supervaizer agents
-
   - Full implementation of [RFC-001: Cloud Deployment CLI](docs/rfc/001-cloud-deployment-cli.md)
   - Support for three major cloud platforms:
     - **Google Cloud Run** with Artifact Registry and Secret Manager
@@ -155,12 +163,10 @@ All notable changes to this project will be documented in this file.
   - See [Local Testing Documentation](docs/LOCAL_TESTING.md) for details
 
 - **Agent Instructions Template** - New HTML page served by FastAPI for Supervaize integration instructions
-
   - Accessible at `/admin/supervaize-instructions`
   - Provides step-by-step setup guide for agents
 
 - **Version Check Utility** - Automatic check for latest Supervaizer version
-
   - Helps users stay up-to-date with latest features and fixes
   - Located in `supervaizer.utils.version_check`
 
@@ -172,7 +178,6 @@ All notable changes to this project will be documented in this file.
 ### Changed
 
 - **🔄 Protocol Unification** - Removed ACP protocol in favor of unified A2A protocol
-
   - Removed `src/supervaizer/protocol/acp/` directory and all ACP-specific code
   - Removed `acp_endpoints` parameter from Server class
   - Removed ACP route registration and test files
@@ -182,7 +187,6 @@ All notable changes to this project will be documented in this file.
   - **Breaking Change**: `acp_endpoints` parameter no longer accepted in Server initialization
 
 - **📦 Dependency Optimization** - Cloud SDKs moved to optional dependencies
-
   - Base package size significantly reduced
   - Cloud deployment dependencies now optional: `pip install supervaizer[deploy]`
   - Optional `deploy` group includes: boto3, docker, google-cloud-artifact-registry, google-cloud-run, google-cloud-secret-manager, psutil
@@ -242,7 +246,6 @@ All notable changes to this project will be documented in this file.
 ### Changed
 
 - **Parameter Validation System**: Refactored to provide separate validation endpoints for different concerns
-
   - **Agent Parameters**: Now validated separately through `/validate-agent-parameters` endpoint
   - **Method Fields**: Now validated separately through `/validate-method-fields` endpoint
   - **Clean Architecture**: Removed legacy endpoint for cleaner, more focused API design

docs/CLI.md

@@ -58,8 +58,19 @@ supervaizer start --debug --reload
 
 # Set log level
 supervaizer start --log-level=DEBUG
+
+# Run in local mode (no Studio registration)
+supervaizer start --local
 ```
 
+**Local mode (`--local`):**
+
+Starts the server without connecting to Studio. Your agents from `supervaizer_control.py` run alongside a built-in Hello World agent. If no `supervaizer_control.py` exists, only Hello World is loaded.
+
+- `SUPERVAIZER_LOCAL_MODE=true` is set automatically
+- API key defaults to `local-dev` (override with `SUPERVAIZER_API_KEY`)
+- Set `SUPERVAIZER_DISABLE_HELLO_WORLD=true` to deactivate the Hello World agent
+
 ### deploy
 
 Automated deployment to cloud platforms. Requires installation with deploy extras: `pip install supervaizer[deploy]`
@@ -246,6 +257,8 @@ All CLI options can also be configured through environment variables:
 | SUPERVAIZER_FORCE_INSTALL | Force overwrite existing file    | false                         |
 | SUPERVAIZER_PRIVATE_KEY   | RSA private key (PEM string)     | generated at runtime if unset |
 | SUPERVAIZER_SERVER_ID     | Stable server instance ID (UUID) | generated at runtime if unset |
+| SUPERVAIZER_LOCAL_MODE    | Enable local mode (true/false)   | false                         |
+| SUPERVAIZER_DISABLE_HELLO_WORLD | Disable built-in Hello World agent in local mode | false |
 
 **Serverless (e.g. Vercel):** On serverless platforms, each instance may be a new process. Set `SUPERVAIZER_PRIVATE_KEY` and `SUPERVAIZER_SERVER_ID` in the platform's environment variables so the same key and ID are used across instances. Otherwise every cold start generates a new key and server ID.