ANT-OS Documentation

Complete reference for the biological operating system. v0.4.0

Installation

One-line install

$ curl -sSf https://ant-os.dev/install.sh | sh

The installer detects your system and picks the best method:

• Debian/Ubuntu — Downloads and installs the .deb package via dpkg
• Cargo (any Linux) — Clones the repo and builds from source

Requirements

• OS: Linux x86_64 (required)
• Install: apt/dpkg OR Rust toolchain (cargo)
• Optional: GPU support requires wgpu-compatible hardware (Vulkan/Metal/DX12)

Manual install

From .deb package

# Download latest release
$ wget https://github.com/anthonygaston/autonomous-native-trainee/releases/download/v0.4.0/ant-os_0.4.0_amd64.deb
$ sudo dpkg -i ant-os_0.4.0_amd64.deb

From source

$ git clone https://github.com/anthonygaston/autonomous-native-trainee.git
$ cd autonomous-native-trainee
$ cargo build --release
$ cp target/release/ant-os target/release/ant-shell ~/.cargo/bin/

Quick Start

1. Start the colony

# Fresh colony, 3 starter ants, API on port 7700
$ ant-os --fresh --port 7700 --ants 3

2. Connect with the shell

$ ant-shell
Connected to ANT-OS colony at 127.0.0.1:7700

ant> :status
Colony: 3 ants | Tick: 0 | Energy avg: 50.0%

ant> :roles
Extraction: 1 | Synthesis: 1 | Conversion: 1

3. Feed it data

# Ingest a local file
ant> :explorer read /path/to/document.txt

# Fetch a web page
ant> :cybernaut fetch https://example.com/article

# Train the language model
ant> :lm train 200

# Generate text
ant> :lm gen "The colony has learned"

4. Let it grow

# Enable automatic growth (on by default)
ant> :growth on

# ANTs will promote through roles based on quality
# Extraction → Synthesis → Convert → Constructor → Specialist roles

Configuration

Command-line flags

Config files

api.json example

{
  "provider": "claude",
  "model": "claude-sonnet-4-6",
  "api_key": "sk-ant-..."
}

What Is ANT-OS

ANT-OS is biological computation running as a Linux daemon. It is not a chatbot, not a simulation, and not a wrapper around an LLM. It is a self-organizing colony of autonomous neural agents — called ANTs (Autonomous Native Trainees) — that process data through a pipeline, earn energy from quality work, get promoted based on performance, and die when they run out of energy.

The colony learns by feeding — ingesting text, files, and URLs that flow through the neural pipeline and train the colony's internal language model. Over time, ANTs specialize into 13 distinct roles, from low-level data processing to executive decision-making, filesystem manipulation, network access, and system operation.

ANT-OS was designed as a Personal Cognitive OS (PC-OS): a local autonomous intelligence layer that runs beneath your daily computing life, continuously perceiving, learning, and acting in the background.

The Colony

The colony is the central simulation loop. Every tick, the following phases execute:

1. Job dispatch — Tasks are queued and assigned to idle ANTs based on role
2. Tick all ANTs — Each ANT processes its current task through its neural brain
3. Quality scoring — The Supervisor evaluates task output via cosine similarity
4. Energy update — Quality work earns energy; failure and idleness drain it
5. Promotions — ANTs with sustained high quality EMA advance to specialist roles
6. Lifecycle — Zero-energy ANTs die; Constructors can reproduce
7. Automation — Rules evaluate, watchers drain, tasks execute
8. Social signal — Colony-wide trust/valence updates propagate through the Thalamus

The 13 Roles

ANTs are promoted through a hierarchy based on sustained quality scores. Every ANT starts in the Pipeline tier and advances through demonstrated performance.

Energy & Lifecycle

Every ANT has an energy level that determines its survival. Energy is the colony's currency of quality.

• Earning energy: Quality task completions add energy. Higher quality = more energy.
• Losing energy: Failed tasks, idle ticks, and metabolic burn drain energy. Stress increases burn rate.
• Death: When energy reaches zero, the ANT dies. Its knowledge transfers to the Soul Plane.
• Reproduction: Constructors can split their brain to spawn offspring, passing learned weights.
• Quality EMA: Exponential moving average of recent task scores. Drives promotion decisions.

The Pipeline

All data flows through a three-stage neural pipeline:

Extraction ANTs encode raw data into 832-dimensional Species Code representations. Synthesis ANTs reconstruct patterns from these representations. Conversion ANTs transform between formats. The quality of each stage is scored by the Supervisor, feeding back into energy and promotions.

This pipeline runs every tick — the colony is always processing, always learning.

