Aurora AI-OS: The Complete Guide to Architecture, Safety, and Deployment

Aurora’s AI-OS is the architecture we use to build AI-driven business systems that behave like software people already know how to operate. This guide covers the three tiers of the system, how sub-agents and skills produce reliable output, the safety model that runs underneath, and the six environments the AI-OS can be deployed into without rewriting any code.

What is Aurora's AI-OS?

Aurora’s AI-OS is a three-tier operating system for building AI-powered business tools, combining an intelligent agent layer, a structured database backend, and a visual frontend dashboard. It is not a chatbot. It is a platform that runs repeatable, governed operations through AI, with the same reliability and visibility a team expects from professional SaaS software.

The generic concept of an AI-OS is covered in our introduction to AI operating systems. This guide focuses on Aurora’s specific implementation: what sits in each tier, how the safety model works, and where the system can be hosted.

Why does AI-OS bridge the gap between SaaS and AI agents?

AI-OS closes the visibility and governance gap between traditional SaaS, which people understand intuitively, and raw AI agents, which feel opaque and unreliable to operate at scale. SaaS tools have dashboards, audit logs, approval workflows, and clear states. People know what happened, when, and who approved it.

Agents are increasingly capable, but raw agents leave operators uncertain about what ran, what changed, and whether it is safe to leave running. According to McKinsey’s 2024 State of AI report, 65% of organisations now use generative AI in at least one business function, roughly double the share from the year before. According to Gartner’s 2024 forecast, by 2028 a third of enterprise software applications will include agentic capabilities, up from less than 1% in 2024.

The mental model most operators have, however, is still SaaS-shaped. AI-OS gives the agent layer all the structure of a production SaaS tool, including visible state, approval gates, tracked operations, and a real database. The agent keeps the intelligence and flexibility no static SaaS tool can match.

What are the three tiers of Aurora's AI-OS?

The Three Tiers of Aurora’s AI-OS are an agent layer for intelligence, a database backend for state, and a frontend dashboard for operator visibility, designed to work together as a single coordinated system. Each tier is independent enough to swap, but tightly enough integrated that operators experience one product, not three.

Tier 1: The agent layer

The intelligence layer is built around a hierarchy of specialised sub-agents. At the top sits a global identity that defines brand rules, operating principles, and strategic goals. Every session inherits this identity. Below that, sub-agents are isolated workspaces for distinct domains of work. Think of them as departments. Each has its own role, its own data permissions, and its own output rules. A marketing agent, an ops agent, and a client-facing agent can all run side by side, each self-contained, each governed independently. This is one practical instance of a multi-agent system inside a single business.

Tier 2: The database backend

Every action the AI takes writes to a structured database. Locally, the database is SQLite. For multi-user or hosted deployments it can run on Supabase or any Postgres-compatible service. The schema is version-controlled, migrations are additive-only, and every significant operation lands in an action_log table that serves as the system’s audit trail.

External actions, including emails, CRM writes, and API calls, are written to the log with a pending status. A human reviews and approves before anything executes. This is the human-in-the-loop gate, and it is not optional.

Context loading is handled through a summaries layer. Pre-generated markdown snapshots of database state are regenerated after every meaningful write. The AI agent reads these at session start for fast, deterministic context, not live SQL. That means consistent behaviour regardless of data volume, and summaries operators can inspect directly to see exactly what the AI loaded.

Tier 3: The frontend dashboard

A clean React dashboard connects to the database read-only and gives operators full visibility into everything the system is doing. Pipeline state, scheduled actions, pending approvals, content inventory, and campaign status are all surfaced as the kind of UI familiar from any SaaS product, with filter views, status badges, metric cards, and data tables.

Changes within an operator’s scope, such as updating a record status, approving a pending action, or adjusting a label, can be made directly from the interface. The kinds of things you would normally do in a CRM or project tool happen here, with the AI able to act on that state in the next session.

How do sub-agents and skills work inside the AI-OS?

