Skip to main content

Introduction

Core Concepts

Key concepts behind DxCore: task graphs, the frontier, sharding, agents, and the coordinator.

Task Graph (DAG)

At the center of DxCore is a directed acyclic graph of tasks. Each node is a task (e.g., build, test, lint for a specific package) and edges represent dependencies. Your build system produces this graph — DxCore consumes it.

Coordinator

The coordinator is the central server. It receives the task graph from the dispatcher, maintains scheduling state, and assigns work to agents over WebSocket channels. It exposes a REST API for session management and a WebSocket interface for real-time coordination.

Dispatcher

The dispatcher is a CLI command (dxcore dispatch) that reads a task graph from stdin and submits it to the coordinator. It streams execution progress and exits with the overall result.

Agents

Agents are CLI processes (dxcore agent) that connect to the coordinator and execute assigned tasks. Each agent announces its capabilities — CPU, memory, and custom tags — so the scheduler can make informed placement decisions.

Frontier

The frontier is the set of tasks whose dependencies have all completed successfully. The scheduler continuously recomputes the frontier as tasks finish and assigns frontier tasks to available agents.

Sharding

Long-running tasks can be split into N parallel shards. The coordinator’s expand_graph step splits tasks based on:

  1. Explicit config — dxcore.json shard counts (highest priority)
  2. Learned profiles — recommended_shards from historical TaskProfile data
  3. Default — 1 shard (no splitting)

See Shard Configuration for details on dxcore.json.

Sessions

A session groups a single CI run. The dispatcher and all agents join the same session. Sessions are created via the REST API (POST /api/sessions) and finished when the run completes.

Smart Scheduler

The scheduler scores frontier tasks against agent capabilities (cpu_heavy, memory_heavy, standard) and uses greedy selection to assign tasks. Task profiles are recorded after completion and used to improve future scheduling.

Note

The scheduler improves over time. Early runs use default settings; later runs benefit from learned duration and resource profiles.

Next Steps