Species Code (832D)

Species Code (SC) is the universal internal representation used by every ANT. It's an 832-dimensional vector composed of:

• 64 dense dimensions — Core pattern vector
• 16 semantic slots × 48 dimensions each — Structured information slots for language, emotion, context, goals, social signals, and deliberation

The SCEncoder maps raw 8D sensor inputs into 832D SC via dense and slot weight matrices. The SCDecoder maps SC back to 8D action outputs. Between them, the Gate System applies multiplicative neuromodulation across 4 tiers:

Brain Regions

Each ANT's brain contains 6 simulated cortical regions that process information in a coordinated loop:

The processing loop each tick: Sensory Cortex → Thalamus → Hippocampus + Amygdala → dlPFC → Basal Ganglia → SC Encoder → Action

Kernel (59 Primitives)

The kernel is ANT-OS's interface to the host operating system. The SystemOperator role executes primitives through a 3-layer architecture:

• Layer 0 — Ops (kernel_ops.rs): 59 primitive definitions with safety classification
• Layer 1 — Command (kernel_cmd.rs): SC output activation → primitive + target resolution
• Layer 2 — Execution (kernel_exec.rs): Sandboxed execution with capability-based isolation

Safety levels

Every primitive is classified for Defender review:

Memory System

ANT-OS implements a 3-tier semantic memory system inspired by biological memory consolidation:

Additional memory features:

• Notes — Explicit note storage with importance weighting
• Pinned facts — Core identity and preferences, always available
• Conversation threading — Semantic grouping of multi-turn interactions
• Episodic memory — Per-ANT hippocampal episodes with salience-weighted retrieval

NeuralLM

A 2-layer Transformer (625K parameters) that trains on the colony's corpus. This is not a large language model — it's a small, local, continuously-learning model that captures domain-specific patterns from the colony's experience.

Training sources

• Self-corpus — .sc files describing the colony's own architecture
• Ingested files — Local files read by Explorer
• Fetched pages — Web content fetched by Cybernaut
• Direct text — User-provided training text
• Personality profiles — Writing style overlays for output shaping

Commands

ant> :lm status              # Model stats, corpus size, vocab
ant> :lm train 200           # Train 200 epochs on current corpus
ant> :lm train "Custom text"  # Add text to corpus and train
ant> :lm gen "The colony"     # Generate text from prompt
ant> :lm feed /path 10       # Ingest file + train 10 epochs
ant> :lm save                 # Persist weights to disk
ant> :lm load model.antlm    # Load saved weights

Automation Engine

Event-driven rules that fire autonomously every tick — no user input required. Rules consist of a condition (when to fire) and an action (what to do).

Condition types

Available metrics

num_alive, num_idle, energy_avg, total_deaths, total_tasks_completed, tick_count, sys_cpu_load, sys_memory_available

Action types

Examples

# Alert when energy drops low
ant> :auto create low-energy metric:energy_avg:below:20 webhook:http://localhost:3100/hook:low_energy 100

# Log a heartbeat every 1000 ticks
ant> :auto create heartbeat tick:1000 journal:alive 0

# Trigger a task when CPU spikes
ant> :auto create cpu-alert metric:sys_cpu_load:above:90 task:cpu-report 500

# List all rules
ant> :auto list

# Disable a rule
ant> :auto disable 1

Filesystem Watcher

The Explorer is both a periodic crawler (every 500 ticks) and a real-time filesystem sensor. Using Linux inotify (via the notify crate), the colony watches directories and reacts to file changes as they happen.

How it works

1. You add watch paths via :watch add /path
2. inotify monitors the directory recursively for create/modify/delete events
3. Events are drained every tick (Phase 4.66, max 256 events/tick)
4. Changed file paths are pushed into explorer_hints
5. Explorer ANTs pick up changed files for re-ingestion

The periodic crawl is preserved — the watcher supplements it. Crawling catches anything the watcher might miss; watching catches changes instantly.

ant> :watch add /home/user/projects    # Watch recursively
ant> :watch add /var/log                # Watch log directory
ant> :watch list                        # List active watches
ant> :watch remove /var/log             # Stop watching

Shell Execution