Sub-agents define who is working, and skills define how the work runs. Together they make AI output repeatable: the same structured procedure runs every time, with the same quality criteria and the same logged result. Sub-agents are isolated workspaces with their own role, data scope, and output conventions. Skills are the structured playbooks each sub-agent uses to perform specific tasks.

Every skill in the AI-OS follows the same four-phase structure, which we call The Four-Phase Skill Structure:

1. Load. Read the context needed before starting. Skill files, knowledge files, database summaries, and any prior outputs are pulled into context first.
2. Validate. Check blocking conditions before any action. If a required input is missing, a duplicate exists, or an output would violate a rule, the skill exits before producing anything.
3. Execute. Produce the output, following embedded templates and quality standards. The execution phase is the only place where new content is created.
4. Log. Save the output to the right location, write the action to the database, and regenerate context summaries so the next session loads the updated state.

This is the reason the system is repeatable. The AI does not improvise how to write a proposal or send a campaign followup. It follows a defined procedure, every time, auditably. Each skill is a markdown file in the repository, readable and editable by anyone authorised to change it. Coordination across multiple skills and sub-agents is handled through agent orchestration, which keeps the routing logic out of any single skill.

How is safety built into the AI-OS architecture?

The safety model is built into the system’s architecture, not added as a layer of policy. Four primitives are mechanically enforced before any state-changing action can run, so safety is the default rather than a posture. Each primitive addresses a different category of risk that comes with running AI agents in production.

Blast radius scoping. Before running any state-changing command, the system categorises the action by its scope of effect: host machine, user account, project data, network exposure, shared production, or credentials. Dangerous actions in these scopes are hard-blocked at the hook level, not by policy, by code that exits before the command runs.

Profile enforcement. Two operational profiles govern what the AI can touch. Operators run skills, produce outputs, and manage domain content. Builders have architectural authority over the framework itself. The boundary is mechanically enforced. An operator session cannot edit schema migrations, system prompts, or security hooks, even if someone asks nicely.

Approval gates. No external action executes without a logged, human-approved record. The system can draft the email, prepare the CRM update, or stage the sequence, but it waits. According to Salesforce’s 2025 State of Sales report, sales reps spend an average of 32% of their time on manual data entry and research tasks. Approval gates capture human review where it matters most: at the moment of an outbound action, not as a buffer over every step.

Git-native audit trail. Every skill-driven change is an atomic commit. Skill outputs, knowledge writes, and reflection applications are all reversible with a single git revert. Operators never touch git directly. The automation handles sync, conflict triage, and push.

For deployments that include Claude Code as the underlying agent runtime, the additional controls in our Claude Code safety guide layer on top of these primitives.

Why is the AI-OS AI-agnostic and portable by design?

The AI-OS is built so that the model layer, the database layer, and the hosting environment are all interchangeable. No part of the system is locked to a specific vendor, and the same codebase runs across local machines, cloud containers, and full enterprise deployments. Portability was a constraint, not an afterthought.

The agent layer is built on Claude Code today, but the architecture is model-agnostic. Skills are markdown files: readable, editable, committable. The database is SQLite locally and Postgres-compatible for production, including Supabase as a managed option. The frontend is plain React with no proprietary UI framework.

The system can run natively on a developer’s machine or inside a container for full isolation, with filesystem sandboxing, network egress allowlists, and capability restrictions. The same .devcontainer/ definition runs on local Docker, GitHub Codespaces, or a cloud VM. The integration points to external systems use Model Context Protocol (MCP) where supported, which keeps the AI-to-tool interface standardised across providers.

Where can the AI-OS be hosted?

Aurora’s AI-OS supports six deployment targets that span from a single operator’s laptop to a regulated AWS Bedrock environment, sharing the same codebase, skills, database conventions, and safety model across every option. We call this The Six Deployment Targets of AI-OS. The right target depends on team size, security posture, and existing infrastructure.

Employee laptop (local, native)

