rapid.json Specification

Version: 1.0

Overview

rapid.json is the configuration file for RAPID. It defines how containers are managed, which AI agents are available, how secrets are loaded, and what context is provided to agents.

File Location

RAPID looks for configuration in this order:

rapid.json (project root) - recommended
.rapid/config.json
.rapidrc.json

Schema

{
  "$schema": "https://getrapid.dev/schema/v1/rapid.json"
}

Top-Level Properties

Property	Type	Required	Default	Description
`$schema`	string	No	-	JSON schema URL for validation/IntelliSense
`version`	string	Yes	-	Specification version (`"1.0"`)
`name`	string	No	Directory name	Project name
`container`	object	No	See below	Container configuration
`secrets`	object	No	`{"provider": "env"}`	Secret management
`agents`	object	Yes	-	AI agent configuration
`context`	object	No	See below	Context file settings
`mcp`	object	No	-	MCP server configuration

container

Container lifecycle configuration.

Property	Type	Default	Description
`devcontainer`	string	`".devcontainer/devcontainer.json"`	Path to devcontainer.json
`compose`	string	`null`	Docker Compose file (overrides devcontainer)
`autoStart`	boolean	`true`	Start container automatically on `rapid dev`
`buildArgs`	object	`{}`	Additional Docker build arguments

Example

{
  "container": {
    "devcontainer": ".devcontainer/devcontainer.json",
    "autoStart": true,
    "buildArgs": {
      "NODE_VERSION": "20"
    }
  }
}

secrets

Secret management configuration. RAPID uses .envrc with direnv as the source of truth for secure secret loading.

Property	Type	Default	Description
`provider`	enum	`"1password"`	`"1password"`, `"vault"`, `"env"`
`vault`	string	-	Vault name (1Password) or path (HashiCorp)
`address`	string	-	Vault server address (HashiCorp only)
`items`	object	`{}`	Map of env var names to secret references
`envrc`	object	`{}`	`.envrc` generation settings

envrc Options

Property	Type	Default	Description
`generate`	boolean	`true`	Auto-generate `.envrc` from items
`path`	string	`".envrc"`	Path to `.envrc` file
`includeLocal`	boolean	`true`	Source `.envrc.local` if present

Provider: 1password (Recommended)

{
  "secrets": {
    "provider": "1password",
    "vault": "Development",
    "items": {
      "ANTHROPIC_API_KEY": "op://Development/Anthropic/api-key",
      "OPENAI_API_KEY": "op://Development/OpenAI/api-key",
      "GITHUB_TOKEN": "op://Development/GitHub/pat"
    },
    "envrc": {
      "generate": true,
      "includeLocal": true
    }
  }
}

Generated .envrc:

# .envrc - Generated by RAPID
# Safe to commit - contains references only, not actual secrets

export ANTHROPIC_API_KEY=$(op read "op://Development/Anthropic/api-key")
export OPENAI_API_KEY=$(op read "op://Development/OpenAI/api-key")
export GITHUB_TOKEN=$(op read "op://Development/GitHub/pat")

# Load local overrides (gitignored)
[[ -f .envrc.local ]] && source_env .envrc.local

Provider: vault (HashiCorp)

{
  "secrets": {
    "provider": "vault",
    "address": "https://vault.example.com",
    "vault": "secret/data/dev",
    "items": {
      "ANTHROPIC_API_KEY": "anthropic_key",
      "OPENAI_API_KEY": "openai_key"
    }
  }
}

Generated .envrc:

# .envrc - Generated by RAPID
export VAULT_ADDR="https://vault.example.com"

export ANTHROPIC_API_KEY=$(vault kv get -field=anthropic_key secret/data/dev)
export OPENAI_API_KEY=$(vault kv get -field=openai_key secret/data/dev)

Provider: env (Not Recommended)

Fallback that reads from environment. Does not generate .envrc.

{
  "secrets": {
    "provider": "env"
  }
}

dotenv Integration (Discouraged)

RAPID can load .env files but this is discouraged due to security risks:

{
  "secrets": {
    "provider": "env",
    "dotenv": {
      "enabled": true,
      "files": [".env.local"],
      "warn": true
    }
  }
}

When warn: true, RAPID will display a security warning when loading .env files.

agents

AI agent configuration.

Property	Type	Required	Description
`default`	string	Yes	Name of the default agent
`available`	object	Yes	Map of agent name to configuration

Agent Configuration

Each agent in available supports:

Property	Type	Required	Description
`cli`	string	Yes	CLI command to execute
`instructionFile`	string	No	Path to instruction file for this agent
`envVars`	array	No	Required environment variables
`installCmd`	string	No	Command to install the CLI tool
`args`	array	No	Additional CLI arguments

Example

{
  "agents": {
    "default": "claude",
    "available": {
      "claude": {
        "cli": "claude",
        "instructionFile": "CLAUDE.md",
        "envVars": ["ANTHROPIC_API_KEY"],
        "installCmd": "npm install -g @anthropic-ai/claude-code"
      },
      "opencode": {
        "cli": "opencode",
        "instructionFile": "AGENTS.md",
        "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
        "installCmd": "npm install -g opencode"
      },
      "aider": {
        "cli": "aider",
        "instructionFile": ".aider.conf.yml",
        "envVars": ["OPENAI_API_KEY"],
        "installCmd": "pip install aider-chat",
        "args": ["--model", "gpt-4o"]
      }
    }
  }
}

