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
    }
  },
  "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

Field Type Required Description
scenarios string Yes Path to the scenarios directory.
agents (string | AgentConfig)[] Yes Agent names or full agent configurations.
settings object No Concurrency and scoring weight overrides.
env string[] No Additional environment variables to pass through to agent processes.
mcp_servers object No MCP servers available to all agents.
skills string[] No Skills available to all agents.
adapters object No Custom agent module paths, keyed by agent name.

Agent Configuration

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

Field Type Required Description
adapter string Yes Agent name: claude-code, codex, gemini, goose, etc.
model string No Model override passed to the agent CLI.
scenarios string[] No Subset of scenarios to run. Supports glob patterns like cms/*.
skills string[] No Agent-specific skills (merged with top-level skills).
flags object No CLI flags passed to the agent, e.g. {"full-auto": true}.
command string No Custom CLI command (for custom agents).

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.

Field Type Required Description
goal_achievement number No Goal Achievement weight. Default: 0.4.
environment number No Environment weight. Default: 0.2.
service number No Service weight. Default: 0.2.
agent number No Agent weight. Default: 0.2. 
{
  "settings": {
    "scoring_weights": {
      "goal_achievement": 0.5,
      "environment": 0.2,
      "service": 0.2,
      "agent": 0.1
    }
  }
}

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.

Field Type Required Description
type "stdio" | "http" Yes Server transport type.
command string Yes Command to start the server process (stdio only).
args string[] No Arguments passed to the command.
env object No Environment variables for the server process.
url string Yes Remote server endpoint URL (http only).
headers object No HTTP headers (supports ${VAR} env interpolation). 
{
  "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:

Agent Config File Location
claude-code .mcp.json Workspace root
codex config.toml CODEX_HOME
gemini settings.json GEMINI_CLI_HOME

Skills

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

Format Example Description
Local path ./skills/deploy Relative to the config file.
GitHub shorthand netlify/axis-skill-deploy owner/repo format, cloned automatically.
Full URL https://github.com/owner/repo GitHub repository URL, cloned automatically. 
{
  "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:

Category Variables
API keys ANTHROPIC_API_KEY, CODEX_API_KEY, GEMINI_API_KEY
System PATH, USER, SHELL, LANG, TERM, TMPDIR 
{
  "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.