GitHub Copilot Home Assistant Integration

Integration to bring GitHub Copilot AI capabilities to Home Assistant using the GitHub Copilot SDK.

This integration provides a conversation agent powered by the GitHub Copilot SDK and Copilot CLI, enabling voice assistants and AI-powered tasks similar to OpenAI, Claude, and Gemini integrations.

Features

🤖 Conversation Agent - Use GitHub Copilot as an AI conversation agent
🎤 Voice Assistant Support - Works with Home Assistant's voice pipeline
🔧 Configurable Models - Default to auto, or select an available model through the integration's options
💬 Context Preservation - Maintains conversation history within sessions via the SDK
🐳 Add-on Support - Run the Copilot CLI as a Home Assistant add-on instead of installing it locally
🧰 MCP Tools - Connect to Home Assistant's built-in MCP server or other explicitly authorized MCP servers

Installation

Requires Home Assistant 2025.2.4 or later. Use a current stable Home Assistant release for the built-in MCP server setup below.

HACS (Recommended)

Open HACS in Home Assistant
Go to "Integrations"
Click the "+" button
Search for "GitHub Copilot"
Click "Install"
Restart Home Assistant

Manual Installation

Copy the custom_components/github_copilot directory to your Home Assistant custom_components directory
Restart Home Assistant

GitHub Copilot Bridge Add-on (Recommended for Home Assistant OS)

The GitHub Copilot Bridge add-on runs the CLI in a dedicated container that the integration connects to over the internal network. Bridge mode needs no CLI binary or runtime download inside Home Assistant Core.

Current Version: v3.12.2 (Copilot CLI v1.0.83)

Key Features:

🐳 Containerized Copilot CLI server running on port 8000 (internal network only)
🔄 Automatic retry mechanism with up to 5 restart attempts on failures
🔐 Token-based authentication via environment variables (no interactive prompts)
🏗️ Multi-architecture support for amd64 and aarch64 systems
✅ SHA256 checksum verification for CLI binary integrity
🚀 Auto-start on boot with configurable GitHub token
🛡️ Clear authentication status without model requests during bridge startup
🎯 Feature detection for CLI flags to support multiple Copilot CLI versions
🧰 Custom MCP support via integration settings or add-on options for other clients

Installing the Add-on

In Home Assistant, go to Settings → Add-ons → Add-on Store
Click the ⋮ menu (top-right) and choose Repositories
Add this repository URL: https://github.com/tserra30/Github-Copilot-SDK-integration
Find GitHub Copilot Bridge in the store and click Install
Go to the add-on's Configuration tab and set your GitHub fine-grained personal access token:
```
github_token: "github_pat_REPLACE_WITH_YOUR_TOKEN"
mcp_config: ""
```
Start the add-on
Check the Log tab to confirm it started successfully

For this integration, put MCP configuration in the integration's MCP field, even when using the bridge. Add-on mcp_config alone does not authorize tools for this integration. See MCP configuration.

The add-on's optional mcp_config remains available for other bridge clients. It accepts an inline JSON object containing mcpServers or a JSON file path readable inside the add-on container, and is passed to the CLI via --additional-mcp-config. Leave it empty if you only use the integration's MCP configuration.

Finding the Add-on Hostname

The integration needs the URL of the running add-on. Find its hostname in the add-on's Info tab and enter:

http://<hostname>:8000

For example: http://a1b2c3d4-github-copilot-bridge:8000

Note: Home Assistant generates the hostname from the add-on slug by replacing all underscores (_) with hyphens (-). Always use hyphens in the hostname — using the raw slug with underscores will cause DNS resolution to fail.

Configuration

Setup via UI

