🏯 Shogun — Your AI Command Center

A local-first AI agent operating system with persistent memory, multi-agent orchestration, visual workflows, and governed autonomy.

Shogun is the AI orchestrator. The Tenshu is the browser-based command center where you configure, supervise, and communicate with it. Everything runs locally by default; no Docker or Shogun cloud account is required.

If you later need to manage several Shogun installations, add Gensui, the optional fleet-management platform. Install Shogun first, then Gensui.

Start here

I want to…	Install
Run my own governed AI command center	Shogun and The Tenshu
Let one administrator serve several people through Telegram or Teams	Shogun in Team mode
Run Shogun continuously in containers on a server or NAS	Shogun Server mode
Centrally manage multiple Shogun installations	Gensui after installing Shogun

Shogun and The Tenshu

Shogun is the primary AI agent and orchestrator. It remembers context, delegates to specialized Samurai agents, selects models, runs governed tools, and coordinates long-running work.

The Tenshu is Shogun's mission-control interface. It provides chat, memory, model and tool configuration, Agent Flows, Flow Stacks, security controls, audit logs, skills, integrations, and system administration without requiring terminal commands.

Install Shogun and The Tenshu

Download one installer from the latest GitHub release:

Platform	Installer	Run it
Windows	⬇️ Shogun-Install.bat	Double-click the downloaded file
macOS	⬇️ Shogun-Install.command	Double-click the downloaded file

The installer downloads Shogun, creates the Python environment, installs dependencies, builds The Tenshu, creates a desktop shortcut, and opens the Setup Wizard.

Shogun requires Python 3.10+. Frontend builds and CI use Node.js 22.12+; .nvmrc and .node-version pin the supported major.

Complete the Setup Wizard

The nine-step Setup Wizard guides you through:

1. Language, Single-user or Team mode, and user identity
2. Local data directory
3. Shogun identity and behavior
4. Constitution and mandate
5. AI model providers
6. Model-routing profile
7. Fallback models
8. Optional Ronin desktop control
9. Configuration review and activation

Changing the language updates the wizard immediately. All setup screens are available in the 15 supported languages.

Single-user and Team mode

Choose the operating mode during installation:

Mode	How it works
Single-user mode	One Primary Admin uses Shogun and The Tenshu personally.
Team mode	One Primary Admin operates The Tenshu. Team members communicate with Shogun through Telegram or Microsoft Teams.

In Team mode:

• The Primary Admin is the only person with platform and administrative authority.
• Any number of team members can be configured during setup.
• Each member is mapped to a Telegram or Microsoft Teams identity.
• Shogun maintains a separate identity and pinned-memory context for each member.
• Private member context is isolated and is not disclosed to other members.
• Team members cannot invoke Primary Admin-only operations such as HARAKIRI.

Server mode (Docker)

Server mode runs Shogun and The Tenshu continuously in containers with dedicated PostgreSQL and Qdrant services. It is the recommended deployment for an always-on Team-mode installation.

Prerequisite: Install Docker Desktop on Windows/macOS, or Docker Engine with the Docker Compose plugin on Linux. The server installer downloads the Shogun source and builds the application image locally.

Platform	Server installer	Run it
Linux/macOS server	⬇️ Shogun-Server-Install.sh	Run bash Shogun-Server-Install.sh
Windows Server/Desktop	⬇️ Shogun-Server-Install.bat	Double-click the downloaded file

The Server installer:

• Generates independent application, vault-encryption, infrastructure-admin, and PostgreSQL secrets.
• Builds Shogun and The Tenshu as a non-root container.
• Starts PostgreSQL and Qdrant on an internal Docker network.
• Stores application data, memories, configuration, vault content, and logs in named volumes.
• Enables health checks and automatic restart.
• Preserves .env.server and Docker volumes during upgrades.
• Keeps The Tenshu bound to 127.0.0.1 by default.

After installation, the Primary Admin opens http://127.0.0.1:8000/setup on the server and selects Single-user or Team mode. Team members communicate through Telegram or Microsoft Teams; they do not receive access to The Tenshu.

Privileged Gensui connection and Nexus peer-invitation actions require the generated infrastructure token in Server mode. Paste it into the corresponding Tenshu field; it is kept only for the browser-tab session. See the outbound destination security guide.

Secure by default: Do not change SHOGUN_BIND_ADDRESS to a public interface without placing The Tenshu behind an authenticated HTTPS reverse proxy. For remote administration, prefer a VPN or SSH tunnel.

Important — Ronin does not work in Server mode: A container cannot safely access the server's physical desktop. Ronin screenshots, mouse and keyboard control, native application control, and host-desktop sessions are therefore disabled and rejected by the server. Selecting the Torii posture named RONIN does not override this container boundary. Use a normal desktop installation when Ronin Desktop Control is required.

