Claude Flow Backend Plugin

The Claude Flow Backend provides session management, Docker container orchestration, and Vault integration for AI-assisted development environments.

Overview

Property	Value
Package	@internal/plugin-claude-flow-backend
Type	Backend
Plugin ID	claude-flow-backend
Database	PostgreSQL via Knex
Integration	Docker, Vault, Git

Architecture

API Endpoints

Health & Configuration

Method	Endpoint	Description
GET	/health	Health check
GET	/config	Backend configuration
POST	/sessions/recover	Manual session recovery

Sessions

Method	Endpoint	Description
GET	/sessions	List user sessions
GET	/sessions/:sessionId	Get session details
POST	/sessions	Create new session
PUT	/sessions/:sessionId	Update session
DELETE	/sessions/:sessionId	Delete session

Container Operations

Method	Endpoint	Description
POST	/sessions/:sessionId/start	Start Docker container
POST	/sessions/:sessionId/stop	Stop container
GET	/sessions/:sessionId/logs	Get container logs
GET	/sessions/:sessionId/auth-url	Get authenticated URL
GET	/sessions/:sessionId/stats	Get resource stats
GET	/sessions/:sessionId/stats/stream	Stream stats (SSE)
GET	/sessions/:sessionId/state	Get container state

Repositories & Configuration

Method	Endpoint	Description
GET	/repositories	List Git repositories
GET	/repositories/:repo/branches	Get repository branches
GET	/startup-scripts	List startup scripts
GET	/fuelix-tokens	Get FUELIX tokens

Vault Operations

Method	Endpoint	Description
GET	/vault/tokens	Get Vault tokens
POST	/vault/tokens	Create Vault token
GET	/vault/health	Vault health check

Templates

Method	Endpoint	Description
GET	/templates	List templates
POST	/templates	Create template
PUT	/templates/:id	Update template
DELETE	/templates/:id	Delete template
GET	/templates/search/:query	Search templates

Authorization

Method	Endpoint	Description
GET	/auth/users	List users (from catalog)
GET	/auth/groups	List groups
GET	/auth/user/:userRef/groups	Get user's groups

Services

SessionService

Manages the complete session lifecycle.

interface SessionService {
  create(input: CreateSessionInput, userId: string): Promise<Session>;
  get(sessionId: string): Promise<Session>;
  list(userId: string): Promise<Session[]>;
  update(sessionId: string, input: UpdateSessionInput): Promise<Session>;
  delete(sessionId: string): Promise<void>;
  start(sessionId: string): Promise<void>;
  stop(sessionId: string): Promise<void>;
}

DockerService

Handles Docker container operations.

interface DockerService {
  createContainer(config: ContainerConfig): Promise<Container>;
  startContainer(containerId: string): Promise<void>;
  stopContainer(containerId: string): Promise<void>;
  removeContainer(containerId: string): Promise<void>;
  getLogs(containerId: string): Promise<string>;
  getStats(containerId: string): Promise<ContainerStats>;
  getState(containerId: string): Promise<ContainerState>;
}

Features:

• Socket connection to Docker Engine
• Container lifecycle management
• Resource monitoring and stats streaming
• Log retrieval with tail options

VaultSecretsService

Integrates with HashiCorp Vault.

interface VaultSecretsService {
  getSecrets(path: string): Promise<Record<string, string>>;
  writeSecret(path: string, data: Record<string, string>): Promise<void>;
  listSecrets(path: string): Promise<string[]>;
}

TemplateService

Manages session templates.

interface TemplateService {
  list(): Promise<Template[]>;
  get(templateId: string): Promise<Template>;
  create(input: CreateTemplateInput): Promise<Template>;
  update(templateId: string, input: UpdateTemplateInput): Promise<Template>;
  delete(templateId: string): Promise<void>;
  search(query: string): Promise<Template[]>;
}

AuthorizationService

Backstage catalog integration for users and groups.

interface AuthorizationService {
  listUsers(): Promise<User[]>;
  listGroups(): Promise<Group[]>;
  getUserGroups(userRef: string): Promise<Group[]>;
}

ContainerMonitorService

Monitors container health and status.

interface ContainerMonitorService {
  startMonitoring(containerId: string): void;
  stopMonitoring(containerId: string): void;
  getHealth(containerId: string): Promise<HealthStatus>;
}

Database Schema

claude_flow_sessions

Column	Type	Description
id	UUID	Primary key
user_id	VARCHAR	Owner user reference
name	VARCHAR	Session name
status	VARCHAR	Session status
container_id	VARCHAR	Docker container ID
repository	VARCHAR	Git repository URL
branch	VARCHAR	Git branch
startup_script	VARCHAR	Startup script path
created_at	TIMESTAMP	Creation timestamp
updated_at	TIMESTAMP	Last update timestamp

claude_flow_templates

Column	Type	Description
id	UUID	Primary key
name	VARCHAR	Template name
description	TEXT	Template description
config	JSONB	Template configuration
owner	VARCHAR	Owner user reference
is_public	BOOLEAN	Public visibility
created_at	TIMESTAMP	Creation timestamp

Container Configuration

Sessions create Docker containers with:

interface ContainerConfig {
  image: string;
  name: string;
  env: Record<string, string>;
  volumes: VolumeMount[];
  ports: PortMapping[];
  workingDir: string;
  command: string[];
  labels: Record<string, string>;
}

Default Environment Variables:

• VAULT_ADDR - Vault server address
• VAULT_TOKEN - Session Vault token
• GIT_REPO - Repository URL
• GIT_BRANCH - Branch name

Related Documentation

• Claude Flow Frontend - Frontend plugin
• Vault Secrets Backend - Vault integration
• Plugins Overview