Generic JSON Configuration

Adapter Capabilities

The generic JSON adapter gives you full control over the task graph. You define everything explicitly:

Field	Available	Description
Task ID	Yes	User-defined unique identifier
Package name	Yes	User-defined grouping (e.g., service or project name)
Dependencies	Yes	Explicit dependency edges between task IDs
Task hash	No	Always empty string — no content hashing
Cache status	No	Always MISS — every task runs every time
Command	Yes	Explicit shell command executed by the agent

Build System Flag

Always pass -b generic to both the dispatcher and agent commands:

# Dispatcher
cat graph.json | dxcore dispatch \
  -c $URL -s $SESSION -t $TOKEN -b generic

# Agent
dxcore agent \
  -c $URL -a agent-1 -s $SESSION -t $TOKEN -b generic

JSON Schema Reference

Each task object requires these fields:

Field	Type	Required	Description
taskId	string	Yes	Unique identifier for this task
package	string	Yes	Package or project this task belongs to
task	string	Yes	Task name (e.g., build, test, lint)
command	string	Yes	Shell command to execute
dependencies	array of strings	No	Task IDs that must complete before this task runs. Defaults to []

Validation rules:

• Missing any required field produces an error naming the missing field
• An empty tasks array is valid (the session completes immediately)
• taskId values referenced in dependencies must exist in the tasks array

Working Directory

Use --work-dir (or -w) to set the directory where commands are executed:

cat graph.json | dxcore dispatch \
  -c $URL -s $SESSION -t $TOKEN -b generic -w ./services

dxcore agent \
  -c $URL -a agent-1 -s $SESSION -t $TOKEN -b generic -w ./services

No Sharding Support

The generic adapter does not support dxcore.json shard configuration. Since you define commands explicitly, parallelize by splitting work into separate tasks in your JSON. For example, instead of sharding a test task, define multiple tasks that each run a subset of tests:

{
  "tasks": [
    {
      "taskId": "test-unit",
      "package": "api",
      "task": "test-unit",
      "command": "pytest tests/unit/",
      "dependencies": ["build"]
    },
    {
      "taskId": "test-integration",
      "package": "api",
      "task": "test-integration",
      "command": "pytest tests/integration/",
      "dependencies": ["build"]
    }
  ]
}

Command Templates

By default, the agent executes the command field from your task JSON. If you want the agent to construct commands from task metadata instead, use --command-template:

dxcore agent \
  -c $URL -a agent-1 -s $SESSION -t $TOKEN -b generic \
  --command-template "make -C {package} {task}"

When set, the agent constructs the executed command from the template rather than using the command field directly. The original command is still available via the {command} placeholder for wrapping use cases. This gives the agent operator control over what commands run.

Available Placeholders

Placeholder	Description
{package}	Package name from the task
{task}	Task name
{hash}	Task hash (always empty for generic adapter)
{shard_index}	Shard index (when sharding is configured)
{shard_count}	Shard count (when sharding is configured)
{command}	Original command from the task JSON

Wrapping Commands

Use {command} to wrap the original command rather than replace it:

# Add a timeout to every command
--command-template "timeout 300 {command}"

# Run with reduced priority
--command-template "nice -n 10 {command}"

# Wrap in a custom script
--command-template "./scripts/run.sh {package} {task} {command}"

Validation

• Unknown placeholders (e.g., {foo}) cause the task to fail with an error
• If a placeholder used in the template resolves to an empty value, the task fails
• An empty command after interpolation fails the task

All template errors are reported as task failures (exit_code: -1) with a descriptive log message.

Note: This flag applies to all build system adapters, not just generic. When set, it overrides commands from Turbo, Nx, Gradle, or Docker adapters as well.

Next Steps

• Complete generic JSON workflow example
• CLI command reference