Build, deploy, and orchestrate neural-grade services.

Introduction

AxonStellar is a neural-inspired orchestration platform. Services are neurons, traffic flows along axons, and autonomous agents reason at every synapse. The platform pairs a static infrastructure layer (nginx proxies, port allocation, SSL automation) with a dynamic agent layer (the Aexyr agent, Engram playbooks, Action Potential decision model).

This documentation covers everything in the constellation:

• Quickstart — your first service in under five minutes
• Architecture — proxies, tiers, traffic flow, port layout
• Agent protocols — Action Potential, Synaptic Delegation, Engrams
• API reference — every endpoint the platform exposes
• Troubleshooting — common pitfalls and recovery paths

Quickstart

Ship a new HTTPS-served service into the constellation in six steps. Each step takes seconds — most of the wall-clock time is waiting for the SSL certificate to propagate.

A minimal manifest

Every service must publish a service.json manifest. No manifest, no discovery, no orchestration. The bare minimum:

{
  "name": "My Service",
  "port": 9560,
  "role": "app",
  "tier": 1,
  "managed_by": "aexyr",
  "traffic_type": "nginx_proxy",
  "start_command": "node server.js",
  "working_directory": "/aexyr/usr/projects/myservice"
}

Launching the service

Two ways to start a service:

1. Service Control API (preferred for services with a manifest):

import urllib.request, json
TOKEN = open('/aexyr/tmp/.internal_api_key').read().strip()
H = {'Content-Type': 'application/json', 'X-Internal-Auth': TOKEN}
body = json.dumps({'action': 'restart', 'port': 9560}).encode()
urllib.request.urlopen(urllib.request.Request(
    'http://127.0.0.1:80/visualizer_service_control',
    data=body, headers=H, method='POST'))

2. Direct nohup (first-time deployment, before discovery):

cd /aexyr/usr/projects/myservice
nohup node server.js >> logs/app.log 2>&1 &

Core Concepts

Six ideas you must understand to operate in the constellation effectively.

Architecture

AxonStellar runs inside a single Docker container with a layered network model. Each layer has one job and exposes a clear contract upward.

Traffic flow

Internet :443
   └──▶ nginx (Web Proxy, SSL termination)
          └──▶ Backend Proxy :3550
                 └──▶ Service :95xx (Tier 1)
                        └──▶ Microservice :35xx (Tier 2)

Reserved system ports

Five ports are owned by the platform and must never be reassigned:

Security model

Three distinct user identities collaborate via a privilege broker:

• root (UID 0) — runs Flask/uvicorn backend, owns system configs
• aexyr-user (UID 1100) — runs all agent code (terminal, python, nodejs)
• web_serve (UID 1101) — privilege broker; owns shared credential files

Services & Manifests

Services are discovered automatically by scanning /aexyr/usr/projects/*/service.json. The manifest is the source of truth for everything the platform needs to know about your service.

Manifest fields

Discovery sync

After creating, updating, or deleting a manifest, sync the registry:

# POST /manifests_sync — re-scans projects/ and updates the registry
curl -X POST http://127.0.0.1:80/manifests_sync \
     -H "X-Internal-Auth: $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{}'

Networking & SSL

SSL is fully automated via Cloudflare DNS-01 challenges and Let's Encrypt. Two API calls take you from no certificate to a live HTTPS endpoint, typically in 60–90 seconds.

The two-phase workflow

1. Provision the certificate — DNS challenge runs in the background
2. Assign the cert to a service — nginx configured + restarted automatically

# Phase 1 — Provision (fire-and-forget)
body = json.dumps({'domain': 'myapp.example.com'}).encode()
urllib.request.urlopen(urllib.request.Request(
    'http://127.0.0.1:80/api_certificates?action=provision',
    data=body, headers=H, method='POST'))

# Phase 2 — Assign (after status == 'active')
body = json.dumps({'domain': 'myapp.example.com', 'servicePort': 9560}).encode()
urllib.request.urlopen(urllib.request.Request(
    'http://127.0.0.1:80/api_assignments',
    data=body, headers=H, method='POST'))

Agent Protocols

Aexyr operates under three interlocking protocols. Every autonomous action passes through them in sequence.

Action Potential

Before executing any tool call, Aexyr computes an activation:

z = (x₁ × 0.5) + (x₂ × 0.8) + (x₃ × 0.4) + b
Output = max(0, z)

• x₁ — Confidence (0.0–1.0): certainty the action achieves the goal
• x₂ — Safety (0.0–1.0): how safe (1.0=read, 0.0=destructive)
• x₃ — Necessity (0.0–1.0): how strictly necessary
• b — bias: −0.9 standard, −0.7 development mode

If Output > 0 the axon fires and the action executes. If Output == 0 the action is gated and Aexyr asks for confirmation.

Read-Before-Edit

Every file modification follows a strict five-step cycle. No exceptions.

1. READ — open the file fresh; never edit from memory
2. LOCATE — find the exact target with surrounding context
3. ASSERT — verify the target string exists before replacing
4. EDIT — surgical, targeted modification only
5. VERIFY — read back and confirm the change landed

Documentation-Before-Response

After any change inside a project, the agent updates service_changelog.md and (when affected) service_blueprint.md before responding to the user. A change without a changelog entry is considered drift.

Engrams

Engrams are stored agent playbooks — sixteen battle-tested recipes spanning four categories. Each Engram is a complete spike train: ordered steps, expected outputs, and rollback conditions.

Quanta & Delegation

When a task exceeds a single context window or requires specialized expertise, Aexyr dispatches a Quanta — a subordinate agent with a specific profile.

API Reference

All platform APIs are served from http://127.0.0.1:80 (uvicorn) and authenticated with the internal token:

export TOKEN=$(cat /aexyr/tmp/.internal_api_key)
curl -H "X-Internal-Auth: $TOKEN" http://127.0.0.1:80/manifests_list

Manifests

Service control

SSL & assignments

Engrams & agent

Operations

Troubleshooting

The top fifteen pitfalls baked into the agent's knowledge base, ordered by frequency.

Changelog

Documentation site versions:

• v0.0.1 — 2026-05-25 — Initial documentation site. Nine sections covering quickstart, architecture, services, networking, agent protocols, Engrams, delegation, API reference, troubleshooting.