From c199e8c32117e09826397c3af09cf676384cd73f Mon Sep 17 00:00:00 2001 From: Angel M Miguel Date: Tue, 27 Jan 2026 12:48:32 +0100 Subject: [PATCH 1/3] feat: move the configuration to a separate section and add missing features --- astro.config.mjs | 8 + .../docs/rover/configuration/hooks.mdx | 159 ++++++++++ .../configuration/project-configuration.mdx | 231 +++++++++++++++ .../configuration/sandbox-configuration.mdx | 263 +++++++++++++++++ .../rover/configuration/user-settings.mdx | 144 +++++++++ .../docs/rover/intro/configuration.mdx | 276 ------------------ 6 files changed, 805 insertions(+), 276 deletions(-) create mode 100644 src/content/docs/rover/configuration/hooks.mdx create mode 100644 src/content/docs/rover/configuration/project-configuration.mdx create mode 100644 src/content/docs/rover/configuration/sandbox-configuration.mdx create mode 100644 src/content/docs/rover/configuration/user-settings.mdx delete mode 100644 src/content/docs/rover/intro/configuration.mdx diff --git a/astro.config.mjs b/astro.config.mjs index e9e1446..c636579 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -79,6 +79,10 @@ export default defineConfig({ status: 301, destination: '/rover/reference/cli-reference/', }, + '/rover/intro/configuration': { + status: 301, + destination: '/rover/configuration/project-configuration', + }, }, integrations: [ // @see https://github.com/joesaby/astro-mermaid?tab=readme-ov-file#integration-order-important @@ -105,6 +109,10 @@ export default defineConfig({ label: 'Key Concepts', autogenerate: { directory: 'rover/concepts' }, }, + { + label: 'Configuration', + autogenerate: { directory: 'rover/configuration' }, + }, { label: 'Guides', autogenerate: { directory: 'rover/guides' }, diff --git a/src/content/docs/rover/configuration/hooks.mdx b/src/content/docs/rover/configuration/hooks.mdx new file mode 100644 index 0000000..76fb57a --- /dev/null +++ b/src/content/docs/rover/configuration/hooks.mdx @@ -0,0 +1,159 @@ +--- +title: Hooks +description: Run custom commands when tasks are merged, pushed, or completed +sidebar: + order: 3 +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +Hooks let you run custom shell commands at specific points in the task lifecycle. Use them to trigger notifications, update dashboards, run CI pipelines, or integrate with other tools. + +## Available Hooks + +| Hook | Trigger | +|------|---------| +| `onMerge` | Runs after a task is successfully merged via `rover merge` | +| `onPush` | Runs after a task branch is pushed via `rover push` | +| `onComplete` | Runs when a task finishes (success or failure), detected via `rover list` | + +## Configuration + +Add hooks to your `rover.json` file: + +```jsonc +{ + "version": "1.2", + "languages": ["typescript"], + "packageManagers": ["npm"], + "hooks": { + "onComplete": ["./scripts/on-complete.sh"], + "onMerge": ["./scripts/on-merge.sh"], + "onPush": ["echo 'Task $ROVER_TASK_ID pushed'"] + } +} +``` + +Each hook accepts an array of shell commands. Commands are executed sequentially in the order specified. + +## Environment Variables + +Rover passes task information to hooks via environment variables: + +| Variable | Description | Available In | +|----------|-------------|--------------| +| `ROVER_TASK_ID` | The task ID | All hooks | +| `ROVER_TASK_BRANCH` | The task branch name | All hooks | +| `ROVER_TASK_TITLE` | The task title | All hooks | +| `ROVER_TASK_STATUS` | Task status: `completed` or `failed` | `onComplete` only | + +## Example Hook Script + +Create a script that notifies your team when a task completes: + +```bash +#!/bin/bash +# scripts/on-complete.sh + +echo "Task $ROVER_TASK_ID ($ROVER_TASK_TITLE) finished with status: $ROVER_TASK_STATUS" + +# Send a Slack notification +if [ "$ROVER_TASK_STATUS" = "completed" ]; then + curl -X POST -H 'Content-type: application/json' \ + --data "{\"text\":\"Task #$ROVER_TASK_ID completed: $ROVER_TASK_TITLE\"}" \ + "$SLACK_WEBHOOK_URL" +fi +``` + +Make sure to set execute permissions: + +```sh +chmod +x scripts/on-complete.sh +``` + +## Hook Behavior + +### Execution Context + +- Hooks run in the **project directory** (where `rover.json` is located) +- Commands execute via the shell (`sh -c`), supporting pipes and complex commands +- Hooks inherit the current environment plus `ROVER_*` variables + +### Error Handling + +- Hook failures are logged as **warnings** but don't interrupt the main operation +- If a hook fails, subsequent hooks in the array still execute +- The primary command (`merge`, `push`, `list`) completes regardless of hook failures + + + +### Deduplication + +The `onComplete` hook only triggers on **new** status transitions. If a task was already completed and you run `rover list` again, the hook won't re-execute. + +## Use Cases + +### Notify on Completion + +Send notifications when tasks finish: + +```jsonc +{ + "hooks": { + "onComplete": [ + "curl -X POST https://api.example.com/webhook -d '{\"task\": \"$ROVER_TASK_ID\", \"status\": \"$ROVER_TASK_STATUS\"}'" + ] + } +} +``` + +### Trigger CI on Push + +Start a CI pipeline when a task branch is pushed: + +```jsonc +{ + "hooks": { + "onPush": [ + "gh workflow run ci.yml --ref $ROVER_TASK_BRANCH" + ] + } +} +``` + +### Update Issue Tracker on Merge + +Close related issues when tasks are merged: + +```jsonc +{ + "hooks": { + "onMerge": [ + "./scripts/close-issue.sh" + ] + } +} +``` + +### Multiple Commands + +Chain multiple commands for a single hook: + +```jsonc +{ + "hooks": { + "onComplete": [ + "echo 'Task $ROVER_TASK_ID completed'", + "./scripts/notify-slack.sh", + "./scripts/update-dashboard.sh" + ] + } +} +``` + +## Next Steps + + + + + diff --git a/src/content/docs/rover/configuration/project-configuration.mdx b/src/content/docs/rover/configuration/project-configuration.mdx new file mode 100644 index 0000000..e8892fe --- /dev/null +++ b/src/content/docs/rover/configuration/project-configuration.mdx @@ -0,0 +1,231 @@ +--- +title: Project Configuration +description: Configure project-wide settings shared across your team +sidebar: + order: 1 +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +The **`rover.json`** file is an **optional** configuration file that defines project-wide settings. Rover works out of the box without it. When you run any Rover command in a git repository, Rover [automatically registers the project](/rover/concepts/project) and detects your environment. + +Create a `rover.json` when you want to: + +- **Share configuration with your team**: Commit the file to version control so everyone uses the same MCP servers, environment variables, and hooks +- **Add MCP servers**: Provide additional context to AI agents via Model Context Protocol +- **Configure hooks**: Run custom commands when tasks are merged, pushed, or completed +- **Pass environment variables**: Share API keys or configuration with containerized agents + +You can create a `rover.json` manually or run `rover init` to generate one with detected defaults. + +## Configuration Options + +| Field | Description | +|-------|-------------| +| `languages` | Programming languages used in the project | +| `packageManagers` | Package managers available (npm, pnpm, pip, etc.) | +| `taskManagers` | Task runners like Make, Just, or Task | +| `mcps` | Model Context Protocol servers providing additional context to AI agents | +| `attribution` | Whether Rover adds itself as co-author on AI-assisted commits | +| `envs` | Custom environment variables passed to containerized agents | +| `envsFile` | Path to a dotenv file with environment variables | +| `hooks` | Commands to run at task lifecycle events ([see Hooks](/rover/configuration/hooks)) | +| `sandbox` | Customize the container environment ([see Sandbox Configuration](/rover/configuration/sandbox-configuration)) | +| `excludePatterns` | Glob patterns for files to exclude from task workspaces | + +## Basic Structure + +Here's a minimal example: + +```jsonc +{ + // Schema version for automatic migration + "version": "1.3", + + // Programming languages used in the project + "languages": ["typescript", "javascript"], + + // Package managers available + "packageManagers": ["npm"], + + // Task runners (optional) + "taskManagers": [], + + // MCP servers for AI context (optional) + "mcps": [], + + // Add Rover as co-author on commits + "attribution": true +} +``` + + + +## MCP Servers + +Add Model Context Protocol servers to provide additional context to AI agents. These MCP servers are automatically installed in each [task](/rover/concepts/task)'s [sandboxed environment](/rover/concepts/sandbox). + +```jsonc +{ + "version": "1.3", + "languages": ["typescript"], + "packageManagers": ["npm"], + "mcps": [ + { + "name": "filesystem", + "commandOrUrl": "npx -y @modelcontextprotocol/server-filesystem /path/to/files", + "transport": "stdio" + }, + { + "name": "database", + "commandOrUrl": "npx -y @modelcontextprotocol/server-postgres", + "transport": "stdio", + "envs": ["DATABASE_URL"] + } + ] +} +``` + +## Environment Variables + +Pass environment variables to containerized AI agents using two methods. + +### Inline Variables + +Use the `envs` array to pass environment variables: + +```jsonc +{ + "version": "1.3", + "languages": ["javascript"], + "packageManagers": ["npm"], + "envs": [ + "NODE_ENV", // Pass through from host + "DEBUG=true", // Set explicit value + "API_KEY" // Pass through from host + ] +} +``` + +Environment variable formats: +- `"ENV_NAME"`: Pass the current value from your host machine to the container +- `"ENV_NAME=VALUE"`: Set a specific value in the container (overrides host value) + +### Dotenv File + +Load variables from a dotenv file using the `envsFile` field: + +```jsonc +{ + "version": "1.3", + "languages": ["javascript"], + "packageManagers": ["npm"], + "envsFile": ".env.rover" +} +``` + +Create a `.env.rover` file in your project root: + +```bash +NODE_ENV=development +DEBUG=true +API_KEY=your-api-key-here +DATABASE_URL=postgres://localhost:5432/mydb +``` + + + +### Combined Approach + +You can use both `envs` and `envsFile` together. Values in `envs` take precedence: + +```jsonc +{ + "version": "1.3", + "languages": ["javascript"], + "packageManagers": ["npm"], + "envsFile": ".env.rover", // Load from file + "envs": ["DEBUG=false"] // Override specific values +} +``` + +## Attribution + +Control whether Rover adds itself as co-author on commits: + +```jsonc +{ + "version": "1.3", + "languages": ["typescript"], + "packageManagers": ["npm"], + "attribution": false +} +``` + +When attribution is enabled, commits generated by Rover include: + +``` +Co-Authored-By: Rover +``` + +## Exclude Patterns + +Use `excludePatterns` to prevent specific files from being checked out in task workspaces. Excluded files won't be visible to or modifiable by AI agents. This is useful for: + +- **Sensitive files**: Credentials, API keys, or secrets +- **Large files**: Binary assets, datasets, or generated files +- **Protected code**: Files that shouldn't be modified by agents + +```jsonc +{ + "version": "1.3", + "languages": ["typescript"], + "packageManagers": ["npm"], + "excludePatterns": [ + "secrets/**", + "*.env", + ".env.*", + "credentials.json", + "data/*.csv" + ] +} +``` + +Patterns use glob syntax and are applied via git sparse checkout: + +| Pattern | Matches | +|---------|---------| +| `secrets/**` | All files in the `secrets/` directory | +| `*.env` | All files ending in `.env` | +| `.env.*` | Files like `.env.local`, `.env.production` | +| `internal/config.ts` | A specific file | +| `/root-only.txt` | File only at the repository root | + + + +## Schema Versioning + + + +The `version` field enables automatic migration when upgrading Rover: + +```jsonc +{ + "version": "1.3", // Current project config version + // ... other settings +} +``` + +When Rover detects an older schema version, it automatically migrates your configuration to the latest format. + +## Reference + +For a complete list of all available configuration options, see the [Project Config Reference](/rover/reference/project-config). + +## Next Steps + + + + + + diff --git a/src/content/docs/rover/configuration/sandbox-configuration.mdx b/src/content/docs/rover/configuration/sandbox-configuration.mdx new file mode 100644 index 0000000..71f8a12 --- /dev/null +++ b/src/content/docs/rover/configuration/sandbox-configuration.mdx @@ -0,0 +1,263 @@ +--- +title: Sandbox Configuration +description: Customize the containerized environment where tasks run +sidebar: + order: 4 +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +The sandbox configuration lets you customize the containerized environment where AI agents execute tasks. Use it to provide custom Docker images, run initialization scripts, pass extra container arguments, or control network access. + +All sandbox options are configured under the `sandbox` key in your `rover.json`: + +```jsonc +{ + "version": "1.3", + "languages": ["typescript"], + "packageManagers": ["npm"], + "sandbox": { + "agentImage": "my-registry/custom-agent:latest", + "initScript": "./scripts/init-sandbox.sh", + "extraArgs": ["--memory=4g"], + "network": { + "mode": "allowlist", + "rules": [{ "host": "api.example.com" }] + } + } +} +``` + +## Custom Agent Image + +Use the `agentImage` option to specify a custom Docker or Podman image instead of Rover's default agent image. + +```jsonc +{ + "sandbox": { + "agentImage": "ghcr.io/my-org/custom-agent:v1.0" + } +} +``` + +### Image Resolution Priority + +Rover resolves the agent image in this order: + +1. `AGENT_IMAGE` environment variable (highest priority) +2. Image stored in the task (from previous runs) +3. `agentImage` from `rover.json` +4. Default Rover agent image (based on CLI version) + + + +### Building Custom Images + +Custom images should be based on Rover's agent image or include compatible tooling. The image must have the AI agent CLI installed (Claude Code, Codex, Gemini CLI, etc.). + +```dockerfile +FROM ghcr.io/endorhq/rover/agent:latest + +# Add your custom tools +RUN apt-get update && apt-get install -y my-custom-tool + +# Add custom configuration +COPY my-config /etc/my-config +``` + +## Initialization Script + +The `initScript` option runs a shell script inside the container before the AI agent starts. Use it to set up the environment, install dependencies, or configure tools. + +```jsonc +{ + "sandbox": { + "initScript": "./scripts/init-sandbox.sh" + } +} +``` + +The path is relative to your project root. The script is mounted read-only at `/init-script.sh` inside the container. + +### Example Script + +```bash +#!/bin/bash +# scripts/init-sandbox.sh + +# Install additional system packages +apt-get update && apt-get install -y graphviz + +# Configure git +git config --global user.name "AI Agent" +git config --global user.email "agent@example.com" + +# Set up environment +export MY_CUSTOM_VAR="value" +``` + + + +## Extra Container Arguments + +The `extraArgs` option passes additional arguments directly to Docker or Podman when starting the container. Use it for advanced configuration like memory limits, CPU constraints, or additional volume mounts. + +```jsonc +{ + "sandbox": { + "extraArgs": ["--memory=4g", "--cpus=2"] + } +} +``` + +You can also use a single string with space-separated arguments: + +```jsonc +{ + "sandbox": { + "extraArgs": "--memory=4g --cpus=2" + } +} +``` + +### Common Use Cases + +| Arguments | Purpose | +|-----------|---------| +| `--memory=4g` | Limit container memory to 4GB | +| `--cpus=2` | Limit to 2 CPU cores | +| `-v /host/path:/container/path` | Mount additional volumes | +| `--gpus all` | Enable GPU access (Docker) | +| `--device /dev/dri` | Pass through GPU device (Podman) | + + + +## Network Configuration + +Control network access from the sandbox using allowlist or blocklist modes. This is useful for security-conscious environments or when you want to restrict which external services the AI agent can access. + +```jsonc +{ + "sandbox": { + "network": { + "mode": "allowlist", + "rules": [ + { "host": "api.github.com", "description": "GitHub API" }, + { "host": "registry.npmjs.org", "description": "npm registry" } + ], + "allowDns": true, + "allowLocalhost": true + } + } +} +``` + +### Network Modes + +| Mode | Behavior | +|------|----------| +| `allowall` | No filtering (default). All network traffic is allowed. | +| `allowlist` | Deny all traffic except to specified hosts. | +| `blocklist` | Allow all traffic except to specified hosts. | + +### Network Rules + +Rules specify which hosts to allow or block. Each rule supports: + +- **Domain names**: `api.github.com`, `*.example.com` +- **IP addresses**: `192.168.1.1` +- **CIDR notation**: `10.0.0.0/8`, `192.168.0.0/16` + +```jsonc +{ + "sandbox": { + "network": { + "mode": "allowlist", + "rules": [ + { "host": "api.github.com" }, + { "host": "192.168.1.0/24", "description": "Local network" }, + { "host": "10.0.0.5" } + ] + } + } +} +``` + +### Additional Options + +| Option | Default | Description | +|--------|---------|-------------| +| `allowDns` | `true` | Allow DNS resolution. Keep enabled unless you're using IP addresses only. | +| `allowLocalhost` | `true` | Allow localhost/loopback traffic. Required for MCP servers. | + +### Example: Restricted Environment + +Allow only essential services for a Node.js project: + +```jsonc +{ + "sandbox": { + "network": { + "mode": "allowlist", + "rules": [ + { "host": "registry.npmjs.org", "description": "npm packages" }, + { "host": "api.github.com", "description": "GitHub API" }, + { "host": "api.anthropic.com", "description": "Claude API" } + ], + "allowDns": true, + "allowLocalhost": true + } + } +} +``` + +### Example: Block Specific Hosts + +Block known problematic or unwanted destinations: + +```jsonc +{ + "sandbox": { + "network": { + "mode": "blocklist", + "rules": [ + { "host": "telemetry.example.com", "description": "Block telemetry" }, + { "host": "ads.example.com" } + ] + } + } +} +``` + +## Combining Options + +You can use all sandbox options together: + +```jsonc +{ + "version": "1.3", + "languages": ["python"], + "packageManagers": ["pip"], + "sandbox": { + "agentImage": "my-registry/python-agent:latest", + "initScript": "./scripts/setup-python-env.sh", + "extraArgs": ["--memory=8g", "--cpus=4"], + "network": { + "mode": "allowlist", + "rules": [ + { "host": "pypi.org" }, + { "host": "files.pythonhosted.org" }, + { "host": "api.anthropic.com" } + ] + } + } +} +``` + +## Next Steps + + + + + + diff --git a/src/content/docs/rover/configuration/user-settings.mdx b/src/content/docs/rover/configuration/user-settings.mdx new file mode 100644 index 0000000..45826f1 --- /dev/null +++ b/src/content/docs/rover/configuration/user-settings.mdx @@ -0,0 +1,144 @@ +--- +title: User Settings +description: Configure user-specific preferences that aren't shared with your team +sidebar: + order: 2 +--- + +import StepList from '../../../../components/StepList.svelte'; +import StepItem from '../../../../components/StepItem.svelte'; +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +The **`.rover/settings.json`** file stores user-specific preferences that should not be shared across your team. This file is automatically added to `.gitignore` when you run `rover init`. + +## Configuration Options + +| Field | Description | +|-------|-------------| +| `aiAgents` | List of AI agents installed on your machine | +| `defaults.aiAgent` | Your preferred AI agent to use by default | +| `defaults.models` | Default model to use for each AI agent | +| `defaults.watchIntervalSeconds` | Polling interval for `rover list --watch` (1-60 seconds, default: 3) | + +## Basic Structure + +Here's a typical user settings file: + +```jsonc +{ + // Schema version for automatic migration + "version": "1.0", + + // AI agents installed on this machine + "aiAgents": ["claude", "gemini"], + + // Default preferences + "defaults": { + "aiAgent": "claude", + "models": { + "claude": "sonnet" + } + } +} +``` + + + +## Setting a Default Agent + +Choose your preferred AI agent: + +```jsonc +{ + "version": "1.0", + "aiAgents": ["claude", "gemini"], + "defaults": { + "aiAgent": "gemini" + } +} +``` + +The default agent is used when you create tasks without explicitly specifying an agent. You can always override this choice for specific tasks: + +```sh +rover task --agent claude "Fix the login bug" +``` + +## Default Models + +Configure which model each AI agent should use by default. This is useful when you want to use a specific model tier (like Claude's Opus or Sonnet) without specifying it every time. + +```jsonc +{ + "version": "1.0", + "aiAgents": ["claude", "gemini"], + "defaults": { + "aiAgent": "claude", + "models": { + "claude": "opus", + "gemini": "flash" + } + } +} +``` + +The available models depend on each AI agent. Common options include: + +| Agent | Example Models | +|-------|----------------| +| `claude` | `opus`, `sonnet`, `haiku` | +| `gemini` | `pro`, `flash` | + +You can override the default model for specific tasks using the `--agent agent:model` syntax: + +```sh +rover task --agent claude:sonnet "Quick code review" +``` + +## Reference + +For a complete list of all available configuration options, see the [User Config Reference](/rover/reference/user-config). + +## Telemetry + +Rover has basic telemetry reporting to help understand how the tool is used. This telemetry does not identify you, as it generates a fully random hash you can change. You can find your random ID at `~/.config/rover/.user`. + +The only information recorded by telemetry is which action was invoked and basic metadata like the action source (CLI or VS Code Extension). Telemetry **does not record** any data from prompts, task titles, or descriptions. + +### Disabling Telemetry + +There are two ways to disable telemetry in Rover. + +**Option 1: Create a no-telemetry file** + + + + ```sh + mkdir -p ~/.config/rover + ``` + + + ```sh + touch ~/.config/rover/.no-telemetry + ``` + + + +**Option 2: Use an environment variable** + +Set the `ROVER_NO_TELEMETRY` environment variable: + +```sh +# For a single command +ROVER_NO_TELEMETRY=true rover list + +# Or export it globally +export ROVER_NO_TELEMETRY=true +``` + +## Next Steps + + + + + diff --git a/src/content/docs/rover/intro/configuration.mdx b/src/content/docs/rover/intro/configuration.mdx deleted file mode 100644 index 46d2424..0000000 --- a/src/content/docs/rover/intro/configuration.mdx +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: Configuration -description: Configure Rover with project-wide and user-specific settings -sidebar: - order: 3 ---- - -import StepList from '../../../../components/StepList.svelte'; -import StepItem from '../../../../components/StepItem.svelte'; -import { Aside } from '@astrojs/starlight/components'; - -Rover uses a two different configuration files for the project-wide settings and user-specific preferences: - -- **`rover.json`**: Project-wide configuration committed to version control. Defines project context (languages, package managers, MCP servers) that all team members share. -- **`.rover/settings.json`**: User-specific settings automatically added to `.gitignore`. Stores user-specific configuration like installed AI agents and your default agent preference. - -Both files are created automatically when you run `rover init`. Rover detects your project environment and populates them with appropriate defaults. Checkout the [quickstart guide](/rover/intro/quickstart) to learn how to initialize Rover in your projects. - -## Project Configuration (rover.json) - -The **`rover.json`** file defines project-wide settings shared across your team. This file is committed to version control. It defines: - -- **languages**: Programming languages used in the project -- **packageManagers**: Package managers available (npm, pnpm, pip, etc.) -- **taskManagers**: Task runners like Make, Just, or Task -- **mcps**: Model Context Protocol servers providing additional context to AI agents -- **attribution**: Whether Rover adds itself as co-author on AI-assisted commits -- **envs**: Custom environment variables passed to containerized agents -- **envsFile**: Path to a dotenv file with environment variables - -### Basic rover.json Structure - -Here's a minimal example: - -```jsonc -{ - // Schema version for automatic migration - "version": "1.2", - - // Programming languages used in the project - "languages": ["typescript", "javascript"], - - // Package managers available - "packageManagers": ["npm"], - - // Task runners (optional) - "taskManagers": [], - - // MCP servers for AI context (optional) - "mcps": [], - - // Add Rover as co-author on commits - "attribution": true -} -``` - -### Version Control - -✅ Commit this file so your team shares the same project configuration - -### Configuring MCP Servers - -Add Model Context Protocol servers to provide additional context to AI agents. These MCP servers will be automatically installed in each [task](/rover/concepts/task)'s [sandboxed environment](/rover/concepts/sandbox). - -```jsonc -{ - "version": "1.2", - "languages": ["typescript"], - "packageManagers": ["npm"], - "taskManagers": [], - "mcps": [ - { - "name": "filesystem", - "commandOrUrl": "npx -y @modelcontextprotocol/server-filesystem /path/to/files", - "transport": "stdio" - }, - { - "name": "database", - "commandOrUrl": "npx -y @modelcontextprotocol/server-postgres", - "transport": "stdio", - "envs": ["DATABASE_URL"] - } - ], - "attribution": true -} -``` - -### Custom Environment Variables - -Pass environment variables to containerized AI agents using two methods: - -**Method 1: Inline environment variables** using the `envs` array: - -```jsonc -{ - "version": "1.2", - "languages": ["javascript"], - "packageManagers": ["npm"], - "taskManagers": [], - "mcps": [], - "attribution": true, - "envs": [ - "NODE_ENV", // Pass through from host - "DEBUG=true", // Set explicit value - "API_KEY" // Pass through from host - ] -} -``` - -Environment variable formats: -- `"ENV_NAME"`: Pass the current value from your host machine to the container -- `"ENV_NAME=VALUE"`: Set a specific value in the container (overrides host value) - -**Method 2: Load from a dotenv file** using the `envsFile` field: - -```jsonc -{ - "version": "1.2", - "languages": ["javascript"], - "packageManagers": ["npm"], - "taskManagers": [], - "mcps": [], - "attribution": true, - "envsFile": ".env.rover" -} -``` - -Create a `.env.rover` file in your project root: - -```bash -NODE_ENV=development -DEBUG=true -API_KEY=your-api-key-here -DATABASE_URL=postgres://localhost:5432/mydb -``` - -**Security note**: Never commit `.env` files with sensitive credentials. Add them to `.gitignore` and provide a `.env.example` file instead. - -**Combined approach**: You can use both `envs` and `envsFile` together. Values in `envs` take precedence: - -```jsonc -{ - "version": "1.2", - "languages": ["javascript"], - "packageManagers": ["npm"], - "taskManagers": [], - "mcps": [], - "attribution": true, - "envsFile": ".env.rover", // Load from file - "envs": ["DEBUG=false"] // Override specific values -} -``` - -### Disabling Attribution - -Control whether Rover adds itself as co-author on commits: - -```jsonc -{ - "version": "1.2", - "languages": ["typescript"], - "packageManagers": ["npm"], - "taskManagers": [], - "mcps": [], - "attribution": false -} -``` - -When attribution is enabled, commits generated by Rover will include: - -``` -Co-Authored-By: Rover -``` - -### Reference - -You have a full reference of all available configuration options in the [Project Config reference](/rover/reference/project-config). - -## User Settings (.rover/settings.json) - -The **`.rover/settings.json`** file stores user-specific preferences that should not be shared across your team. This file is automatically added to `.gitignore`. It defines: - -- **aiAgents**: List of AI agents installed on your machine -- **defaultAgent**: Your preferred AI agent to use by default - -These settings are user-specific because different developers may have different AI agents installed and prefer different agents for different tasks. - -### Basic settings.json Structure - -Here's a typical user settings file: - -```jsonc -{ - // Schema version for automatic migration - "version": "1.0", - - // AI agents installed on this machine - "aiAgents": ["claude", "gemini"], - - // Default agent preference - "defaults": { - "aiAgent": "claude" - } -} -``` - -### Version Control - -❌ Do not commit this file (automatically added to `.gitignore`) - -### Setting a Default Agent - -Choose your preferred AI agent: - -```jsonc -{ - "version": "1.0", - "aiAgents": ["claude", "gemini"], - "defaults": { - "aiAgent": "gemini" - } -} -``` - -The default agent is used when you create tasks without explicitly specifying an agent. You can always override this choice for specific tasks. - -### Reference - -You have a full reference of all available configuration options in the [User Config reference](/rover/reference/user-config). - -## Schema Versioning - - - -Both files include a `version` field for automatic migration. - -```jsonc -{ - "version": "1.2", // Current project config version - // ... other settings -} -``` - -When Rover detects an older schema version, it automatically migrates your configuration to the latest format. This ensures backward compatibility when upgrading Rover. - -## Telemetry - -Rover has very basic telemetry reporting to help us understand how you use the tool. This telemetry does not identify you, as it generates a fully random hash you can change. You can find your random ID at `~/.config/rover/.user`. - -The only information that is recorded by the telemetry is which action was invoked, and very basic metadata like the action source (CLI or VSCode Extension). Telemetry **does not record** any data from prompts or task titles and descriptions. - -### Disabling telemetry - -There are two ways to completely disable telemetry in Rover. One is in your home directory Rover settings, and the other one is by exporting the `ROVER_NO_TELEMETRY` environment variable. - - - - ```sh - mkdir -p ~/.config/rover - ``` - - - ```sh - touch ~/.config/rover/.no-telemetry - ``` - - - - - You can either export a `ROVER_NO_TELEMETRY` environment variable set to `true` globally, or you can set it every time you run the Rover CLI. - - ```sh - ROVER_NO_TELEMETRY=true rover list - ``` - - \ No newline at end of file From 7d8e535a411d843d53a4a9e27ad1d7845fcf964f Mon Sep 17 00:00:00 2001 From: Angel M Miguel Date: Tue, 27 Jan 2026 12:59:57 +0100 Subject: [PATCH 2/3] chore: rename routes, fix links and fix highlight name --- astro.config.mjs | 218 ++++++++++-------- src/content/docs/rover/concepts/sandbox.mdx | 4 +- .../rover/{configuration => config}/hooks.mdx | 4 +- .../project-config.mdx} | 10 +- .../sandbox-config.mdx} | 4 +- .../user-settings.mdx | 4 +- .../docs/rover/guides/write-workflows.mdx | 4 +- 7 files changed, 131 insertions(+), 117 deletions(-) rename src/content/docs/rover/{configuration => config}/hooks.mdx (93%) rename src/content/docs/rover/{configuration/project-configuration.mdx => config/project-config.mdx} (92%) rename src/content/docs/rover/{configuration/sandbox-configuration.mdx => config/sandbox-config.mdx} (96%) rename src/content/docs/rover/{configuration => config}/user-settings.mdx (93%) diff --git a/astro.config.mjs b/astro.config.mjs index c636579..9386983 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -1,13 +1,13 @@ -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; -import starlightLinksValidator from 'starlight-links-validator'; -import starlightThemeRapide from 'starlight-theme-rapide'; -import starlightSidebarTopics from 'starlight-sidebar-topics'; -import svelte from '@astrojs/svelte'; -import tailwindcss from '@tailwindcss/vite'; -import mermaid from 'astro-mermaid'; +import { defineConfig } from "astro/config"; +import starlight from "@astrojs/starlight"; +import starlightLinksValidator from "starlight-links-validator"; +import starlightThemeRapide from "starlight-theme-rapide"; +import starlightSidebarTopics from "starlight-sidebar-topics"; +import svelte from "@astrojs/svelte"; +import tailwindcss from "@tailwindcss/vite"; +import mermaid from "astro-mermaid"; -import { posthogCode } from './posthog.mjs'; +import { posthogCode } from "./posthog.mjs"; const isProd = import.meta.env.PROD; @@ -15,18 +15,18 @@ const isProd = import.meta.env.PROD; let head = [ // OG image { - tag: 'meta', + tag: "meta", attrs: { - property: 'og:image', - content: 'https://docs.endor.dev/og.webp' - } + property: "og:image", + content: "https://docs.endor.dev/og.webp", + }, }, ]; if (isProd) { head.push({ - tag: 'script', - content: posthogCode + tag: "script", + content: posthogCode, }); } @@ -34,181 +34,195 @@ if (isProd) { export default defineConfig({ redirects: { // MCP redirects - '/mcp/overview': { + "/mcp/overview": { status: 302, - destination: '/cli/mcp/overview', + destination: "/cli/mcp/overview", }, - '/mcp/claude-code': { + "/mcp/claude-code": { status: 302, - destination: '/cli/mcp/claude-code', + destination: "/cli/mcp/claude-code", }, - '/mcp/cursor': { + "/mcp/cursor": { status: 302, - destination: '/cli/mcp/cursor', + destination: "/cli/mcp/cursor", }, - '/mcp/goose': { + "/mcp/goose": { status: 302, - destination: '/cli/mcp/goose', + destination: "/cli/mcp/goose", }, - '/mcp/vscode': { + "/mcp/vscode": { status: 302, - destination: '/cli/mcp/vscode', + destination: "/cli/mcp/vscode", }, - '/mcp/windsurf': { + "/mcp/windsurf": { status: 302, - destination: '/cli/mcp/windsurf', + destination: "/cli/mcp/windsurf", }, // Rover redirects - '/rover/overview': { + "/rover/overview": { status: 301, - destination: '/rover/intro/overview', + destination: "/rover/intro/overview", }, - '/rover/quickstart': { + "/rover/quickstart": { status: 301, - destination: '/rover/intro/quickstart', + destination: "/rover/intro/quickstart", }, - '/rover/common-workflows': { + "/rover/common-workflows": { status: 301, - destination: '/rover/intro/quickstart', + destination: "/rover/intro/quickstart", }, - '/rover/vscode-extension': { + "/rover/vscode-extension": { status: 301, - destination: '/rover/intro/vscode-extension', + destination: "/rover/intro/vscode-extension", }, - '/rover/command-reference': { + "/rover/command-reference": { status: 301, - destination: '/rover/reference/cli-reference/', + destination: "/rover/reference/cli-reference/", }, - '/rover/intro/configuration': { + "/rover/intro/configuration": { status: 301, - destination: '/rover/configuration/project-configuration', + destination: "/rover/config/project-config", }, }, integrations: [ // @see https://github.com/joesaby/astro-mermaid?tab=readme-ov-file#integration-order-important mermaid({ - theme: 'forest', - autoTheme: true + theme: "forest", + autoTheme: true, }), starlight({ - title: 'Endor Documentation', + title: "Endor Documentation", plugins: [ starlightLinksValidator(), starlightThemeRapide(), starlightSidebarTopics([ { - label: 'Rover', - link: '/rover/intro/overview', - icon: 'seti:bicep', + label: "Rover", + link: "/rover/intro/overview", + icon: "seti:bicep", items: [ { - label: 'Introduction', - autogenerate: { directory: 'rover/intro' }, + label: "Introduction", + autogenerate: { directory: "rover/intro" }, }, { - label: 'Key Concepts', - autogenerate: { directory: 'rover/concepts' }, + label: "Key Concepts", + autogenerate: { directory: "rover/concepts" }, }, { - label: 'Configuration', - autogenerate: { directory: 'rover/configuration' }, + label: "Configuration", + autogenerate: { directory: "rover/config" }, }, { - label: 'Guides', - autogenerate: { directory: 'rover/guides' }, + label: "Guides", + autogenerate: { directory: "rover/guides" }, }, { - label: 'Reference', - autogenerate: { directory: 'rover/reference' }, + label: "Reference", + autogenerate: { directory: "rover/reference" }, }, { - label: 'Troubleshooting', - autogenerate: { directory: 'rover/troubleshooting' }, - } + label: "Troubleshooting", + autogenerate: { directory: "rover/troubleshooting" }, + }, ], }, { - label: 'Endor CLI', - link: '/cli/overview', - icon: 'forward-slash', + label: "Endor CLI", + link: "/cli/overview", + icon: "forward-slash", items: [ { - label: 'CLI', + label: "CLI", items: [ { - label: 'Overview', - link: '/cli/overview', + label: "Overview", + link: "/cli/overview", }, { - label: 'Setup', - link: '/cli/setup', + label: "Setup", + link: "/cli/setup", }, { - label: 'MCP', - autogenerate: { directory: 'cli/mcp' } + label: "MCP", + autogenerate: { directory: "cli/mcp" }, }, { - label: 'Networking', - link: '/cli/networking', + label: "Networking", + link: "/cli/networking", }, { - label: 'Volumes', - link: '/cli/volumes', + label: "Volumes", + link: "/cli/volumes", }, { - label: 'Commands', - link: '/cli/commands', + label: "Commands", + link: "/cli/commands", }, { - label: 'Open a Shell', - link: '/cli/shell', + label: "Open a Shell", + link: "/cli/shell", }, { - label: 'Services', - autogenerate: { directory: 'cli/services' }, - } + label: "Services", + autogenerate: { directory: "cli/services" }, + }, ], - } + }, ], }, { - label: 'Endor Web', - link: '/faq/', - icon: 'seti:html', + label: "Endor Web", + link: "/faq/", + icon: "seti:html", items: [ { - label: 'FAQ', - autogenerate: { directory: 'faq' }, + label: "FAQ", + autogenerate: { directory: "faq" }, }, { - label: 'Reference', - autogenerate: { directory: 'reference' }, + label: "Reference", + autogenerate: { directory: "reference" }, }, { - label: 'Guides', - autogenerate: { directory: 'guides' }, + label: "Guides", + autogenerate: { directory: "guides" }, }, ], }, ]), ], head, - customCss: [ - './src/styles/global.css' - ], + customCss: ["./src/styles/global.css"], logo: { - dark: './src/assets/logo-text-dark.png', - light: './src/assets/logo-text.png', - alt: 'Endor Logo', + dark: "./src/assets/logo-text-dark.png", + light: "./src/assets/logo-text.png", + alt: "Endor Logo", replacesTitle: true, }, social: [ - { icon: 'github', label: 'GitHub', href: 'https://github.com/endorhq' }, - { icon: 'mastodon', label: 'Mastodon', href: 'https://mastodon.social/@endorhq' }, - { icon: 'twitter', label: 'X', href: 'https://x.com/endorhq' }, - { icon: 'blueSky', label: 'BlueSky', href: 'https://bsky.app/profile/endorhq.bsky.social' }, - { icon: 'youtube', label: 'YouTube', href: 'https://www.youtube.com/@endorhq' }, - { icon: 'linkedin', label: 'LinkedIn', href: 'https://www.linkedin.com/company/endorhq' }, + { icon: "github", label: "GitHub", href: "https://github.com/endorhq" }, + { + icon: "mastodon", + label: "Mastodon", + href: "https://mastodon.social/@endorhq", + }, + { icon: "twitter", label: "X", href: "https://x.com/endorhq" }, + { + icon: "blueSky", + label: "BlueSky", + href: "https://bsky.app/profile/endorhq.bsky.social", + }, + { + icon: "youtube", + label: "YouTube", + href: "https://www.youtube.com/@endorhq", + }, + { + icon: "linkedin", + label: "LinkedIn", + href: "https://www.linkedin.com/company/endorhq", + }, ], }), svelte(), @@ -217,4 +231,4 @@ export default defineConfig({ vite: { plugins: [tailwindcss()], }, -}); \ No newline at end of file +}); diff --git a/src/content/docs/rover/concepts/sandbox.mdx b/src/content/docs/rover/concepts/sandbox.mdx index bffd2f1..301342a 100644 --- a/src/content/docs/rover/concepts/sandbox.mdx +++ b/src/content/docs/rover/concepts/sandbox.mdx @@ -22,7 +22,7 @@ Currently, sandboxes are implemented using containers. This ensures that each ta When you create a new task with `rover task`, Rover sets up a sandbox for it. This involves: 1. **Creating a [workspace](/rover/concepts/workspace)**, which has copy of your project files -2. **Load the user configuration to set up the sandbox environment**. This includes MCP servers, environment variables, and any [other settings defined in the configuration](/rover/intro/configuration) +2. **Load the user configuration to set up the sandbox environment**. This includes MCP servers, environment variables, and any [other settings defined in the configuration](/rover/config/project-config) 2. **Defines an entrypoint file to initialize the sandbox environment**. This file includes setup steps like installing dependencies and starting MCP servers 3. **Spinning up a containerized environment** using Docker or Podman container runtimes 4. **Running the coding agent inside the sandbox**, allowing it to execute commands and make changes in isolation @@ -117,4 +117,4 @@ The sandbox includes the [`package-manager-mcp` server](https://github.com/endor - \ No newline at end of file + diff --git a/src/content/docs/rover/configuration/hooks.mdx b/src/content/docs/rover/config/hooks.mdx similarity index 93% rename from src/content/docs/rover/configuration/hooks.mdx rename to src/content/docs/rover/config/hooks.mdx index 76fb57a..afbee0e 100644 --- a/src/content/docs/rover/configuration/hooks.mdx +++ b/src/content/docs/rover/config/hooks.mdx @@ -154,6 +154,6 @@ Chain multiple commands for a single hook: ## Next Steps - - + + diff --git a/src/content/docs/rover/configuration/project-configuration.mdx b/src/content/docs/rover/config/project-config.mdx similarity index 92% rename from src/content/docs/rover/configuration/project-configuration.mdx rename to src/content/docs/rover/config/project-config.mdx index e8892fe..0c1e2de 100644 --- a/src/content/docs/rover/configuration/project-configuration.mdx +++ b/src/content/docs/rover/config/project-config.mdx @@ -29,8 +29,8 @@ You can create a `rover.json` manually or run `rover init` to generate one with | `attribution` | Whether Rover adds itself as co-author on AI-assisted commits | | `envs` | Custom environment variables passed to containerized agents | | `envsFile` | Path to a dotenv file with environment variables | -| `hooks` | Commands to run at task lifecycle events ([see Hooks](/rover/configuration/hooks)) | -| `sandbox` | Customize the container environment ([see Sandbox Configuration](/rover/configuration/sandbox-configuration)) | +| `hooks` | Commands to run at task lifecycle events ([see Hooks](/rover/config/hooks)) | +| `sandbox` | Customize the container environment ([see Sandbox Configuration](/rover/config/sandbox-config)) | | `excludePatterns` | Glob patterns for files to exclude from task workspaces | ## Basic Structure @@ -225,7 +225,7 @@ For a complete list of all available configuration options, see the [Project Con ## Next Steps - - - + + + diff --git a/src/content/docs/rover/configuration/sandbox-configuration.mdx b/src/content/docs/rover/config/sandbox-config.mdx similarity index 96% rename from src/content/docs/rover/configuration/sandbox-configuration.mdx rename to src/content/docs/rover/config/sandbox-config.mdx index 71f8a12..ee25d1b 100644 --- a/src/content/docs/rover/configuration/sandbox-configuration.mdx +++ b/src/content/docs/rover/config/sandbox-config.mdx @@ -258,6 +258,6 @@ You can use all sandbox options together: - - + + diff --git a/src/content/docs/rover/configuration/user-settings.mdx b/src/content/docs/rover/config/user-settings.mdx similarity index 93% rename from src/content/docs/rover/configuration/user-settings.mdx rename to src/content/docs/rover/config/user-settings.mdx index 45826f1..19718a8 100644 --- a/src/content/docs/rover/configuration/user-settings.mdx +++ b/src/content/docs/rover/config/user-settings.mdx @@ -139,6 +139,6 @@ export ROVER_NO_TELEMETRY=true ## Next Steps - - + + diff --git a/src/content/docs/rover/guides/write-workflows.mdx b/src/content/docs/rover/guides/write-workflows.mdx index 7e7532b..2438e96 100644 --- a/src/content/docs/rover/guides/write-workflows.mdx +++ b/src/content/docs/rover/guides/write-workflows.mdx @@ -400,7 +400,7 @@ After the task completes, inspect the generated report. Check the generated report. - ```Sh + ```sh rover inspect --file=analysis_report.md 1 ``` @@ -432,4 +432,4 @@ By following this guide, you have created your own workflow. You can take existi - \ No newline at end of file + From a2435e82c4c9d1cd821878cae83105dbe8f5c0e0 Mon Sep 17 00:00:00 2001 From: Angel M Miguel Date: Tue, 27 Jan 2026 14:02:27 +0100 Subject: [PATCH 3/3] fix: update configuration links --- src/content/docs/rover/advanced/global-store.mdx | 2 +- src/content/docs/rover/concepts/project.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/rover/advanced/global-store.mdx b/src/content/docs/rover/advanced/global-store.mdx index 1c0516f..bfecd1b 100644 --- a/src/content/docs/rover/advanced/global-store.mdx +++ b/src/content/docs/rover/advanced/global-store.mdx @@ -106,7 +106,7 @@ This directory is created on first Rover CLI use, along with a default `rover.js The `rover.json` file is the central configuration file for Rover. It stores user preferences, AI agent settings, and the registry of all projects you've used with Rover. This file is auto-generated and managed by the Rover CLI, so you don't need to edit it. -If you want to customize a specific project, create a [Project Configuration](/rover/intro/configuration) file. +If you want to customize a specific project, create a [Project Configuration](/rover/config/project-config) file. ### Project Registry diff --git a/src/content/docs/rover/concepts/project.mdx b/src/content/docs/rover/concepts/project.mdx index f3138b7..f154d45 100644 --- a/src/content/docs/rover/concepts/project.mdx +++ b/src/content/docs/rover/concepts/project.mdx @@ -127,5 +127,5 @@ When you run Rover commands outside a git repository, Rover operates in **global - +