context

Context file generation and management.

Property	Type	Default	Description
`files`	array	`["README.md"]`	Files to include in agent context
`dirs`	array	`["docs/"]`	Directories to include
`exclude`	array	`[]`	Patterns to exclude
`generateAgentFiles`	boolean	`true`	Auto-generate AGENTS.md, CLAUDE.md
`templateDir`	string	-	Custom templates for agent files

Example

{
  "context": {
    "files": ["README.md", "CONTRIBUTING.md", "docs/architecture.md"],
    "dirs": ["docs/", "specs/"],
    "exclude": ["docs/internal/"],
    "generateAgentFiles": true
  }
}

mcp

Model Context Protocol server configuration. See MCP Server Configuration for detailed setup guide.

Property	Type	Default	Description
`configFile`	string	`".mcp.json"`	Path to MCP config file
`servers`	object	`{}`	MCP server configurations

Server Configuration

Each server in servers supports:

Property	Type	Required	Description
`enabled`	boolean	No	Enable/disable server (default: true)
`type`	string	No	`"remote"` or `"stdio"`
`url`	string	No	URL for remote servers
`headers`	object	No	HTTP headers for remote servers
`command`	string	No	Command for stdio servers
`args`	array	No	Arguments for stdio command
`env`	object	No	Environment variables for stdio

Remote Server Example

{
  "mcp": {
    "configFile": ".mcp.json",
    "servers": {
      "context7": {
        "enabled": true,
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "headers": {
          "Context7-API-Key": "${CONTEXT7_API_KEY}"
        }
      },
      "tavily": {
        "enabled": true,
        "type": "remote",
        "url": "https://mcp.tavily.com/mcp",
        "headers": {
          "Authorization": "Bearer ${TAVILY_API_KEY}"
        }
      }
    }
  }
}

Stdio Server Example

{
  "mcp": {
    "servers": {
      "playwright": {
        "enabled": true,
        "type": "stdio",
        "command": "npx",
        "args": ["@playwright/mcp@latest"]
      },
      "github": {
        "enabled": true,
        "type": "stdio",
        "command": "npx",
        "args": ["@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

Built-in Templates

RAPID includes templates for common servers. Use rapid mcp list --templates to see all available templates.

Template	Type	Description
`context7`	Remote	Documentation context
`tavily`	Remote	Web search
`playwright`	Stdio	Browser automation
`github`	Stdio	GitHub operations
`filesystem`	Stdio	File system access
`memory`	Stdio	Persistent memory
`postgres`	Stdio	PostgreSQL access
`slack`	Stdio	Slack messaging
`fetch`	Stdio	HTTP fetch
`sqlite`	Stdio	SQLite access

Variables

RAPID supports variable substitution in string values:

Variable	Description
`${env:VAR}`	Environment variable from container
`${localEnv:VAR}`	Environment variable from host
`${workspaceFolder}`	Absolute path to project root
`${workspaceFolderBasename}`	Project directory name

Example

{
  "mcp": {
    "servers": {
      "github": {
        "repo": "${localEnv:GITHUB_REPOSITORY}"
      }
    }
  }
}

Complete Example

{
  "$schema": "https://getrapid.dev/schema/v1/rapid.json",
  "version": "1.0",
  "name": "my-rapid-project",

  "container": {
    "devcontainer": ".devcontainer/devcontainer.json",
    "autoStart": true
  },

  "secrets": {
    "provider": "1password",
    "vault": "Development",
    "items": {
      "ANTHROPIC_API_KEY": "op://Development/Anthropic/api-key",
      "OPENAI_API_KEY": "op://Development/OpenAI/api-key",
      "GITHUB_TOKEN": "op://Development/GitHub/pat"
    }
  },

  "agents": {
    "default": "claude",
    "available": {
      "claude": {
        "cli": "claude",
        "instructionFile": "CLAUDE.md",
        "envVars": ["ANTHROPIC_API_KEY"],
        "installCmd": "npm install -g @anthropic-ai/claude-code"
      },
      "opencode": {
        "cli": "opencode",
        "instructionFile": "AGENTS.md",
        "envVars": ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
        "installCmd": "npm install -g opencode"
      },
      "aider": {
        "cli": "aider",
        "instructionFile": ".aider.conf.yml",
        "envVars": ["OPENAI_API_KEY"],
        "installCmd": "pip install aider-chat"
      }
    }
  },

  "context": {
    "files": ["README.md", "CONTRIBUTING.md"],
    "dirs": ["docs/"],
    "generateAgentFiles": true
  },

  "mcp": {
    "configFile": ".mcp.json",
    "servers": {
      "filesystem": { "enabled": true },
      "github": { "enabled": true }
    }
  }
}

JSON Schema

For editor IntelliSense and validation, reference the schema:

{
  "$schema": "https://getrapid.dev/schema/v1/rapid.json"
}

Or install the RAPID VS Code extension for automatic schema association.