How to Run

Prerequisites

• Node.js 20+ (node --version)
• npm (npm --version)
• An ANTHROPIC_API_KEY in .env

Setup

cd orbita-core
npm install               # First time only
cp .env.example .env      # Then edit .env and add your API key

Commands

# ──────────────────────────────────
# Run the organism
# ──────────────────────────────────
npm start
# → Embedded MongoDB auto-starts
# → Axiom agent loads
# → Heartbeat starts: ♥ beat 1, ♥ beat 2, ...
# → Ctrl+C to stop gracefully

# ──────────────────────────────────
# Run tests (proof of life)
# ──────────────────────────────────
npm test
# → Runs all 37 tests (isolated test DB)
# → Must see: "Tests  37 passed"

npm run test:watch
# → Re-runs tests on file changes

# ──────────────────────────────────
# Read the docs (this site)
# ──────────────────────────────────
npm run docs
# → Opens at http://localhost:5173

Web Interfaces (while running)

http://localhost:3210/talk    — Chat UI (ChatGPT-style, thread continuity)
http://localhost:3210/inbox   — All agent inboxes (pending + history)
http://localhost:3210/xray    — X-Ray dashboard (traces + tasks)
http://localhost:3210/trace   — Trace mesh visualization
http://localhost:3210/pulse   — Organism vital signs
http://localhost:3210/health  — Health check

Talk UI Features

• Thread continuity — conversation context preserved in localStorage
• "+ New chat" button to start fresh
• Debug panel collapsed by default, expand to see trace, tokens, skills, X-Ray events
• Markdown rendering in assistant replies
• Shift+Enter for newline, Enter to send

API

# Send a message (API)
curl -X POST http://localhost:3210/message \
  -H "Content-Type: application/json" \
  -d '{"from":"anyone","text":"anything"}'

Project Structure

orbita-core/
├── dna.md              # Universal genetic code
├── agents/             # Agent definitions (only Axiom at startup)
│   └── axiom/
├── skills/             # Shared skills (markdown — when/how to use tools)
├── src/                # Source code (body organs)
│   ├── pulse/          # Heart
│   ├── cortex/         # Brain
│   ├── sense/          # Senses
│   ├── muscle/         # Muscles (tasks)
│   ├── nerve/          # Nervous system (inbox)
│   ├── bone/           # Skeleton (org structure)
│   ├── circadian/      # Clock (scheduler)
│   ├── memoria/        # Memory (state)
│   ├── db/             # Database connection
│   ├── xray/           # Observability
│   └── tools/          # Tool implementations (code)
├── test/               # 37 tests
└── doc/                # This documentation

Environment Variables

# Required
ANTHROPIC_API_KEY=sk-ant-...

# Optional (defaults to embedded MongoDB if not set)
MONGODB_URL=mongodb://localhost:27017
MONGODB_DB=orbita

The Rule

At every stage, npm test must pass. If tests fail, the organism is sick. Fix before growing.