Shard Configuration

Overview

DxCore uses dxcore.json files to configure task sharding. This is the only configuration file — there is no YAML config, no dxcore.config.yaml, and no global config file.

File Format

Place a dxcore.json in any package or project directory:

{
  "shards": {
    "test": 4,
    "e2e": 2
  }
}

Each key is a task name and each value is the shard count. The package name is derived from the parent directory name.

Discovery

The dispatcher (CLI-side, via dxcore dispatch) scans **/dxcore.json in the working directory to find all shard configurations. The resolved shard config is then sent to the coordinator as part of the submit_graph WebSocket payload. The coordinator never touches the filesystem — no registration or import is needed. Just place the file and the dispatcher discovers it.

How Sharding Works

When the coordinator receives a task graph, it runs expand_graph which splits tasks into N shards based on priority:

1. Explicit dxcore.json — Highest priority. If a matching task/package entry exists, that shard count is used.
2. Learned profile — If historical TaskProfile data recommends a shard count (recommended_shards), that is used.
3. Default — 1 shard (no splitting).

Example

Given this project structure:

apps/
  web/
    dxcore.json          # {"shards": {"test": 4}}
  api/
    dxcore.json          # {"shards": {"test": 2, "e2e": 3}}
  docs/
    (no dxcore.json)     # uses learned profile or default

The test task for web will be split into 4 shards. The test task for api will be split into 2 shards and e2e into 3. The docs package uses whatever the coordinator’s learned profile recommends, or 1 shard.

Viewing Configuration

Use the CLI to inspect resolved shard configuration:

dxcore config

Next Steps

• CLI command reference
• Troubleshooting