The simplest deployment runs Claude Code directly on a single operator’s machine. The database is a local SQLite file. The frontend runs on localhost. No network is required beyond the API call. The full safety model, including hooks, profile enforcement, and approval gates, is still active. Nothing leaves the machine except the model API call. This is the right starting point for solo operators, freelancers, and sensitive engagements where data cannot leave the premises.

Mac Mini server (on-premise shared)

A Mac Mini in an office or rack is a capable AI-OS host. Claude Code runs as a persistent process. Operators connect remotely via Tailscale, SSH, or a simple web UI and run sessions against the shared instance. The database lives on the SSD. The frontend is served on the LAN. With Tailscale the Mini is reachable securely from anywhere without opening ports. Best for small teams that want shared infrastructure without cloud costs or cloud data residency concerns.

Distributed via git

Each employee runs their own Claude Code session on their own machine, but all sessions share a database and a knowledge base kept in sync via git. Session start pulls the latest. Session end commits and pushes. Conflicts are triaged automatically by type. Content conflicts get a plain-English prompt. Structural conflicts escalate to the builder. Employees never run git commands directly. The automation handles sync. For write-heavy concurrent workflows the database layer can be upgraded to Supabase, adding row-level security and multi-machine write concurrency. Best for teams of three to fifteen.

AWS EC2 with Bedrock

For organisations already in the AWS ecosystem, the AI-OS runs cleanly on EC2 inside a container. The same .devcontainer/ definition works on any Linux host. The container provides filesystem isolation, an egress allowlist, a non-root capability-dropped process with CPU and memory limits, and ephemerality on rebuild.

Amazon Bedrock opens the door to running Claude models through AWS infrastructure directly. When the AI call routes through Bedrock, it stays within the customer’s AWS VPC, with no traffic to Anthropic’s public endpoints. For regulated industries like healthcare, finance, and government, this is often a requirement, not a preference. According to Stack Overflow’s 2025 Developer Survey, 76% of developers are actively using or planning to use AI coding assistants, and enterprise rollouts of those tools increasingly route through cloud-native model providers like Bedrock for the same VPC-containment reasons.

GitHub Codespaces

The same .devcontainer/ definition that runs on Docker locally runs on GitHub Codespaces without modification. A full AI-OS environment, containerised and isolated, comes up in under two minutes from any browser. This is useful for builders doing architectural work who want a clean, ephemeral environment, or for onboarding new operators who do not want to install anything locally.

Hybrid: local operators, hosted database

A common production pattern places operators on local Claude Code, with the database hosted on Supabase. The local SQLite file and the Supabase Postgres instance share the same schema. Going multi-user is one connection-string change in db.js. The frontend’s read-only API keeps working. The only migration is the data itself. Supabase adds user authentication, per-row access policies, and scoped views for individual operators.

The model layer is similarly interchangeable across all six targets. The system ships with Claude (via Anthropic’s API or AWS Bedrock), but the skills, database conventions, and safety hooks are model-agnostic. Switching to a newer or cheaper model is an infrastructure decision, not a codebase rewrite.

How does the AI-OS learn and improve over time?

The AI-OS improves through an operator-driven feedback loop. When an operator notices a skill output that missed the mark, the system reads the skill, its outputs, and the feedback, then proposes specific edits with rationale and confidence. Approved changes are committed atomically. The loop is transparent and reversible.

This matters because the alternative is silent drift. A static AI system gradually produces outputs that fit the use case worse over time as conditions change. An AI-OS with an explicit improvement loop captures the operator’s experience as durable workflow automation rules, not tribal knowledge. Every approved improvement becomes a permanent baseline that future sessions inherit.

The improvement loop runs only with explicit operator approval. The system does not modify its own skills autonomously. Proposed edits wait for review, are committed atomically when approved, and remain reversible through standard git history. The result is a system that gets more accurate the longer a team uses it, without ever silently changing how it operates.

In short: Aurora’s AI-OS gives growing businesses the reliability and visibility of enterprise SaaS, the intelligence and flexibility of modern AI agents, and the governance model to run both in production, without trading one for the other.

Frequently asked questions