Go to Settings → Devices & Services
Click Add Integration
Search for GitHub Copilot
Fill in the configuration:
- GitHub Token – Your GitHub fine-grained personal access token with Copilot permissions (optional when using the bridge)
- Model – Leave at auto (recommended for new installations), or enter a supported model ID. Setup also accepts custom IDs.
- Copilot CLI URL (add-on) (optional) – URL of the bridge (e.g. http://a1b2c3d4-github-copilot-bridge:8000). Leave empty for local mode; the SDK can download its matching CLI runtime automatically.
- MCP configuration (optional) – Inline JSON containing mcpServers, or a JSON file path readable by Home Assistant Core. See MCP configuration.

After setup, adjust settings through Settings → Devices & Services → GitHub Copilot → Configure. Response timeout defaults to 120 seconds (range: 10–600 seconds); increase it for reasoning-heavy models or high-latency connections.

Upgrading an existing installation? Saved model selections are preserved, not silently replaced with auto. Open Configure to fetch the runtime's available model IDs and select a supported model. An older saved ID can become unavailable even if it worked before the SDK/CLI upgrade.

Tip for Home Assistant OS users: Install the bridge and enter its URL in the "Copilot CLI URL" field. No manual CLI installation in the Core container is needed.

Note: With a CLI URL, the integration does not pass a GitHub token to the SDK. Configure GitHub authentication in the bridge itself.

GitHub Token & Authentication

Ensure your GitHub account has active Copilot access, subject to your plan and organization policies.
Create a fine-grained personal access token at GitHub token settings.
Grant Account permissions → Copilot Requests → Read and write. Repository permissions are not required for this integration.
For bridge mode, put the token in the add-on's github_token field. The integration's GitHub Token field is optional and is not passed to the SDK.
For local mode, put the token in the integration's GitHub Token field (required).

Classic PATs (ghp_...) are not supported by the current SDK authentication guidance. Do not look for a classic copilot scope or switch to a classic PAT to fix authentication.

Keep tokens private and rotate them when needed. Update a rotated token where it is used: in the bridge configuration for remote mode, or in the integration for local mode. The Home Assistant token used for MCP below is a different credential.

MCP Configuration

Enter MCP settings in the GitHub Copilot integration's MCP configuration field, during setup or through Configure. This field accepts:

Inline JSON with a top-level mcpServers object, as shown below.
A JSON file path, such as /config/copilot/mcp.json or @/config/copilot/mcp.json. The file must be readable by Home Assistant Core, even in bridge mode; file loading runs off the event loop.

MCP configuration is validated during both setup and options changes. Files are loaded off the event loop; invalid JSON, unreadable files, and invalid server definitions produce configuration errors rather than being silently accepted or disabling MCP. Remote server definitions use type: "http" or type: "sse", a url, and a tools list; optional headers provide authentication. Every server, including local/stdio servers, requires an explicit tools list. Use tools: [] to disable its tools, an explicit list of that server's tool names for narrower access, or tools: ["*"] to authorize all its current and future tools. A wildcard is appropriate only for a trusted server.

Upgrading an older MCP configuration? A missing tools field is now a validation error, not implicit approval. Add the intended list to every server in the integration's MCP field or its referenced JSON file; no wildcard is silently inserted. Legacy transport: "streamable-http" and local working-directory cwd aliases remain supported. Local cwd input is normalized to the Python SDK's working_directory field; the SDK converts it back to cwd for the CLI.

Configured tool allowlists are authorization, not just discovery: allowed MCP tool calls can execute without an interactive approval prompt. Only authorize servers and tools you trust. Built-in CLI tools are disabled, and unknown or unconfigured MCP servers/tools are denied. Add-on mcp_config alone does not grant this authorization.

Assist's control capability is enabled only when the validated configuration authorizes at least one tool. An empty mcpServers object or servers with only tools: [] leave it disabled. Configuration files are loaded when the integration starts; reload the integration after editing a file so capabilities and tool authorization update together.

Use the exact tool IDs advertised by the MCP server. For example, Home Assistant may advertise intent__HassTurnOn and homeassistant__GetLiveContext; friendly names such as HassTurnOn do not match those IDs. Do not add the CLI's extra server-name prefix to the tools list.

Home Assistant's Built-in MCP Server

No external MCP server or proxy is needed:

Use a current stable Home Assistant release with the Model Context Protocol Server integration. The older 2024 development baseline does not include it.
Go to Settings → Devices & services → Add integration → Model Context Protocol Server.
Enable its Assist API, and expose a safe test entity to Assist under Settings → Voice assistants → Expose. For example, use an input boolean helper rather than a lock or other safety-sensitive device.
Create a Home Assistant long-lived access token from your Home Assistant profile's security settings. This is separate from your GitHub fine-grained PAT.
Paste the following JSON into the GitHub Copilot integration's MCP configuration field, replacing the Home Assistant token placeholder:

{
  "mcpServers": {
    "homeassistant": {
      "type": "http",
      "url": "http://homeassistant:8123/api/mcp",
      "tools": ["*"],
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_HOME_ASSISTANT_LONG_LIVED_TOKEN"
      }
    }
  }
}

http://homeassistant:8123/api/mcp is the endpoint reachable from the bridge on Home Assistant's internal network. For other deployments, use an address reachable from the Copilot CLI runtime, not just from your browser. Keep plain HTTP on a trusted internal network; use HTTPS for untrusted networks.

Ask the conversation agent to turn the exposed test helper on, then off. Verify its actual state in Home Assistant after each request; a natural-language success message alone does not prove a tool executed. Protect MCP configuration files and headers as credentials, and never include tokens in issue reports or logs.

Usage

As a Conversation Agent

Once configured, you can:

