|
| 1 | +--- |
| 2 | +display_name: Copilot CLI |
| 3 | +description: GitHub Copilot CLI agent for AI-powered terminal assistance |
| 4 | +icon: ../../../../.icons/github.svg |
| 5 | +verified: false |
| 6 | +tags: [agent, copilot, ai, github, tasks] |
| 7 | +--- |
| 8 | + |
| 9 | +# Copilot |
| 10 | + |
| 11 | +Run [GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli) in your workspace for AI-powered coding assistance directly from the terminal. This module integrates with [AgentAPI](https://github.com/coder/agentapi) for task reporting in the Coder UI. |
| 12 | + |
| 13 | +```tf |
| 14 | +module "copilot" { |
| 15 | + source = "registry.coder.com/coder-labs/copilot/coder" |
| 16 | + version = "0.2.1" |
| 17 | + agent_id = coder_agent.example.id |
| 18 | + workdir = "/home/coder/projects" |
| 19 | +} |
| 20 | +``` |
| 21 | + |
| 22 | +> [!IMPORTANT] |
| 23 | +> This example assumes you have [Coder external authentication](https://coder.com/docs/admin/external-auth) 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"`. |
| 24 | +
|
| 25 | +> [!NOTE] |
| 26 | +> 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](https://coder.com/docs/admin/setup#wildcard-access-url) and set `subdomain = true`. See [here](https://coder.com/docs/tutorials/best-practices/security-best-practices#disable-path-based-apps) for more details. |
| 27 | +
|
| 28 | +## Prerequisites |
| 29 | + |
| 30 | +- **Node.js v22+** and **npm v10+** |
| 31 | +- **[Active Copilot subscription](https://docs.github.com/en/copilot/about-github-copilot/subscription-plans-for-github-copilot)** (GitHub Copilot Pro, Pro+, Business, or Enterprise) |
| 32 | +- **GitHub authentication** via one of: |
| 33 | + - [Coder external authentication](https://coder.com/docs/admin/external-auth) (recommended) |
| 34 | + - Direct token via `github_token` variable |
| 35 | + - Interactive login in Copilot |
| 36 | + |
| 37 | +## Examples |
| 38 | + |
| 39 | +### Usage with Tasks |
| 40 | + |
| 41 | +For development environments where you want Copilot to have full access to tools and automatically resume sessions: |
| 42 | + |
| 43 | +```tf |
| 44 | +data "coder_parameter" "ai_prompt" { |
| 45 | + type = "string" |
| 46 | + name = "AI Prompt" |
| 47 | + default = "" |
| 48 | + description = "Initial task prompt for Copilot." |
| 49 | + mutable = true |
| 50 | +} |
| 51 | +
|
| 52 | +module "copilot" { |
| 53 | + source = "registry.coder.com/coder-labs/copilot/coder" |
| 54 | + version = "0.2.1" |
| 55 | + agent_id = coder_agent.example.id |
| 56 | + workdir = "/home/coder/projects" |
| 57 | +
|
| 58 | + ai_prompt = data.coder_parameter.ai_prompt.value |
| 59 | + copilot_model = "claude-sonnet-4.5" |
| 60 | + allow_all_tools = true |
| 61 | + resume_session = true |
| 62 | +
|
| 63 | + trusted_directories = ["/home/coder/projects", "/tmp"] |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +### Advanced Configuration |
| 68 | + |
| 69 | +Customize tool permissions, MCP servers, and Copilot settings: |
| 70 | + |
| 71 | +```tf |
| 72 | +module "copilot" { |
| 73 | + source = "registry.coder.com/coder-labs/copilot/coder" |
| 74 | + version = "0.2.1" |
| 75 | + agent_id = coder_agent.example.id |
| 76 | + workdir = "/home/coder/projects" |
| 77 | +
|
| 78 | + # Version pinning (defaults to "0.0.334", use "latest" for newest version) |
| 79 | + copilot_version = "latest" |
| 80 | +
|
| 81 | + # Tool permissions |
| 82 | + allow_tools = ["shell(git)", "shell(npm)", "write"] |
| 83 | + trusted_directories = ["/home/coder/projects", "/tmp"] |
| 84 | +
|
| 85 | + # Custom Copilot configuration |
| 86 | + copilot_config = jsonencode({ |
| 87 | + banner = "never" |
| 88 | + theme = "dark" |
| 89 | + }) |
| 90 | +
|
| 91 | + # MCP server configuration |
| 92 | + mcp_config = jsonencode({ |
| 93 | + mcpServers = { |
| 94 | + filesystem = { |
| 95 | + command = "npx" |
| 96 | + args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/coder/projects"] |
| 97 | + description = "Provides file system access to the workspace" |
| 98 | + name = "Filesystem" |
| 99 | + timeout = 3000 |
| 100 | + type = "local" |
| 101 | + tools = ["*"] |
| 102 | + trust = true |
| 103 | + } |
| 104 | + playwright = { |
| 105 | + command = "npx" |
| 106 | + args = ["-y", "@playwright/mcp@latest", "--headless", "--isolated"] |
| 107 | + description = "Browser automation for testing and previewing changes" |
| 108 | + name = "Playwright" |
| 109 | + timeout = 5000 |
| 110 | + type = "local" |
| 111 | + tools = ["*"] |
| 112 | + trust = false |
| 113 | + } |
| 114 | + } |
| 115 | + }) |
| 116 | +
|
| 117 | + # Pre-install Node.js if needed |
| 118 | + pre_install_script = <<-EOT |
| 119 | + #!/bin/bash |
| 120 | + curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - |
| 121 | + sudo apt-get install -y nodejs |
| 122 | + EOT |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +> [!NOTE] |
| 127 | +> GitHub Copilot CLI does not automatically install MCP servers. You have two options: |
| 128 | +> |
| 129 | +> - Use `npx -y` in the MCP config (shown above) to auto-install on each run |
| 130 | +> - Pre-install MCP servers in `pre_install_script` for faster startup (e.g., `npm install -g @modelcontextprotocol/server-filesystem`) |
| 131 | +
|
| 132 | +### Direct Token Authentication |
| 133 | + |
| 134 | +Use this example when you want to provide a GitHub Personal Access Token instead of using Coder external auth: |
| 135 | + |
| 136 | +```tf |
| 137 | +variable "github_token" { |
| 138 | + type = string |
| 139 | + description = "GitHub Personal Access Token" |
| 140 | + sensitive = true |
| 141 | +} |
| 142 | +
|
| 143 | +module "copilot" { |
| 144 | + source = "registry.coder.com/coder-labs/copilot/coder" |
| 145 | + version = "0.2.1" |
| 146 | + agent_id = coder_agent.example.id |
| 147 | + workdir = "/home/coder/projects" |
| 148 | + github_token = var.github_token |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +### Standalone Mode |
| 153 | + |
| 154 | +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. |
| 155 | + |
| 156 | +```tf |
| 157 | +module "copilot" { |
| 158 | + source = "registry.coder.com/coder-labs/copilot/coder" |
| 159 | + version = "0.2.1" |
| 160 | + agent_id = coder_agent.example.id |
| 161 | + workdir = "/home/coder" |
| 162 | + report_tasks = false |
| 163 | + cli_app = true |
| 164 | +} |
| 165 | +``` |
| 166 | + |
| 167 | +## Authentication |
| 168 | + |
| 169 | +The module supports multiple authentication methods (in priority order): |
| 170 | + |
| 171 | +1. **[Coder External Auth](https://coder.com/docs/admin/external-auth) (Recommended)** - Automatic if GitHub external auth is configured in Coder |
| 172 | +2. **Direct Token** - Pass `github_token` variable (OAuth or Personal Access Token) |
| 173 | +3. **Interactive** - Copilot prompts for login via `/login` command if no auth found |
| 174 | + |
| 175 | +> [!NOTE] |
| 176 | +> OAuth tokens work best with Copilot. Personal Access Tokens may have limited functionality. |
| 177 | +
|
| 178 | +## Session Resumption |
| 179 | + |
| 180 | +By default, the module resumes the latest Copilot session when the workspace restarts. Set `resume_session = false` to always start fresh sessions. |
| 181 | + |
| 182 | +> [!NOTE] |
| 183 | +> Session resumption requires persistent storage for the home directory or workspace volume. Without persistent storage, sessions will not resume across workspace restarts. |
| 184 | +
|
| 185 | +## Troubleshooting |
| 186 | + |
| 187 | +If you encounter any issues, check the log files in the `~/.copilot-module` directory within your workspace for detailed information. |
| 188 | + |
| 189 | +```bash |
| 190 | +# Installation logs |
| 191 | +cat ~/.copilot-module/install.log |
| 192 | + |
| 193 | +# Startup logs |
| 194 | +cat ~/.copilot-module/agentapi-start.log |
| 195 | + |
| 196 | +# Pre/post install script logs |
| 197 | +cat ~/.copilot-module/pre_install.log |
| 198 | +cat ~/.copilot-module/post_install.log |
| 199 | +``` |
| 200 | + |
| 201 | +> [!NOTE] |
| 202 | +> To use tasks with Copilot, you must have an active GitHub Copilot subscription. |
| 203 | +> The `workdir` variable is required and specifies the directory where Copilot will run. |
| 204 | +
|
| 205 | +## References |
| 206 | + |
| 207 | +- [GitHub Copilot CLI Documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) |
| 208 | +- [Installing GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli) |
| 209 | +- [AgentAPI Documentation](https://github.com/coder/agentapi) |
| 210 | +- [Coder AI Agents Guide](https://coder.com/docs/tutorials/ai-agents) |
0 commit comments