Mado browser automation still works because its managed Chromium browser runs inside the container. Agent Flows, Flow Stacking, Telegram, Teams, Nexus, memory, ToolGate, HARAKIRI, and externally hosted local-model services such as Ollama remain available.

See the Docker capability matrix and migration guide for the complete native-versus-headless scope.

Start Server mode from a source checkout

cp .env.server.example .env.server
# Replace every change-me value in .env.server.
docker compose --env-file .env.server -f docker-compose.server.yml up -d --build

Useful commands:

# Status
docker compose --env-file .env.server -f docker-compose.server.yml ps

# Shogun logs
docker compose --env-file .env.server -f docker-compose.server.yml logs -f shogun

# Stop containers without deleting persistent volumes
docker compose --env-file .env.server -f docker-compose.server.yml down

Launch, update, and uninstall

Platform	Launch Shogun
Windows	Double-click Shogun — The Tenshu on the Desktop
macOS	Open Shogun.app from the Desktop
Linux developer install	Open the generated shogun.desktop shortcut

The Tenshu opens at http://localhost:8000.

Updates can be installed from The Tenshu while preserving configuration, databases, and memories. To uninstall, run uninstall.bat on Windows or ./uninstall.sh on macOS/Linux from the Shogun installation directory.

Uninstalling removes the environment, databases, memories, shortcut, and installation directory. Back up anything you need first.

What Shogun can do

Agents, models, and memory

Feature	Description
Multi-model intelligence	Connect OpenAI, Anthropic, Google, Perplexity, OpenRouter, and local Ollama models.
Model Router	Route each task by complexity and type using five built-in profiles, model fallbacks, and usage telemetry.
Samurai agents	Create specialized sub-agents for research, coding, analysis, and other domains.
Persistent memory	Semantic memory with salience scoring, consolidation, search, and embedded Qdrant storage.
Active Skills	Retrieve relevant skills at runtime, gate them by policy, inject them into context, and track outcomes.
Dojo and OpenClaw College	Browse, install, certify, and update thousands of agent skills.
SkillOpt	Generate, validate, compare, promote, or reject improved skill versions using captured outcomes.

Workflows and long-running execution

Feature	Description
Agent Flow	Build visual multi-step workflows with agents, tools, approvals, conditions, and browser actions.
Flow Stacking	Chain multiple Agent Flows into one governed, long-horizon execution plan.
Stack Orchestrator	Plan and supervise Flow Stacks with checkpoints, verification gates, approval modes, retries, state recovery, execution trees, and artifact capture.
Scheduled and autonomous work	Run approved tasks on schedules or through governed autonomous loops.
ALE Benchmark	Execute headless agent evaluations with trajectory, artifact, and verification exports.

Flow Stacking is available from Flow Stack in The Tenshu. A single Agent Flow handles one pipeline; a Flow Stack coordinates several flows as a persistent plan. The Stack Orchestrator can pause, resume, recover, retry, and verify that plan while retaining an auditable execution history.

Communication and integrations

Feature	Description
Telegram	Communicate with Shogun remotely with streaming responses and identity-aware Team mode.
Microsoft Teams	Connect organization members to their own governed Shogun identity and memory context.
Email and calendar	Use IMAP/SMTP mail and CalDAV calendars from the command center.
Nexus	Connect Shogun peers and external enterprise agents through A2A, webhook, and MCP adapters.
VS Code IDE mode	Govern file reads, patches, terminal commands, Git operations, and diagnostics through a workspace-bound bridge.

Browser, desktop, and visual work

Feature	Description
Mado browser automation	Browse, extract content, fill forms, and capture screenshots through a secured Playwright layer.
Ronin desktop control	Govern screenshots, mouse, keyboard, windows, and application trust levels with the Komainu guardian.
Visual Intake	Normalize, deduplicate, strip EXIF data, OCR, inspect, compare, and govern uploaded images.

Governance, safety, and operations

Feature	Description
Constitution and mandate	Define versioned rules, boundaries, and objectives that guide Shogun's behavior.
Security postures	Choose graduated security levels and fine-grained tool permissions.
ToolGate	Inspect each tool call, risk-score its parameters, and allow, confirm, or block execution.
HARAKIRI	Fail-closed emergency stop for active Telegram, Teams, Agent Flow, Flow Stack, and approval work.
Quarantine	Soft-delete files to .shogun_trash/ for recoverability instead of immediately destroying them.
Prompt-injection containment	Mark external content as untrusted before it enters model context.
Audit and compliance	Maintain HMAC-chained audit records and NIS2, SOC 2, and EU AI Act-oriented exports.
Backup and updates	Schedule backups, configure retention, and update without replacing user data.

Shogun architecture