Select GitHub Copilot as a conversation agent in voice assistants
Use it in automations via the conversation.process service
Chat with it through the Home Assistant UI

Example Automation

automation:
  - alias: "Morning briefing with Copilot"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: conversation.process
        data:
          text: "Good morning! What should I know today?"
          agent_id: conversation.github_copilot

Documentation

For detailed setup and usage guidance, use this README. For contributing and development details, see CONTRIBUTING.md.

The upgrade validation environment is official Home Assistant Container 2026.9.1, with Docker Engine in Ubuntu WSL2 and the built bridge image running as an external CLI server. This container has no Supervisor: that setup cannot validate the full add-on lifecycle and is not Home Assistant OS validation. See the contribution guide for checks and how to report actual results.

Troubleshooting

"Model not available"

An older model ID, such as gpt-4.1, can be rejected by the new runtime even if a previous installation could use it. Open Settings → Devices & Services → GitHub Copilot → Configure and choose a currently offered supported model. New installations default to auto; existing saved selections are not automatically migrated.

MCP Configuration and Tool Calls

Invalid configuration: Check that the JSON contains mcpServers and valid server definitions. Prefer canonical type: "http" or "sse" for remote servers and include tools.
File not found or unreadable: A file used in the integration must exist in Home Assistant Core's filesystem. A file used only in the add-on's mcp_config must exist inside that separate add-on container.
Tools unavailable or denied: Put the server and its allowed tools in the integration's MCP field, not just the add-on options. For explicit allowlists, use the exact tool names exposed by the server.
Home Assistant MCP authentication fails: Use a Home Assistant long-lived access token with the Bearer prefix, not a GitHub PAT.
Entity cannot be controlled: Enable the MCP server's Assist API and expose the test entity to Assist. Verify its real state, not just the assistant's response.
Connection fails: Confirm the MCP URL is reachable from the CLI runtime. From the bridge, use http://homeassistant:8123/api/mcp; localhost would refer to the bridge itself.

SDK Installation

Home Assistant automatically installs upstream github-copilot-sdk==1.0.13 from PyPI using the integration manifest. Its universal py3-none-any wheel supports Home Assistant's Python environment without a bundled or patched wheel. Home Assistant Core's container uses Alpine/musl, not an older glibc.

The Python SDK is required in both modes:

Local mode (no CLI URL): When no installed or explicit CLI executable is available, the SDK automatically downloads and verifies a checksummed matching runtime. SDK 1.0.13 pins CLI 1.0.83, with musl and glibc builds for amd64/arm64. Allow outbound access for the first download and ensure its cache location is writable.
Remote bridge mode: The SDK connects to the bridge and neither needs a local CLI executable nor downloads one. Update the bridge along with the integration to keep its CLI compatible.

If an old manual CLI installation or COPILOT_CLI_PATH override is selected, update it to a compatible version or remove the stale override so the SDK can manage its runtime. Do not reinstall old patched wheels or use boot-time binary-download automations.

"Unable to connect to Copilot CLI" Error

Bridge v3.12.0 logs "listening on port 8000", but HA reports connection refused: upgrade the bridge add-on to v3.12.1. Version 3.12.0 bound the CLI to the container's loopback interface; v3.12.1 binds to 0.0.0.0:8000 on the internal network. No host port exposure or token change is needed. HACS updates the Python integration, not the separate bridge add-on.

Bridge mode:

Confirm the add-on is running and check its logs.
Check the integration's CLI URL and hostname, including hyphens rather than underscores.
Check that GitHub authentication is configured in the add-on.

Local mode:

Check Home Assistant logs for runtime download, permissions, or startup errors.
Confirm outbound connectivity and a writable SDK runtime cache.
Check for a stale manually installed CLI or COPILOT_CLI_PATH override.
Confirm the integration has a valid fine-grained GitHub PAT.

Installing a CLI only in the SSH/Terminal add-on does not make it available inside Home Assistant Core.

Authentication Errors

Check that the fine-grained GitHub PAT is not expired or revoked, has Account permissions → Copilot Requests → Read and write, and belongs to an account with Copilot access.
In bridge mode, update the add-on's github_token and restart the bridge; changing the integration token does not change remote authentication.
In local mode, update the integration token.
Check runtime logs for invalid credentials, plan restrictions, or rate limits. Respect any reported retry delay.

Bridge v3.12.2 no longer runs an LLM prompt or legacy command as an authentication probe. "GitHub token configured" means only that a token was supplied, not that GitHub accepted it. The integration checks authentication through the SDK, and its setup connection test confirms model access with a real response. Older bridge versions' "auth probe failed" warning came from an unreliable probe.

Understanding Bridge and Integration Logs

The three authentication layers are separate:

