XOS Monorepo

This repository contains the Xybernetex decision and execution stack:

• decision_engine/ — structured decision analysis
• xybernetex/ — API, portal, worker, orchestrator, and tool execution
• xos/ — the control plane joining decisioning to guarded execution

Supported development environment

Linux is the only supported development environment. Use Python 3.11 or newer and Node.js 18 or newer.

Bootstrap

make bootstrap

This creates .venv, installs the credential-free XOS test dependencies, and installs the portal dependencies from its lock file. It does not install the large model and connector dependency sets used by the live services.

Copy configuration templates only when you are ready to run live services:

cp config/shared.env.example config/shared.env
cp config/xos.env.example config/xos.env

Never commit real environment files or credentials.

Verify

Run the same baseline checks used by CI:

make check

The baseline is deliberately offline and does not require Redis, PostgreSQL, provider credentials, or connector credentials. It runs the XOS unit/API tests, compiles the Python source trees, and builds the React portal.

Run XOS safely

XOS defaults to mock decisioning and preview-only execution:

make run-xos

Then open http://127.0.0.1:8010/. See xos/README.md for the live integration settings.

In the complete stack, XOS stores cycle snapshots in PostgreSQL. Decisions, approvals, execution references, outcomes, and recent-memory context survive service and machine restarts.

Run the complete stack on WSL

WSL2 with Docker Desktop integration (or Docker Engine plus Docker Compose) is the supported full-stack development environment. Install all service environments once:

make bootstrap-stack

The first full bootstrap also generates synthetic expert demonstrations and trains worker-prod/models/policy_v3.pt when no policy artifact is present. To rebuild the policy explicitly:

make train-worker

Start PostgreSQL, Redis, and all application services:

make stack-up

Inspect or stop them with:

make stack-status
make stack-down

Runtime logs and PID files are written to runtime/dev-stack/. PostgreSQL and Redis data use named Docker volumes and survive stack-down. To deliberately erase local infrastructure data, run docker compose -f compose.dev.yml down -v.

The Decision Engine is reachable before an LLM provider is configured, but XOS reports it as needs configuration. Open the Decision Engine, select the gear icon, choose a provider/model, enter its API key, and use Test then Save. The key is stored in the ignored local Decision Engine settings database.

The stack exports local database/Redis defaults and keeps XOS_AUTO_EXECUTE=false. Values already exported in your shell take precedence. Provider and connector credentials remain opt-in through the ignored files under config/.

If PostgreSQL or Redis is already using its default host port, override it for the complete command lifecycle. The application connection URLs follow these values automatically:

POSTGRES_PORT=55432 REDIS_PORT=56379 make stack-up
POSTGRES_PORT=55432 REDIS_PORT=56379 make stack-status
POSTGRES_PORT=55432 REDIS_PORT=56379 make stack-down

Stabilization tiers

1. make check — deterministic, credential-free checks required for every change.
2. Service integration — Redis/PostgreSQL and local HTTP boundaries.
3. Live smoke tests — opt-in provider and connector checks with explicit credentials.

Live smoke tests must never be part of the default test command.