All code has been created following TDD/BDD methodology with comprehensive test coverage. NO TESTS OR CLI COMMANDS HAVE BEEN EXECUTED - Awaiting owner approval.

Overview

NebulaOS is a production-grade platform for running AI agents with:

Security-First Design: Zero-trust architecture with policy enforcement
Observability Built-In: Comprehensive logging, metrics, and tracing
Plugin Ecosystem: Extensible through verified plugins
Event-Driven: Reactive automation with event triggers
Scalable: Horizontal scaling with distributed runtime

Quick Start

curl -fsSL https://gitea.armco.dev/Restruct-Corporate-Advantage/nebula-os/raw/branch/main/install.sh | bash

Installs everything — Python deps, PostgreSQL schema, webapp — and prints start commands. Works on macOS and Linux.

Then:

# Start the API (port 2000)
cd ~/.nebula && source .venv/bin/activate && uvicorn src.api.main:app --host 0.0.0.0 --port 2000

# Start the webapp (port 2001, separate terminal)
cd ~/.nebula/webapp && npm run dev

Optional: Add VIRUSTOTAL_API_KEY=your_key to .env.local to enable automatic security scanning of plugins on install.

Prerequisites

Python 3.11+
PostgreSQL 15+
Node.js 18+ (for webapp)

Architecture

┌─────────────────────────────────────────────┐
│              User / Client                  │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│           API Layer (REST/gRPC)             │
│  - Agent management                         │
│  - Task submission                          │
│  - Workflow orchestration                   │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│         Runtime Core (Scheduler)            │
│  - Agent lifecycle                          │
│  - Task queue                               │
│  - Policy enforcement                       │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│      Tool Executor (Sandboxed)              │
│  - Plugin execution                         │
│  - Resource limits                          │
│  - Audit logging                            │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│         Database (PostgreSQL)               │
│  - State persistence                        │
│  - Audit logs                               │
│  - Metrics storage                          │
└─────────────────────────────────────────────┘

Features

Phase 1 (MVP) - Complete

✅ Secure agent runtime with policy enforcement
✅ Plugin system with verification
✅ Comprehensive logging and audit trail
✅ Database schema with migrations
✅ Task queue with priority scheduling
⏳ REST API (in progress)
⏳ CLI tools (in progress)

Phase 2 (Advanced) - Planned

⏳ Multi-step workflow orchestration
⏳ Vector memory integration (Chroma)
⏳ Event triggers and webhooks
⏳ Plugin marketplace

Phase 3 (Enterprise) - Planned

⏳ Distributed runtime cluster
⏳ Secrets vault integration
⏳ Compliance reporting
⏳ Policy simulation

Documentation

Comprehensive documentation available in docs/:

Guides

Getting Started — one-liner install, first agent, plugin setup
Usage Guide — full API reference, CLI, policy authoring, plugin development

Architecture & Security

Specs

Agent Marketplace — marketplace design, community submission
Real-Time Execution Stream — live agent trace UI
Memory Architecture
Benchmarking Framework
Agent Capability Taxonomy
Problem Space Definition

Project Structure

/nebula-os
  /libs                 # Shared libraries
    /logging           # ✅ Logging utility
    /db                # ✅ Database connection
    /policy            # ⏳ Policy engine
    /common            # ⏳ Common utilities
  
  /services            # Long-running services
    /runtime           # ⏳ Core runtime
    /executor          # ⏳ Tool executor
    /api               # ⏳ REST/gRPC API
  
  /plugins             # Plugin ecosystem
    /sdk               # ⏳ Plugin SDK
    /samples           # ⏳ Sample plugins
  
  /cli                 # ⏳ CLI tools
  /tests               # Test suites
  /db                  # ✅ Migrations
  /docs                # ✅ Documentation

Development

Running Tests

# Unit tests
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# BDD specs
behave tests/specs/

# Coverage report
pytest --cov=libs --cov=services --cov-report=html

Code Quality

# Format code
black libs/ services/ tests/

# Lint
flake8 libs/ services/ tests/

# Type check
mypy libs/ services/

# Sort imports
isort libs/ services/ tests/

Database Migrations

# Run migrations
python -m libs.db.migrations migrate

# Rollback migration
python -m libs.db.migrations rollback

# Create new migration
python -m libs.db.migrations create "migration_name"

Security

NebulaOS follows security-first principles:

Zero Trust: All agents untrusted by default
Policy Enforcement: Every action validated
Audit Logging: Complete audit trail
Secrets Vault: Encrypted credential storage
Sandbox Isolation: Containerized execution

See Security Architecture for details.

Contributing

We welcome contributions! Please see our Governance document.

Development Workflow

Fork the repository
Create feature branch
Write tests first (TDD)
Implement feature
Run all tests
Submit pull request

License

Apache 2.0 - See LICENSE file

Support

Documentation: docs/
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@nebulaos.io

Acknowledgments

Built following the NebulaOS Copilot Plan with:

Test-First Development (TDD/BDD)
Security-First Design
Observability Built-In
Production-Ready Code

⚠️ IMPORTANT: NO TESTS OR COMMANDS EXECUTED

All code has been created but NOT executed per owner requirements. Owner approval required before running any tests or CLI commands.

See FINAL_IMPLEMENTATION_SUMMARY.md for complete status.

Languages

Python 95.8%

Cython 1.6%

TypeScript 1.1%

C 0.7%

CSS 0.5%