ASI‐OS Operator's Runbook: System Management, Logging, and Configuration

ASI-OS Operator's Runbook: System Management, Logging, and Configuration

Introduction: The Operator's Guide to ASI-OS

This document serves as an essential runbook for operators responsible for the daily management, monitoring, and maintenance of the ASI-OS. The ASI-OS is a self-evolving cognitive ecosystem engineered for autonomous operation on local infrastructure, ensuring data privacy and operational sovereignty.

From an operational perspective, the system is defined by its dual architecture: a live runtime kernel, known as the Sovereign-Loop, which executes tasks, and an offline cognitive ecosystem dedicated to skill synthesis and self-improvement. The primary interface for managing both aspects of this architecture is the manage.py Command Line Interface (CLI). This unified tool is the operator's gateway for all system interactions, providing a consistent and auditable mechanism for human-in-the-loop control over the system's powerful autonomous capabilities.

--------------------------------------------------------------------------------

1. Core System Operations via the Unified CLI

To ensure operational integrity and maintain a clear audit trail, all system interactions are centralized through the manage.py CLI. This unified interface is the single authoritative entry point for all critical system operations, guaranteeing consistency, control, and auditability across the ASI-OS environment. An operator's mastery of these four core commands is fundamental to successful administration.

server: Activating the Runtime Kernel

• Purpose: This command starts the live ASI-OS server, bringing the runtime kernel online.
• Syntax: python manage.py server --mode Sovereign-Loop
• Operational Context: An operator executes this command to initiate the system's active state. The --mode Sovereign-Loop argument specifically activates the live kernel, making the system ready to perform its designated functions. This is the standard command for deploying the system for active use.

learn: Initiating Cognitive Improvement Cycles

• Purpose: This command triggers an offline, autonomous learning session where the system's agents work to synthesize new skills and improve existing ones.
• Syntax: python manage.py learn --duration 180 --cycles 3
• Operational Context: This command is used during planned maintenance or development periods to evolve the system's cognitive capabilities without impacting the live environment. It initiates a controlled learning cycle between the Professor and Alpha agents.
  • The --duration argument specifies the length of the learning session in minutes.
  • The --cycles argument defines the number of distinct learning iterations to perform within that session.

test: Executing System Integrity Checks

• Purpose: Runs the comprehensive suite of system tests to verify functionality and integrity.
• Syntax: python manage.py test
• Operational Context: This is a critical command for routine health checks, post-configuration changes, or before deploying the system into a production state. It provides operators with confidence that all core components are functioning as expected.

clean: Removing System Artifacts

• Purpose: Cleans the environment of temporary files and build artifacts.
• Syntax: python manage.py clean
• Operational Context: An operator would use this command to ensure a clean system state, typically before running tests to prevent artifact contamination, or before archiving a deployment package to minimize its size.

Mastering these daily operations is the first step; the next is understanding how to monitor the outcomes of the system's autonomous actions.

--------------------------------------------------------------------------------

2. Audit Trails, Logging, and System Health

In a high-autonomy system like ASI-OS, robust logging and traceability are not merely features but fundamental requirements for governance and operational transparency. A complete and immutable record of all system-initiated actions is essential for debugging complex behaviors, performing security audits, and ensuring that the system's operations remain aligned with organizational directives.

Accessing Audit Trails All autonomous actions are logged in the data/ledger/ directory for full traceability. This ledger is the definitive source for any operational review or incident investigation, providing a complete and auditable history of system behavior.

Performing System Health Checks Execute a system-wide integrity check using the command python manage.py test. This is the primary method for verifying operational readiness. For detailed metrics and status reports, consult the "System Status" documentation in the docs/ directory.

Monitoring system health and auditing its actions are intrinsically linked to the proactive safety measures engineered into the system's core.

--------------------------------------------------------------------------------

3. Safety, Governance, and Recovery Protocols

Safety and governance are foundational pillars of the ASI-OS architecture, not secondary additions. The system is engineered from the ground up with transparency and control in mind, incorporating principles that align with emerging standards such as the EU AI Act. These features provide operators with the necessary tools to govern the system and intervene when required.

• Safety Governor The Safety Governor is the core component responsible for enforcing operational boundaries. Located at src/core/safety_governor.py, it applies a non-negotiable set of hardware and cognitive guardrails, ensuring that all autonomous actions remain within pre-defined safe parameters.
• Human Oversight The system is explicitly designed for human-in-the-loop control. The manage.py CLI is the designated mechanism for this oversight, acting as the primary recovery and intervention tool. All critical operations, from starting the kernel to initiating learning cycles, require explicit operator command, preventing unintended autonomous escalation.
• Local Operation By design, ASI-OS operates entirely on local infrastructure. This fundamental architectural choice provides a powerful, default layer of security. It ensures that sensitive organizational data and proprietary skills developed by the system are never exposed to external networks, securing them by default.

These built-in safety features create a trusted framework within which operators can confidently configure and extend the system.

--------------------------------------------------------------------------------

4. System Configuration and Extensibility

A core design feature of ASI-OS is its inherent extensibility, allowing operators and developers to tailor its behavior and expand its capabilities. This modular architecture ensures that the system can evolve to meet new challenges and integrate novel functionalities over time.

Core Configuration All system-wide parameters and settings are centralized for straightforward management in the configs/ directory. This is the first place an operator should look when needing to adjust system behavior, such as resource allocation, agent parameters, or integration settings.

Extending System Capabilities The system is designed to automatically recognize and integrate new modules placed in the appropriate directories. This streamlined process allows for rapid development and deployment of new functionalities.

Module Type | Implementation Details -- | -- Skills | Add new capabilities to the src/skills/ directory. The system loader will automatically discover and register them. Agents | Define new autonomous agent behaviors by adding corresponding modules to the src/agents/ directory. Scripts | Place new operational and maintenance tasks in the scripts/ directory for administrative use.

Understanding how to configure these software components is complemented by a clear knowledge of where they reside within the filesystem.

--------------------------------------------------------------------------------

5. Operator's Filesystem Reference

A clear understanding of the repository's directory structure is essential for effective troubleshooting, configuration, and maintenance. The layout is designed to be logical and modular, separating concerns to streamline an operator's workflow.

manage.py The unified Command Line Interface (CLI) and the single entry point for all system management tasks, including starting the server, running tests, and initiating learning cycles.

src/ Contains all core source code for the ASI-OS, including the kernel, agents, skills, and memory systems. This is the heart of the application.

scripts/ A dedicated location for operational and maintenance scripts used for various administrative tasks.

tests/ Houses the complete test suite. Operators interact with this directory's contents via the python manage.py test command.

docs/ The central repository for all system documentation, including architectural overviews, agent manifests, and status reports.

configs/ The location for all system configuration files. This is the primary directory for operators to adjust system-wide parameters.

data/ledger/ The directory where all audit trails are stored. It contains the complete, traceable log of all autonomous actions performed by the system.