registry/registry/coder-labs/modules/copilot/README.md

display_name	description	icon	verified	tags
Copilot CLI	GitHub Copilot CLI agent for AI-powered terminal assistance	../../../../.icons/github.svg	false	agent copilot ai github tasks aibridge

Copilot

Run GitHub Copilot CLI in your workspace for AI-powered coding assistance directly from the terminal. This module integrates with AgentAPI for task reporting in the Coder UI.

module "copilot" {
  source   = "registry.coder.com/coder-labs/copilot/coder"
  version  = "0.5.0"
  agent_id = coder_agent.example.id
  workdir  = "/home/coder/projects"
}

Warning

Security Notice: This module runs Copilot with --allow-all by default, which enables all permissions (equivalent to --allow-all-tools --allow-all-paths --allow-all-urls). This bypasses permission prompts and allows Copilot unrestricted access to tools, file paths, and URLs. Use this module only in trusted environments.

Important

This example assumes you have Coder external authentication configured with id = "github". If not, you can provide a direct token using the github_token variable or provide the correct external authentication id for GitHub by setting external_auth_id = "my-github".

Note

By default, this module is configured to run the embedded chat interface as a path-based application. In production, we recommend that you configure a wildcard access URL and set subdomain = true. See here for more details.

Prerequisites

• Node.js v22+ and npm v10+
• Active Copilot subscription (GitHub Copilot Pro, Pro+, Business, or Enterprise)
• GitHub authentication via one of:
  • Coder external authentication (recommended)
  • Direct token via github_token variable
  • Interactive login in Copilot

Examples

Usage with Tasks

For development environments where you want Copilot to have full access to tools and automatically resume sessions:

data "coder_parameter" "ai_prompt" {
  type        = "string"
  name        = "AI Prompt"
  default     = ""
  description = "Initial task prompt for Copilot."
  mutable     = true
}

module "copilot" {
  source   = "registry.coder.com/coder-labs/copilot/coder"
  version  = "0.5.0"
  agent_id = coder_agent.example.id
  workdir  = "/home/coder/projects"

  ai_prompt       = data.coder_parameter.ai_prompt.value
  copilot_model   = "claude-sonnet-4.5"
  allow_all_tools = true
  resume_session  = true

  trusted_directories = ["/home/coder/projects", "/tmp"]
}

Advanced Configuration

Customize tool permissions, MCP servers, and Copilot settings:

module "copilot" {
  source   = "registry.coder.com/coder-labs/copilot/coder"
  version  = "0.5.0"
  agent_id = coder_agent.example.id
  workdir  = "/home/coder/projects"

  # Version pinning (defaults to "latest", use specific version if desired)
  copilot_version = "0.2.3"

  # Tool permissions
  allow_tools         = ["shell(git)", "shell(npm)", "write"]
  trusted_directories = ["/home/coder/projects", "/tmp"]

  # Custom Copilot configuration
  copilot_config = jsonencode({
    banner = "never"
    theme  = "dark"
  })

  # MCP server configuration
  mcp_config = jsonencode({
    mcpServers = {
      filesystem = {
        command     = "npx"
        args        = ["-y", "@modelcontextprotocol/server-filesystem", "/home/coder/projects"]
        description = "Provides file system access to the workspace"
        name        = "Filesystem"
        timeout     = 3000
        type        = "local"
        tools       = ["*"]
        trust       = true
      }
      playwright = {
        command     = "npx"
        args        = ["-y", "@playwright/mcp@latest", "--headless", "--isolated"]
        description = "Browser automation for testing and previewing changes"
        name        = "Playwright"
        timeout     = 5000
        type        = "local"
        tools       = ["*"]
        trust       = false
      }
    }
  })

  # Pre-install Node.js if needed
  pre_install_script = <<-EOT
    #!/bin/bash
    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
    sudo apt-get install -y nodejs
  EOT
}

Note

GitHub Copilot CLI does not automatically install MCP servers. You have two options:

• Use npx -y in the MCP config (shown above) to auto-install on each run
• Pre-install MCP servers in pre_install_script for faster startup (e.g., npm install -g @modelcontextprotocol/server-filesystem)

