AgentKnight

AgentKnight PC Agent connects local GitHub Copilot sessions to an AgentKnight Relay Server.

Run

Node.js 20.19.0 or newer and an authenticated GitHub Copilot CLI are required.

npx agentknight --env C:\path\to\agentknight.env

Or install it globally:

npm install --global agentknight
agentknight --env C:\path\to\agentknight.env

Without --env, AgentKnight reads .env from the current directory.

Configuration

RELAY_URL=https://your-relay-host
RELAY_TOKEN=replace-with-your-relay-token
USER_ID=admin
AGENTKNIGHT_MACHINE_NAME=optional-custom-pc-name
COPILOT_REMOTE_HOME=C:\optional\isolated\instance-data
SESSION_REFRESH_INTERVAL_MS=30000
HEARTBEAT_INTERVAL_MS=15000
LOG_LEVEL=info
SHOW_PAIRING_QR=true
PAIRING_PAGE_ENABLED=true
PAIRING_PAGE_PORT=17888

RELAY_URL is used for HTTP APIs and Socket.IO, so an https:// URL enables HTTPS and WSS for the entire PC Agent connection. Use a distinct COPILOT_REMOTE_HOME for each concurrently running instance so each one has a unique machine identity. AGENTKNIGHT_MACHINE_NAME controls the PC name shown to mobile clients, and PAIRING_PAGE_PORT allows concurrent instances to avoid the default 17888 port.

Relays with a certificate issued by a publicly trusted CA work without extra configuration. For a private or self-signed Relay CA on Windows, keep the public CA certificate at a stable local path, such as $env:OneDrive\AgentKnight\certificates\agentknight-ca.crt, and configure it before starting Node:

$caPath = "$env:OneDrive\AgentKnight\certificates\agentknight-ca.crt"
[Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", $caPath, "User")
$env:NODE_EXTRA_CA_CERTS = $caPath
npx agentknight --env C:\path\to\agentknight.env

Restart existing terminals after setting the user environment variable. Mark the OneDrive certificate Always keep on this device on every PC. Node reads NODE_EXTRA_CA_CERTS only when the process starts, so do not put it only in the AgentKnight --env file. The file must contain PEM-encoded public CA certificates only, never a private key.

Repository checkouts also include Windows Scheduled Task and macOS LaunchAgent installers under client/pc/scripts. Pass the CA path when installing the service so every background restart sets NODE_EXTRA_CA_CERTS before Node starts. On Windows, build the path from $env:OneDrive rather than hard-coding a user-specific absolute path.

Keep RELAY_TOKEN in the environment file. Do not pass it as a command-line argument or commit it to source control.

See the AgentKnight repository for Relay Server and Android client setup.