Architecture Overview

Station is designed as a lightweight, secure runtime for deployable sub-agents with a focus on simplicity, security, and production readiness.

System Architecture

graph TB
    subgraph "Client Interfaces"
        CLI[Station CLI<br/>stn command]
        API[REST API<br/>Port 8080]
        SSH[SSH/TUI Access<br/>Port 2222]
        WS[WebSocket<br/>Real-time updates]
    end
    
    subgraph "Core Runtime"
        Router[Request Router<br/>HTTP/SSH/WS]
        Auth[Authentication<br/>& Authorization]
        Queue[Execution Queue<br/>Background Processing]
        Scheduler[Agent Scheduler<br/>Cron & Events]
    end
    
    subgraph "Service Layer"
        AgentSvc[Agent Management<br/>Creation & Execution]
        MCPSvc[MCP Integration<br/>Tool Discovery]
        ConfigSvc[Configuration<br/>File-based Management]
        SecuritySvc[Security Services<br/>Encryption & Audit]
        WebhookSvc[Webhook Service<br/>Event Notifications]
    end
    
    subgraph "Data Layer"
        SQLite[(SQLite Database<br/>Built-in)]
        ConfigFiles[Config Files<br/>.json/.yml]
        SecretStore[Encrypted Secrets<br/>AES-256]
        AuditLog[Audit Logs<br/>JSON Lines]
    end
    
    subgraph "External Systems"
        MCPServers[MCP Servers<br/>Filesystem, AWS, etc.]
        AIProviders[AI Providers<br/>OpenAI, Anthropic]
        Webhooks[External Webhooks<br/>Slack, PagerDuty]
        VCS[Version Control<br/>Git repositories]
    end
    
    CLI --> Router
    API --> Router
    SSH --> Router
    WS --> Router
    
    Router --> Auth
    Auth --> Queue
    Auth --> Scheduler
    
    Queue --> AgentSvc
    Scheduler --> AgentSvc
    
    AgentSvc --> MCPSvc
    AgentSvc --> ConfigSvc
    AgentSvc --> SecuritySvc
    AgentSvc --> WebhookSvc
    
    ConfigSvc --> ConfigFiles
    SecuritySvc --> SQLite
    SecuritySvc --> SecretStore
    SecuritySvc --> AuditLog
    
    MCPSvc --> MCPServers
    AgentSvc --> AIProviders
    WebhookSvc --> Webhooks
    ConfigSvc --> VCS

Core Components

🏗️ Lightweight Runtime

Single Binary with embedded SQLite

  • Low Memory Footprint - Minimal resource usage
  • Container Optimized - Perfect for Docker/K8s
  • Multi-Interface - CLI, REST, SSH, WebSocket, MCP
  • Production Ready - Queue-based execution

🤖 Agent Management

Intelligent Sub-Agent Orchestration

  • Agent Lifecycle - Create, deploy, monitor, scale
  • Environment Isolation - Dev/staging/prod separation
  • Template System - Reusable agent bundles
  • Scheduling - Cron-based and event-driven

🔧 MCP Integration

Model Context Protocol Support

  • Tool Discovery - Automatic MCP server detection
  • Configuration Management - GitOps-ready configs
  • 20+ Built-in Tools - Filesystem, AWS, databases
  • Custom Tools - Easy integration of your tools

🔒 Security Layer

Enterprise-Grade Security

  • Self-Hosted - Complete data sovereignty
  • AES Encryption - Secrets and sensitive data
  • Audit Logging - Complete execution trail
  • Access Controls - Role-based permissions

Data Flow

sequenceDiagram
    participant User
    participant CLI
    participant Runtime
    participant Agent
    participant MCP
    participant AI
    
    User->>CLI: stn agent run 1 "task"
    CLI->>Runtime: POST /api/v1/agents/1/queue
    Runtime->>Runtime: Authenticate & validate
    Runtime->>Agent: Queue execution
    
    loop Agent Execution
        Agent->>MCP: Discover available tools
        MCP-->>Agent: Tool definitions
        Agent->>AI: Generate execution plan
        AI-->>Agent: Step-by-step actions
        Agent->>MCP: Execute tool calls
        MCP-->>Agent: Tool responses
        Agent->>Runtime: Update execution status
    end
    
    Agent->>Runtime: Execution complete
    Runtime->>CLI: Stream results
    CLI-->>User: Display output
    
    Note over Runtime: Audit log, webhooks,<br/>metrics collection

