Skip to content

README.md

Latest commit

 

History

History
320 lines (225 loc) · 9.59 KB

README.md

File metadata and controls

320 lines (225 loc) · 9.59 KB
Raw

DotBlue

DotBlue is an enterprise AI assistant platform for teams that need agent management, runtime isolation, skill governance, enterprise administration, and private deployment in one stack.

Instead of stitching together a chat UI, auth, model settings, runtime hosting, IM integrations, and deployment scripts, DotBlue gives you a full-stack foundation for building, governing, and delivering AI assistants to real users.

Why DotBlue

  • Manage agents, conversations, skills, models, and enterprise access in one product
  • Run each agent in an isolated containerized runtime for safer execution boundaries
  • Support SaaS-style, self-hosted, and private deployment paths from the same codebase
  • Connect assistants to external channels instead of limiting them to an internal web chat

Who It Is For

  • Product and platform teams shipping AI assistants to internal or external users
  • Enterprise teams that need organizations, members, roles, invitations, and admin workflows
  • Developers and operators who want a self-hosted AI agent platform with a real product surface
  • Open-source builders who want a full-stack starting point instead of a thin SDK demo

Quick Start

The recommended way to try DotBlue is Docker Compose. It gives you the most complete end-to-end setup with the lowest local complexity.

Prerequisites

  • Docker Engine with Docker Compose available
  • Enough local resources to run postgres, redis, casdoor, dotblue, and web
  • A valid LLM API key for the provider you want to test
  • Free local ports for the default endpoints listed below

Start With Compose

  1. Go to the deployment directory.
cd deploy/compose
  1. Copy the environment template.
cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env
  1. Update the key values in .env.
  • Database passwords
  • Platform admin account information
  • DOTBLUE_LLM_API_KEY
  • Public URLs and ports
  1. Generate the local config files.

Linux/macOS:

./prepare-config.sh

Windows PowerShell:

.\prepare-config.ps1
  1. Start the full stack.
docker compose up -d --build

Default Local Endpoints

  • Web: http://localhost:19000
  • Backend: http://localhost:18080
  • Casdoor: http://localhost:18000

What Compose Starts

  • postgres
  • redis
  • casdoor
  • dotblue in all-in-one mode, with the worker loop embedded
  • web

Validate The Setup

After the containers are healthy:

  1. Open http://localhost:19000
  2. Confirm that the landing page or login flow is reachable
  3. Complete initialization through auto-install or the /setup page if needed
  4. Log in and verify you can create an agent and open the chat page

For a more detailed walkthrough, see deploy/compose/README.md.

What You Get

Agent Management

  • Create, edit, and delete agents
  • Configure a name and system prompt for each agent
  • Manage multiple agents for different roles and workflows

Real-Time Chat

  • Conversation list, message history, and auto-generated titles
  • Streaming responses and visible thinking states
  • Tool call and step records for better execution traceability

Enterprise Administration

  • Create and switch enterprises
  • Manage members, org units, roles, and invitations
  • Use an enterprise admin console for team collaboration and access control

Platform Configuration

  • Configure platform data paths and runtime ports
  • Manage platform-wide model access and provider credentials
  • Let platform admins manage global settings in one place

IM Integration

  • Configure and enable enterprise IM connections
  • Bind IM channels to agents
  • Route assistant interactions through channels such as Feishu, Slack, Telegram, Discord, QQ, Matrix, and Web

Skill Management

  • Create platform skills from scratch
  • Import external skills from connected hubs
  • Govern the skill lifecycle from catalog to agent installation
  • Inject installed skills into both Hermes and Nanobot runtimes

Current Support

  • Backend: Go 1.25, GoFrame, PostgreSQL
  • Frontend: React 19, TypeScript, Vite, Ant Design
  • Authentication: Casdoor
  • Runtime isolation: Docker-based agent runtimes
  • Models: centralized platform configuration with OpenAI-compatible and provider-specific runtime handling
  • Testing: Go *_test.go, Vitest

Repository Structure

.
├─ backend/          # Go backend: APIs, domain services, schema init, auto-install
├─ web/              # React frontend: landing page, login, setup, dashboard, chat, admin UI
├─ deploy/           # Deployment assets: Casdoor, DotBlue, and Compose quick start
├─ docs/             # Domain and product design notes
└─ README.md

Useful directories:

  • backend/internal/domains: core business domains such as agent, chat, conversation, enterprise, im, metering, and skill
  • backend/manifest/config: runtime and initialization config templates
  • web/src/domains: frontend pages and business modules
  • deploy/compose: one-command local or test environment startup

