Configuration Reference

Complete reference for axis.config.json.

Full Example

AXIS is configured via an axis.config.json file in your project root. Here is an example showing all available fields:

{
  "scenarios": "./scenarios",
  "agents": [
    "claude-code",
    {
      "adapter": "gemini",
      "model": "gemini-2.5-pro",
      "scenarios": ["cms/*"],
      "flags": { "yolo": true }
    }
  ],
  "settings": {
    "concurrency": 4,
    "scoring_weights": {
      "goal_achievement": 0.4,
      "environment": 0.2,
      "service": 0.2,
      "agent": 0.2
    },
    "limits": {
      "run": { "time_minutes": 60, "tokens": 2000000 },
      "scenario": { "time_minutes": 10, "tokens": 200000 }
    }
  },
  "env": ["ANTHROPIC_API_KEY", "GEMINI_API_KEY"],
  "mcp_servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  },
  "skills": ["./skills/deploy"],
  "adapters": {
    "my-agent": "./adapters/my-agent.ts"
  }
}

Top-Level Fields

Agent Configuration

Each entry in the agents array can be a simple string (agent name with defaults) or a full configuration object.

Scoring Weights

Override the default dimension weights under settings.scoring_weights. Values must sum to 1.0. See Scoring Framework for what each dimension measures.

{
  "settings": {
    "scoring_weights": {
      "goal_achievement": 0.5,
      "environment": 0.2,
      "service": 0.2,
      "agent": 0.1
    }
  }
}

Limits

Limits control how much time and tokens a run or individual scenario can consume. This prevents runaway agents from consuming unbounded resources. Limits can be configured at three levels:

• Overall run limits (settings.limits.run) — when hit, all remaining and in-progress jobs are aborted.
• Default scenario limits (settings.limits.scenario) — default budget for each individual job. Only that job fails when exceeded.
• Per-scenario limits (limits in the scenario JSON) — override the defaults for a specific scenario. Only that job fails when exceeded.

Default behavior

Even without any limits configured, each scenario has a default time limit of 15 minutes. You can override this by setting settings.limits.scenario.time_minutes or by adding limits.time_minutes to individual scenarios.

Limit fields

Overall run limits

Set settings.limits.run to cap the total time or tokens across the entire run. When an overall limit is reached, all remaining and currently running jobs are immediately terminated and marked as failed.

{
  "settings": {
    "limits": {
      "run": { "time_minutes": 60, "tokens": 2000000 }
    }
  }
}

Per-scenario limits

Set settings.limits.scenario to define default per-job budgets. These can be overridden by adding a limits field directly in a scenario file.

// axis.config.json — default for all scenarios
{
  "settings": {
    "limits": {
      "scenario": { "time_minutes": 10, "tokens": 200000 }
    }
  }
}

// scenarios/expensive-task.json — override for one scenario
{
  "name": "Expensive task",
  "prompt": "...",
  "rubric": "...",
  "limits": { "time_minutes": 30, "tokens": 500000 }
}

MCP Servers

Configure Model Context Protocol servers that are automatically wired into each agent environment. AXIS supports both stdio (local process) and HTTP (remote endpoint) servers.

{
  "mcp_servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": { "LOG_LEVEL": "info" }
    },
    "remote-api": {
      "type": "http",
      "url": "https://mcp.example.com/tools",
      "headers": { "Authorization": "Bearer ${TOKEN}" }
    }
  }
}

Each agent writes MCP configuration in its native format before spawning:

Skills

Skills extend agent capabilities with reusable instruction sets. Specify them at the top level (shared across all agents), per agent, or per scenario.

{
  "skills": [
    "./skills/deploy",
    "netlify/axis-skill-deploy",
    "https://github.com/owner/repo"
  ]
}

Remote skills are cached in .axis/skills-cache/. Use --refresh-skills to force re-clone.

Environment Variables

The env field lists additional environment variables to pass through to agent processes. The following are always passed through by default:

{
  "env": ["MY_CUSTOM_TOKEN", "DATABASE_URL"]
}

Scenarios

Scenarios are JSON files in the configured scenarios directory. The filename (without .json) becomes the scenario key. Nested directories create namespaced keys -for example, scenarios/cms/create-post.json maps to key cms/create-post.

Scenarios can define variants to run the same task under different configurations (skills, MCP servers, prompts, etc.) without duplicating files. Each variant produces a separate job with a key like create-post@variant-name.

See Writing Scenarios for the complete scenario schema, rubric design guidance, and example scenarios.