File System Layout

Station follows a standard configuration layout for predictable deployment:

# Development (default)
~/.config/station/
├── station.db              # SQLite database
├── environments/
│   ├── development/
│   │   ├── agents/          # Agent definitions (.prompt files)
│   │   ├── *.json           # MCP configurations
│   │   └── variables.yml    # Environment variables
│   ├── staging/
│   └── production/
├── secrets/                 # Encrypted secrets (AES-256)
├── audit/                   # Audit logs (JSONL)
└── cache/                   # Temporary execution cache

# Production (configurable)
/opt/station/
├── config/                  # Configuration files
├── data/                    # SQLite database
├── logs/                    # Application logs
└── backup/                  # Database backups

Environment Isolation

Station provides complete isolation between environments:

graph LR
    subgraph "Development"
        DevDB[(SQLite<br/>Development)]
        DevAgents[Dev Agents<br/>Test tools]
        DevVars[Dev Variables<br/>Local paths]
    end
    
    subgraph "Staging"
        StageDB[(SQLite<br/>Staging)]
        StageAgents[Staging Agents<br/>Safe tools]
        StageVars[Staging Variables<br/>Test credentials]
    end
    
    subgraph "Production"
        ProdDB[(SQLite<br/>Production)]
        ProdAgents[Production Agents<br/>All tools]
        ProdVars[Production Variables<br/>Real credentials]
    end
    
    DevDB -.-> StageDB
    StageDB -.-> ProdDB
    
    DevAgents -.-> StageAgents
    StageAgents -.-> ProdAgents
    
    DevVars -.-> StageVars
    StageVars -.-> ProdVars

Security Architecture

🔐 Encryption at Rest

  • AES-256 encryption for all secrets and sensitive variables
  • Encrypted database fields for credentials and tokens
  • Secure key derivation using PBKDF2 with salt
  • Key rotation support for long-term security

🚪 Access Control

  • Environment-based isolation prevents cross-environment access
  • Role-based permissions for different user types
  • API key authentication for programmatic access
  • SSH key authentication for secure terminal access

📊 Audit Trail

  • Complete execution logging for all agent activities
  • Configuration change tracking with Git integration
  • Access logging for all API and SSH connections
  • Compliance reporting for security audits

🌐 Network Security

  • TLS encryption for all external communications
  • Configurable firewall rules for port restrictions
  • Webhook signature validation for trusted notifications
  • Zero-trust architecture - verify all requests

Deployment Patterns

Single-Node Development

graph TB
    subgraph "Developer Machine"
        StationBin[Station Binary<br/>stn command]
        SQLiteDB[(SQLite<br/>Local database)]
        ConfigFiles[Config Files<br/>Git tracked]
        LocalMCP[Local MCP<br/>Filesystem tools]
    end
    
    StationBin --> SQLiteDB
    StationBin --> ConfigFiles
    StationBin --> LocalMCP

Production Deployment

Station is designed for simple, secure deployments:

graph TB
    subgraph "Production Environment"
        Station[Station Binary<br/>stn daemon]
        SQLiteDB[(SQLite Database<br/>Persistent storage)]
        ConfigDir[Configuration<br/>File-based configs]
        SecretsStore[Encrypted Secrets<br/>AES-256]
    end
    
    Station --> SQLiteDB
    Station --> ConfigDir
    Station --> SecretsStore

Key Features

🚀 Lightweight & Fast

  • Single Binary - No complex dependencies
  • SQLite Database - Built-in, no setup required
  • Fast Startup - Ready in seconds
  • Low Resource Usage - Minimal memory footprint

🔄 Reliable Operation

  • Queue-based Execution - Background processing
  • Error Recovery - Automatic agent restart on failure
  • Data Integrity - ACID compliance with SQLite
  • Comprehensive Logging - Full execution audit trail

Technology Stack

Runtime: Go 1.21+, SQLite, HTTP/WebSocket servers

Security: AES-256, PBKDF2, TLS 1.3, JWT tokens

Protocols: HTTP/2, WebSocket, SSH, MCP (Model Context Protocol)

Storage: SQLite database, Git-tracked configs

Deployment: Docker, Kubernetes, systemd, GitHub Actions

Next Steps