Local Development

Frontend

  1. Go to web/
  2. Copy .env.example to .env.local
  3. Configure Casdoor and backend URLs
  4. Start the dev server
cd web
npm install
npm run dev

Common commands:

npm run build
npm run lint
npm run test

Backend

  1. Go to backend/
  2. Prepare PostgreSQL
  3. Copy manifest/config/config.example.yaml to manifest/config/config.yaml
  4. If you want auto-install, also copy manifest/config/init_data.example.json to manifest/config/init_data.json
  5. Set the required environment variables
  6. Start the service
cd backend
go run .

Recommended for first-time setup:

export DOTBLUE_ADMIN_PASSWORD='replace-with-a-strong-password'
export DOTBLUE_LLM_API_KEY='replace-with-provider-key'

Windows PowerShell:

$env:DOTBLUE_ADMIN_PASSWORD='replace-with-a-strong-password'
$env:DOTBLUE_LLM_API_KEY='replace-with-provider-key'
go run .

At startup, the backend automatically performs:

  • Casdoor initialization
  • Database connectivity checks
  • Database schema initialization
  • Auto-install based on init_data.json

Configuration

Backend

  • Runtime template: backend/manifest/config/config.example.yaml
  • Initialization template: backend/manifest/config/init_data.example.json
  • Recommended local files:
    • backend/manifest/config/config.yaml
    • backend/manifest/config/init_data.json

Notes:

  • organization.name and application.name must match the backend Casdoor configuration
  • Do not commit sensitive values; inject them through environment variables when possible
  • If no initialization file is provided, the Web setup page at /setup still works as a fallback

Frontend

Key environment variables:

  • VITE_CASDOOR_SERVER_URL
  • VITE_CASDOOR_CLIENT_ID
  • VITE_CASDOOR_ORG_NAME
  • VITE_CASDOOR_APP_NAME
  • VITE_BACKEND_URL

The container image also supports runtime overrides through /runtime-config.js, so private deployments can reuse the same dotblue-web image without rebuilding for each environment.

API and UI Overview

The frontend includes:

  • Landing page
  • Login and login callback
  • Setup wizard
  • Dashboard and agent management
  • Chat page
  • Enterprise admin console
  • Platform settings page
  • Skill market, skill builder, skill governance, and dedicated agent skill management pages

The backend exposes:

  • /api/setup/*: setup and installation
  • /api/agents: agent CRUD
  • /api/conversations: conversations and messages
  • /api/chat: chat interface
  • /api/admin/settings: platform settings
  • /api/admin/*: enterprise and IM administration
  • /api/admin/skills*, /api/admin/platform/skill-hubs*, /api/admin/platform/skill-import-jobs*: skill governance, connected hubs, and import workflows
  • /api/admin/agents/:agentId/skills*: install, list, and remove skills on a target agent

Also available by default:

  • OpenAPI: /api.json
  • Swagger: /swagger

Known Caveats

  • If you update the platform-level model or provider settings after agent containers have already started, recycle or restart the existing hermes_* agent containers before re-testing. Running agent containers keep their existing runtime config until they are recreated.
  • For skill-related end-to-end checks, prefer the local Compose environment and real browser verification. A typical validation flow is: import or create a skill -> install it to an agent -> open the chat page -> confirm the assistant actually uses the installed skill.

Documentation Map

  • Root overview: README.md
  • Compose deployment guide: deploy/compose/README.md
  • Backend setup notes: backend/README.MD
  • Frontend environment notes: web/README.md
  • Domain design docs:
    • docs/skill-system-design.md
    • docs/skill-backend-design.md
    • docs/skill-frontend-design.md
    • docs/skill-database-design.md
    • docs/credit-domain-design.md

CI and Container Images

Every push and pull request runs .github/workflows/ci.yml, which lints, type-checks, builds, and tests both the backend and the web app, and builds both Docker images as a smoke test.

Cutting a tag of the form vX.Y.Z (for example v0.1.0) triggers .github/workflows/release.yml, which:

  • builds and pushes release tags of the backend and web images to GitHub Container Registry
  • drafts a GitHub release with auto-generated notes

Once a tag is pushed, users can pull pre-built images directly instead of building from source. Replace <owner> with the GitHub owner of this repository:

docker pull ghcr.io/<owner>/dotblue:v0.1.0
docker pull ghcr.io/<owner>/dotblue-web:v0.1.0

The backend image is published as dotblue, and the frontend image is published as dotblue-web.