Module	Responsibility
Shogun	Primary AI orchestrator and central decision-maker
The Tenshu	Browser-based mission control and administration
Samurai	Specialized sub-agents
Archives	Persistent semantic memory
Katana	Models, providers, tools, routing, and integrations
Kaizen	Constitution and governance rules
Bushido	Reflection, insights, and self-improvement
Torii	Select the active built-in or custom security posture and access emergency controls
ToolGate	Create and maintain custom postures; configure and enforce runtime capability boundaries
Dojo	Skills, certification, OpenClaw College, and SkillOpt
Agent Flow	Visual workflow construction and execution
Flow Stack	Composition of several Agent Flows
Stack Orchestrator	Persistent planning, checkpoints, verification, retry, and recovery
Mado	Governed browser automation
Ronin	Governed desktop automation
Nexus	Shogun-to-Shogun and enterprise-agent interoperability
Gensui	Optional central fleet management for multiple Shogun installations

Gensui — Agent Fleet Management

Gensui is not required to run Shogun. It is a separate command-and-control platform for organizations that operate multiple Shogun installations.

Install and configure each Shogun first. Add Gensui when you need centralized fleet visibility, enrollment, security policy, audit, and emergency control.

What Gensui provides

Capability	Description
Fleet dashboard	Monitor online state, versions, agents, workflows, and health across enrolled Shogun instances.
Network topology	Visualize fleet membership, Nexus peers, and external enterprise agents.
Discovery and rogue detection	Scan the LAN for enrolled, unenrolled, and unknown Shogun services.
Enrollment tokens	Issue, approve, reject, and revoke secure enrollment credentials.
Groups and posture management	Organize instances and distribute group or instance-level security policies.
Remote HARAKIRI	Trigger governed fleet emergency actions from soft freeze through full termination.
Central audit	Aggregate HMAC-chained events, telemetry, compliance reports, and SIEM-ready exports.
Enterprise identity	Configure service accounts, API key rotation, OIDC/SSO, role mapping, and domain restrictions.

Install Gensui

Download one installer from the latest GitHub release:

Deployment	Installer	Run it
Windows desktop	⬇️ Gensui-Install.bat	Double-click the downloaded file
macOS desktop	⬇️ Gensui-Install.command	Double-click the downloaded file
Linux/macOS Docker server	⬇️ Gensui-Docker-Install.sh	Run bash Gensui-Docker-Install.sh
Windows Docker server	⬇️ Gensui-Docker-Install.bat	Double-click the downloaded file

Gensui opens at http://localhost:8787. The Docker installers generate a random initial administrator password in the protected .env file; rotate it after first login.

Developer installation for Gensui

git clone https://github.com/AlphaHorizon-AI/Shogun.git
cd Shogun/gensui

# Windows
install.bat

# macOS or Linux
chmod +x install.sh
./install.sh

For an always-on server, use the Docker Compose configuration in gensui/. The server profile adds Nginx, TLS termination, security headers, rate limiting, and health checks.

Languages

The Tenshu and Setup Wizard support:

Language	Native name	Code
English	English	en
Danish	Dansk	da
German	Deutsch	de
Spanish	Español	es
French	Français	fr
Hindi	हिन्दी	hi
Italian	Italiano	it
Japanese	日本語	ja
Korean	한국어	ko
Norwegian	Norsk	no
Polish	Polski	pl
Portuguese	Português	pt
Swedish	Svenska	sv
Ukrainian	Українська	uk
Chinese	中文	zh

Developer installation

Install Shogun from source

git clone https://github.com/AlphaHorizon-AI/Shogun.git
cd Shogun

Platform	Command
Windows	Run install.bat
macOS/Linux	Run chmod +x install.sh && ./install.sh

Manual installation:

python -m venv venv
source venv/bin/activate        # macOS/Linux
# venv\Scripts\activate       # Windows

pip install -e .
cd frontend
npm install
npm run build
cd ..
python -m shogun

Endpoint	URL
The Tenshu	http://localhost:8000
Setup Wizard	http://localhost:8000/setup
API documentation	http://localhost:8000/docs

Technology

Area	Technology
Backend	Python, FastAPI, SQLAlchemy, Pydantic
Frontend	React, TypeScript, Vite, Tailwind CSS
Local data	SQLite and embedded Qdrant
Optional database	PostgreSQL
Browser automation	Playwright
Scheduling	APScheduler
Email and calendar	IMAP/SMTP and CalDAV
Fleet deployment	Docker, Docker Compose, and Nginx

Guides and downloads

• YouTube video guides
• Latest release and installers
• OpenClaw College
• VS Code bridge documentation
• Microsoft Teams bridge documentation

Optional installation telemetry

Shogun's privacy-preserving installation telemetry is disabled by default. It sends nothing until an administrator explicitly opts in, never collects operational content or personal identity, and can be previewed, withdrawn, or deleted from Privacy & Telemetry in The Tenshu. See the exact schema, frequency, firewall, Docker, and deletion documentation.

License

Proprietary — AlphaHorizon AI