Inside a Bonsai Pod: Technical Architecture Explained

If you’re evaluating Bonsai Pods, you probably want to know what’s actually under the hood. What components make up a Pod? How do they interact? What can you customize?

This technical deep-dive covers the architecture of a Bonsai Pod—from the base infrastructure through the AI operator layer. Whether you’re making a buying decision or just curious about how it all works, this guide explains the technical foundation.

Architecture Overview

A Bonsai Pod consists of four interconnected layers:

┌─────────────────────────────────────────────────────┐
│  LAYER 4: Visibility & Communication                │
│  └── Discord integration, notifications, approvals  │
├─────────────────────────────────────────────────────┤
│  LAYER 3: AI Operator (Sensei)                      │
│  └── Monitoring, proposals, execution, learning     │
├─────────────────────────────────────────────────────┤
│  LAYER 2: Application Stack                         │
│  └── WordPress/custom apps, databases, services     │
├─────────────────────────────────────────────────────┤
│  LAYER 1: Infrastructure (LEMP)                     │
│  └── Linux, Nginx, MariaDB, PHP                     │
└─────────────────────────────────────────────────────┘

Each layer builds on the one below it. Let’s examine each in detail.

Layer 1: Infrastructure (LEMP Stack)

The foundation of every Bonsai Pod is a production-ready LEMP stack:

Linux (Ubuntu 22.04 LTS)

• Why Ubuntu: Stable, well-documented, extensive package availability
• LTS release: Security updates through 2027, no forced major upgrades
• Non-root operation: Daily work happens as the bonsai user, not root
• UFW firewall: Enabled by default, SSH only until you configure additional ports

Nginx

• High-performance web server: Handles static files, reverse proxying, SSL termination
• Configuration: Pre-tuned for common use cases, fully customizable
• SSL/TLS: Let’s Encrypt certificates with automatic renewal
• Gzip compression: Enabled for text-based assets

MariaDB

• MySQL-compatible: Drop-in replacement with performance improvements
• Security hardening: Remote root disabled, secure defaults
• Automated backups: Scheduled dumps with retention policies
• Query optimization: Sensible buffer and cache settings

PHP (8.2+)

• PHP-FPM: FastCGI process manager for performance
• Extensions: Common extensions pre-installed (mysqli, curl, gd, etc.)
• Composer: Dependency management available
• OPcache: Enabled for production performance

Layer 2: Application Stack

On top of the infrastructure layer, your applications run:

WordPress (Bedrock)

For WordPress sites, we use Bedrock—a modern WordPress boilerplate:

• Composer-based: Manage WordPress and plugins as dependencies
• Environment separation: Different configs for dev/staging/production
• Security improvements: Non-standard folder structure, hardened wp-config
• Git-friendly: Core files not in repo, only your customizations

Sage Theme Framework

For theme development:

• Modern build process: Webpack/Vite for asset compilation
• Blade templating: Laravel’s templating engine for cleaner code
• Tailwind CSS: Available if desired
• Hot reloading: Development server with instant updates

Custom Applications

Not using WordPress? No problem:

• Node.js applications: Install any version, PM2 for process management
• Python applications: Flask, Django, FastAPI—your choice
• Static sites: Build locally, deploy built files
• Docker: Available if containerization is your preference

Layer 3: AI Operator (Sensei)

This is where Bonsai Pods diverge from traditional infrastructure. Sensei is an AI operator that actively manages your Pod.

Core Components

Monitoring daemon:

• Continuous system metrics collection (CPU, memory, disk, network)
• Service health checks (Nginx, PHP-FPM, MariaDB)
• Log analysis for errors and anomalies
• Application-level monitoring (response times, error rates)

Analysis engine:

• Pattern recognition across metrics and logs
• Anomaly detection beyond simple thresholds
• Trend analysis for capacity planning
• Context-aware alerting (knows about deployments, time of day)

Proposal system:

• Generates actionable recommendations with reasoning
• Categorizes by urgency and risk level
• Provides clear explanations of what and why
• Tracks proposal history and outcomes

Execution engine:

• Carries out approved actions reliably
• Full logging of all operations
• Rollback capabilities for reversible changes
• Rate limiting to prevent cascading actions

Autonomous vs. Gated Actions

Autonomous (no approval needed):

• Health checks and alerting
• Log rotation and cleanup
• Certificate renewal
• Scheduled backups
• Metric collection

Gated (requires your approval):

• Deployments
• Configuration changes
• Database operations
• New service installations
• Security modifications

See how it works for more on the approval workflow.

Layer 4: Visibility & Communication

The top layer handles human-AI interaction:

Discord Integration

Channels structure:

• #status: Daily briefings and health summaries
• #alerts: Important notifications requiring attention
• #approvals: Pending actions waiting for your approval
• #logs: Detailed operation logs (optional, can be noisy)

Interaction modes:

• Notifications: Sensei posts updates you need to see
• Approvals: React to approve/reject proposed actions
• Conversation: Ask Sensei questions in natural language
• Commands: Trigger specific operations via messages

CLI Integration (pod command)

For terminal-oriented workflows:

pod status        # System health overview
pod logs          # Watch Sensei activity
pod push "msg"    # Commit and push changes
pod deploy        # Trigger deployment
pod ssh           # Connect to your Pod

Data Flow: How It All Connects

Here’s how a typical operation flows through the system:

1. Detection: Sensei’s monitoring daemon notices disk usage at 82%
2. Analysis: Analysis engine identifies old logs as the primary consumer
3. Proposal: Sensei generates a proposal: “Archive logs older than 30 days”
4. Notification: Proposal posted to Discord #approvals channel
5. Approval: You react with ✅ to approve
6. Execution: Sensei archives old logs, verifies disk space recovered
7. Reporting: Summary posted to #status: “Disk usage reduced to 54%”

The entire loop happens without you writing scripts, SSH-ing in, or remembering commands.

Security Architecture

Security is built into every layer:

• Infrastructure: UFW firewall, SSH key auth only, fail2ban
• Application: Non-root operation, file permissions hardening
• AI operator: Scoped permissions, gated actions, full audit logs
• Communication: Discord webhook security, no credentials in logs

Credentials and secrets live in configs/pod.env with restricted permissions—never logged, never posted.

Customization Points

Everything is customizable. Common modifications:

• Nginx configs: Add sites, tune caching, configure proxies
• PHP settings: Adjust memory limits, upload sizes, timeouts
• Sensei behavior: Adjust alert thresholds, add custom checks
• Backup schedules: Change frequency, retention, destinations
• Additional services: Redis, Elasticsearch, whatever you need

Questions?

This overview covers the major architectural components. For specific technical questions, check our FAQ or reach out directly.

Ready to see it in action? Get started →