ShellExec (Primitive #59) runs arbitrary shell commands on the host system and captures stdout/stderr. Safety level: Destructive — every execution passes through Defender review.

ant> :exec uname -a                    # System info
ant> :! df -h                           # Disk usage (alias)
ant> :exec cargo build --release 2>&1   # Build project
ant> :! systemctl status nginx          # Check service

Soul Plane

When an ANT dies, its knowledge doesn't disappear — it enters the Soul Plane. This is the colony's epigenetic memory: the accumulated wisdom of dead ANTs that influences future generations.

• Dead ANTs' brain weights are stored as "hero weights" in the Soul Plane
• New ANTs can inherit blended weights from multiple dead ancestors
• Personality profiles blend hero weights via convex combinations
• The Soul Plane ensures the colony's knowledge persists even through mass die-offs

ant> :soul                 # View Soul Plane status
ant> :personality scientific  # Apply personality overlay
ant> :personality blend scientific:0.7 creative:0.3  # Blend styles

Defender & Security

The Defender is the colony's immune system. Every kernel command proposal passes through Defender review before execution.

• Observe operations — auto-approved (read-only queries)
• Reversible operations — logged but allowed (file creation, allocation)
• Destructive operations — Defender must explicitly approve (file delete, process kill, shell exec)
• Forbidden operations — always blocked (shutdown without override)

The Defender also monitors for:

• Divergence — ANTs whose behavior deviates from colony norms (EMA tracking)
• Threat branding — Suspicious patterns are flagged for investigation
• Consensus — High-safety operations require Elder Council agreement via the Kernel Ledger

ant> :defender          # Defender status + recent decisions
ant> :ledger            # Full command audit trail

Shell Commands

Status & Inspection

Colony Control

Data Acquisition

Language Model

Knowledge & Memory

Shell Execution

Filesystem Watcher

Task Automation

Tracker

Automation Rules

API Reference (92 endpoints)

ANT-OS exposes a REST API via Axum. By default on http://127.0.0.1:3001 (configurable with --port). All responses are JSON.

Status & Context

Colony Control

Data Acquisition

Language Model

Knowledge

Kernel

Filesystem Watcher

Automation

Source Modules

ANT-OS is organized into ~120 source files across 8 module groups.

Neural foundation (src/)

Brain regions (src/regions/)

Species Code (src/sc/)

Body & interoception (src/body/)

Colony & agents (src/ant/)

Binaries (src/bin/)

Bot Integration

ANT-OS includes Telegram and Discord bot bridges that connect external LLMs (Claude, Mistral, Codex, Kimi) to the colony. The bots inject the colony's agent_reference.md as system context, giving the LLM full awareness of colony state and commands.

How it works

1. User sends a message to the Telegram/Discord bot
2. Bot fetches colony context via GET /context/summary
3. Bot sends user message + colony context + agent reference to the LLM
4. LLM responds, optionally including [api_call] blocks
5. Bot parses API call blocks and executes them against the colony
6. Results are sent back to the user

This gives external LLMs full control over the colony — spawning ANTs, creating automation rules, running shell commands, querying memory — all through natural language.

Configuration

// ~/.config/ant-os/bots.json
{
  "telegram_token": "...",
  "discord_token": "...",
  "colony_url": "http://127.0.0.1:7700",
  "allowed_channels": ["..."]
}

LLM Orchestration

An external LLM connected to ANT-OS isn't just a reference tool — it's the deep reasoning layer of the architecture. The colony provides continuous perception and memory; the LLM provides judgment and strategy.

What the LLM can do

• Strategic orchestration — Decide what the colony focuses on. Spawn roles, prioritize tasks, shape the pipeline.
• Domain adaptation — Configure the colony for the user's needs: developer, writer, researcher, sysadmin.
• Multi-step reasoning — Chain commands: :explorer read → :librarian query → :lm train → :lm gen
• Automation design — Create rules that fire on intervals, thresholds, or events, with webhook/API/task actions.
• System operations — Run commands via :exec, monitor via kernel primitives, react to filesystem events.
• Natural language bridge — Generate complex output that the colony's small NeuralLM cannot.

Programmatic access

# From any script or tool, hit the API:
$ curl -s http://127.0.0.1:7700/stats | jq .
$ curl -X POST http://127.0.0.1:7700/shell/exec -d '{"command":"uname -a"}'
$ curl -X POST http://127.0.0.1:7700/automations/create \
    -H 'Content-Type: application/json' \
    -d '{"name":"cpu-watch","condition":{"type":"MetricThreshold","metric":"sys_cpu_load","op":"Above","value":90},"action":{"type":"JournalLog","message":"CPU high"},"cooldown_ticks":500}'

GPU Acceleration

ANT-OS supports optional GPU acceleration via wgpu (Vulkan/Metal/DX12). Enable with the gpu feature flag:

$ cargo build --release --features gpu

• Hard cap: 160 concurrent ANTs on GPU
• Brain weight matrices batched into VRAM buffers
• Compute shaders (WGSL) for encoder/decoder forward passes
• GPU-accelerated LM training loop