Credential	Connection
GitHub fine-grained PAT (`github_token`, supplied as `GH_TOKEN`)	Bridge to GitHub Copilot
Home Assistant long-lived token in MCP headers	MCP client to Home Assistant
Optional `COPILOT_CONNECTION_TOKEN`	SDK client to bridge TCP endpoint

The CLI's "No COPILOT_CONNECTION_TOKEN was set" warning does not indicate a missing GitHub PAT. It means any client that can reach the bridge's TCP endpoint can connect. Port 8000 is not published to the host by default; keep the endpoint on a trusted internal network. The integration does not currently expose a connection-token option: setting it only on the bridge would prevent the integration from connecting, because both sides must use the same separate secret. The warning is intentionally not suppressed.

The bridge's Log tab shows startup and CLI process output, not every integration connection or request. Home Assistant's logs under custom_components.github_copilot contain INFO-level connection, SDK-reported authentication, session start/close, and client-stop messages in integration v1.0.8. A setup test logs success only after receiving a model response and cleaning up its session. Requested model IDs, including auto, are configuration metadata, not proof of the model chosen by the runtime.

To see these messages, merge this into your existing configuration.yaml logger settings and restart Home Assistant:

logger:
  logs:
    custom_components.github_copilot: info

Use debug temporarily for request-start/response-received milestones. These integration messages omit prompts, responses, authorization headers, full connection URLs, and raw SDK exception payloads. Upstream SDK/CLI diagnostics are separate; review and redact logs before sharing them. Connection logs are emitted when a connection opens, not for every prompt using that connection.

Slow Responses or Timeout Errors

Increase the response timeout: Go to Settings → Devices & Services → GitHub Copilot → Configure (default 120 seconds, up to 600 seconds).
Try a faster model and check network latency.
Check MCP server availability if a response requires tools.
Reduce concurrent requests.

For more help, open an issue. Redact tokens and authorization headers from diagnostic output.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

This project is licensed under the GNU GPLv3 - see the LICENSE file for details. Some source code was originally licensed under the MIT license.

GitHub Copilot SDK License

This integration depends on the GitHub Copilot SDK, which is licensed under the MIT License:

MIT License

Copyright GitHub, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Acknowledgments

Built on Home Assistant's conversation framework
Based on the integration blueprint by @ludeeus

Note: This integration is not officially affiliated with GitHub or Microsoft.

Original MIT license from integration blueprint by @ludeeus

MIT License

Copyright (c) 2019 - 2025  Joakim Sørensen @ludeeus

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Name		Name	Last commit message	Last commit date
.github		.github
addon		addon
config		config
custom_components/github_copilot		custom_components/github_copilot
scripts		scripts
tests		tests
.devcontainer.json		.devcontainer.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.ruff.toml		.ruff.toml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
hacs.json		hacs.json
icon.png		icon.png
icon@2x.png		icon@2x.png
index.html		index.html
logo.png		logo.png
logo@2x.png		logo@2x.png
repository.yaml		repository.yaml
requirements.txt		requirements.txt
robots.txt		robots.txt
sitemap.xml		sitemap.xml

Navigation Menu

Repository navigation

About

Repository files navigation

GitHub Copilot Home Assistant Integration

Features

Installation

HACS (Recommended)

Manual Installation

GitHub Copilot Bridge Add-on (Recommended for Home Assistant OS)

Installing the Add-on

Finding the Add-on Hostname

Configuration

Setup via UI

GitHub Token & Authentication

MCP Configuration

Home Assistant's Built-in MCP Server

Usage

As a Conversation Agent

Example Automation

Documentation

Troubleshooting

"Model not available"

MCP Configuration and Tool Calls

SDK Installation

"Unable to connect to Copilot CLI" Error

Authentication Errors

Understanding Bridge and Integration Logs

Slow Responses or Timeout Errors

Contributing

License

GitHub Copilot SDK License

Acknowledgments

Original MIT license from integration blueprint by @ludeeus

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

GitHub Copilot Home Assistant Integration

Features

Installation

HACS (Recommended)

Manual Installation

GitHub Copilot Bridge Add-on (Recommended for Home Assistant OS)

Installing the Add-on

Finding the Add-on Hostname

Configuration

Setup via UI

GitHub Token & Authentication

MCP Configuration

Home Assistant's Built-in MCP Server

Usage

As a Conversation Agent

Example Automation

Documentation

Troubleshooting

"Model not available"

MCP Configuration and Tool Calls

SDK Installation

"Unable to connect to Copilot CLI" Error

Authentication Errors

Understanding Bridge and Integration Logs

Slow Responses or Timeout Errors

Contributing

License

GitHub Copilot SDK License

Acknowledgments

Original MIT license from integration blueprint by @ludeeus

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages