Introduction to botmaistro

What is botmaistro?

Unlike traditional chatbots that treat each interaction as isolated, botmaistro maintains persistent state across sessions, understands context from multiple modalities (text, voice, vision, code), and enforces governance policies at every layer of the stack.

The system is built on a five-plane architecture that separates concerns cleanly: runtime execution, cognitive processing, perception and action, governance and policy, and user experience.

Quick Start

Get up and running with botmaistro in under 5 minutes.

# Install botmaistro CLI
npm install -g @botmaistro/cli

# Initialize a new project
botmaistro init my-assistant

# Start the development server
cd my-assistant
botmaistro dev

Installation

botmaistro can be deployed in multiple ways depending on your infrastructure requirements.

Cloud Deployment

The fastest way to get started is with our managed cloud offering:

botmaistro deploy --provider cloud

Self-Hosted

For complete control, deploy botmaistro on your own infrastructure:

# Using Docker
docker pull botmaistro/platform:latest
docker run -p 8080:8080 -v $(pwd)/config:/config botmaistro/platform

# Using Kubernetes
kubectl apply -f https://get.botmaistro.ai/k8s/manifests.yaml

Core Concepts

Persistence

botmaistro maintains state across sessions. Every interaction builds on previous context, creating a continuous conversational thread rather than isolated exchanges.

Multimodality

The system processes multiple input types—text, voice, images, code—and can respond in kind. Context from one modality informs processing in others.

Policy Governance

Every action flows through the governance layer (Plane 3) where policies are enforced, access is controlled, and decisions are audited.

Operating Modes

Assistants can operate in multiple modes—interactive (human-in-the-loop), autonomous (independent execution), or orchestrated (multi-agent coordination).

The Five-Plane Stack

botmaistro's architecture is organized into five distinct layers, each with clear responsibilities:

Plane 0: Runtime Layer

The runtime layer executes tools, adapters, and background jobs. It provides deterministic execution, retries, and sandbox boundaries so higher planes can reason safely about outcomes.

Plane 1: Cognitive Layer

This layer handles planning, decomposition, memory strategies, and model routing. It turns high-level user goals into concrete, inspectable execution plans.

Plane 2: Perception Layer

The perception layer normalizes multimodal inputs, enriches context, and tags entities so decisions are based on structured signals instead of raw untyped data.

Plane 3: Governance Layer

Policies, role-based access, escalation paths, and audit events are enforced here. Every action is evaluated against constraints before execution.

Plane 4: Experience Layer

This layer delivers user-facing interactions across chat, dashboards, APIs, and embedded surfaces while preserving context continuity and explainability.

Interactive Mode

Human-in-the-loop collaboration for sensitive workflows. The assistant proposes actions and waits for explicit operator approval at each critical step.

Autonomous Mode

The assistant executes approved plans independently under policy limits, time budgets, and runtime safeguards.

Orchestrated Mode

Multi-agent specialization where coordinator and worker agents share context and synchronize through an event-driven pipeline.

Mode Transitions

Transition rules define when work may shift between interactive, autonomous, and orchestrated modes, including required approvals and rollback behavior.

Policy Engine

Policies are expressed as composable rules that evaluate actor, resource, intent, and risk context in real time.

Access Control

Fine-grained permissions map identities and service roles to allowed capabilities with explicit deny precedence.

Audit Logging

Immutable event streams capture prompts, tool calls, policy decisions, and outcome metadata for forensic and operational review.

Compliance

Control mappings support SOC 2, ISO 27001, and internal governance programs via evidence collection and periodic attestation workflows.

REST API

Use REST endpoints for session lifecycle, task submission, and status retrieval when request/response semantics are preferred.

WebSocket API

Use WebSocket channels for low-latency streaming updates, real-time task telemetry, and collaborative control loops.

SDK

Official SDKs for TypeScript and Python provide typed clients, retry middleware, and event hooks for production integrations.

CLI

The CLI supports bootstrap, local simulation, deployment, policy linting, and audit export from terminal workflows.

API Example

Here's a simple example of creating and invoking an assistant:

import { Botmaistro } from '@botmaistro/sdk';

const client = new Botmaistro({
  apiKey: process.env.BOTMAISTRO_API_KEY
});

// Create an assistant
const assistant = await client.assistants.create({
  name: 'Research Assistant',
  mode: 'autonomous',
  capabilities: ['web_search', 'code_execution'],
  policies: {
    rate_limit: { requests_per_hour: 100 },
    data_retention: { days: 30 }
  }
});

// Start a session
const session = await assistant.sessions.create({
  context: {
    user_id: 'user_123',
    project_id: 'proj_456'
  }
});

// Send a message
const response = await session.messages.create({
  content: 'Research the latest developments in quantum computing',
  mode: 'autonomous'
});

console.log(response.content);

Next Steps