Direct Token Authentication

Use this example when you want to provide a GitHub Personal Access Token instead of using Coder external auth:

variable "github_token" {
  type        = string
  description = "GitHub Personal Access Token"
  sensitive   = true
}

module "copilot" {
  source       = "registry.coder.com/coder-labs/copilot/coder"
  version      = "0.4.0"
  agent_id     = coder_agent.example.id
  workdir      = "/home/coder/projects"
  github_token = var.github_token
}

Standalone Mode

Run Copilot as a command-line tool without task reporting or web interface. This installs and configures Copilot, making it available as a CLI app in the Coder agent bar that you can launch to interact with Copilot directly from your terminal. Set report_tasks = false to disable integration with Coder Tasks.

module "copilot" {
  source       = "registry.coder.com/coder-labs/copilot/coder"
  version      = "0.4.0"
  agent_id     = coder_agent.example.id
  workdir      = "/home/coder"
  report_tasks = false
  cli_app      = true
}

Usage with AI Bridge Proxy

AI Bridge Proxy routes Copilot traffic through AI Bridge for centralized LLM management and governance. The proxy environment variables are scoped to the Copilot process only and do not affect other workspace traffic.

module "aibridge-proxy" {
  source    = "registry.coder.com/coder/aibridge-proxy/coder"
  version   = "1.0.0"
  agent_id  = coder_agent.main.id
  proxy_url = "https://aiproxy.example.com"
}

module "copilot" {
  source                   = "registry.coder.com/coder-labs/copilot/coder"
  version                  = "0.4.0"
  agent_id                 = coder_agent.main.id
  workdir                  = "/home/coder/projects"
  enable_aibridge_proxy    = true
  aibridge_proxy_auth_url  = module.aibridge-proxy.proxy_auth_url
  aibridge_proxy_cert_path = module.aibridge-proxy.cert_path
}

Note

AI Bridge Proxy is a Premium Coder feature that requires AI Governance Add-On. See the AI Bridge Proxy setup guide for details on configuring the proxy on your Coder deployment. GitHub authentication is still required for Copilot as the proxy authenticates with AI Bridge using the Coder session token, but does not replace GitHub authentication.

Important

When using AI Bridge Proxy, enable startup coordination by setting CODER_AGENT_SOCKET_SERVER_ENABLED=true in the workspace container environment. This ensures the Copilot module waits for the aibridge-proxy module to complete before starting. Without it, the Copilot start script may fail if the AI Bridge Proxy setup has not completed in time.

Authentication

The module supports multiple authentication methods (in priority order):

1. Coder External Auth (Recommended) - Automatic if GitHub external auth is configured in Coder
2. Direct Token - Pass github_token variable (OAuth or Personal Access Token)
3. Interactive - Copilot prompts for login via /login command if no auth found

Note

OAuth tokens work best with Copilot. Personal Access Tokens may have limited functionality.

Session Resumption

By default, the module resumes the latest Copilot session when the workspace restarts. Set resume_session = false to always start fresh sessions.

Note

Session resumption requires persistent storage for the home directory or workspace volume. Without persistent storage, sessions will not resume across workspace restarts.

State Persistence

AgentAPI can save and restore its conversation state to disk across workspace restarts. This complements resume_session (which resumes the Copilot CLI session) by also preserving the AgentAPI-level context. Enabled by default, requires agentapi >= v0.12.0 (older versions skip it with a warning).

To disable:

module "copilot" {
  # ... other config
  enable_state_persistence = false
}

Troubleshooting

If you encounter any issues, check the log files in the ~/.copilot-module directory within your workspace for detailed information.

# Installation logs
cat ~/.copilot-module/install.log

# Startup logs
cat ~/.copilot-module/agentapi-start.log

# Pre/post install script logs
cat ~/.copilot-module/pre_install.log
cat ~/.copilot-module/post_install.log

Note

To use tasks with Copilot, you must have an active GitHub Copilot subscription. The workdir variable is required and specifies the directory where Copilot will run.

References

• GitHub Copilot CLI Documentation
• Installing GitHub Copilot CLI
• AgentAPI Documentation
• Coder AI Agents Guide