<div align="center">

🐾 copilot-studio-claw

Give a Copilot Studio agent a machine it can actually operate.

</div>

---

In plain English

A Microsoft Copilot Studio agent is great at chatting and reasoning, but on its own it can't do much on a computer — it has no keyboard, no files, no way to run programs.

copilot-studio-claw gives your agent its own dedicated Windows computer (a throwaway cloud VM) and a safe doorway to use it. Once connected, you can ask your agent things like "set up a Node project, run the tests, and tell me what failed" — and it will actually open the machine, install what it needs, run the commands, and report back.

Think of it as handing your AI assistant the keys to a sandbox laptop in the cloud: powerful inside that laptop, and walled off from everything else.

[!WARNING] This is, quite literally, a remote Administrator command line exposed to the internet (protected by a secret key). Only ever run it on a disposable machine in a throwaway account — never on anything holding real data, passwords, or production access. See Security before you deploy.

---

Table of contents

• What you get
• How it works
• Quick start
  • 1. Deploy the machine (Azure)
  • 2. Set up the machine
  • 3. Connect Copilot Studio
  • 4. Try it
• Security
• Configuration
• The toolbox
• Architecture & docs
• Uninstall / tear down
• Contributing

---

✨ What you get

• A small set of powerful, general-purpose tools instead of a fiddly connector per task — run commands, run PowerShell, read/write files, run long jobs, and inspect the machine.
• The agent installs its own software. Need the Azure CLI, Python, or Playwright? Just ask — the agent runs winget / npm / pip itself and keeps going. There's no "add a tool" step.
• One safe front door. Everything goes through an authenticated HTTPS endpoint with a real TLS certificate — the only thing Copilot Studio needs is a URL and a key.
• Reproducible from scratch. One infrastructure script, one setup script, no secrets in the repo, everything parameterised.

---

🧭 How it works

flowchart LR
    A["🤖 Copilot Studio agent<br/>(GitHub Copilot harness)"] -->|"MCP over HTTPS<br/>secret key in a header"| B["🔒 Caddy · :443<br/>automatic TLS"]
    subgraph VM["☁️ Dedicated, disposable Windows VM"]
        B -->|"localhost:8787"| C["⚙️ claw-server<br/>(runs as a Windows service)"]
        C --> D["PowerShell · CLIs · files · jobs"]
    end

Your agent sends tool requests over HTTPS. Caddy answers on port 443 with an automatically issued Let's Encrypt certificate and forwards to claw-server, a small Node.js service that only listens on localhost. claw-server runs the request against the machine — a PowerShell script, a command, a file operation — and streams back the result. Long tasks become background jobs the agent can poll, so nothing hangs waiting.

The machine is the security boundary. Inside it, the agent is an Administrator and that's fine — it's disposable. Outside it, nothing is granted by default.

---

🚀 Quick start

You'll need: an Azure subscription (a throwaway one is ideal), the Azure CLI signed in (az login), and a Copilot Studio agent using the GitHub Copilot harness.

The whole thing is three short steps: deploy a machine → set it up → connect Copilot Studio.

1. Deploy the machine (Azure)

Clone the repo and run the deployment script. It creates a resource group, a Windows VM with a public web address, and a firewall that only opens what's needed (443 for HTTPS, 80 for the certificate check, and RDP locked to your IP).

git clone https://github.com/ogradyliam5/copilot-studio-claw
cd copilot-studio-claw

./deploy/azure/deploy-azure.ps1 `
  -DnsLabelPrefix "claw-<something-unique>" `
  -Location "eastus" `
  -RestrictRdpToMyIp

When it finishes it prints your machine's address, e.g. https://claw-something-unique.eastus.cloudapp.azure.com.

[!TIP] If you hit SkuNotAvailable, the default VM size isn't available in your region/subscription (common on trial or Dev subscriptions). Add -VmSize Standard_D2as_v7 — or run az vm list-skus -l eastus --size Standard_D2 --query "[].name" to see what's on offer — and re-run. Any 2-vCPU size is plenty.

2. Set up the machine

The deploy step builds the infrastructure; this step installs the software. Connect to the VM with Remote Desktop (address above, username clawadmin, and the password you set), open PowerShell 7 as Administrator, and run:

git clone https://github.com/ogradyliam5/copilot-studio-claw C:\claw
cd C:\claw
./deploy/azure/cloud-init/bootstrap-vm.ps1 `
  -Domain "claw-<something-unique>.eastus.cloudapp.azure.com" `
  -Profile developer

This installs the tools, builds the server, generates your secret API key, and starts claw-server + Caddy as auto-starting Windows services. It prints the API key once — copy it now. (Pick a tool profile: minimal, developer, power-platform, or full. The agent can always install more later.)

Check it's live from your own machine:

curl https://claw-<something-unique>.eastus.cloudapp.azure.com/health
# → {"status":"ok","service":"copilot-studio-claw","version":"0.1.0"}

<details> <summary><strong>Prefer to run it somewhere other than Azure?</strong></summary>

copilot-studio-claw runs on any Windows machine with a public DNS name and a valid TLS certificate. See docs/installation.md for the manual walkthrough. </details>

3. Connect Copilot Studio

In Copilot Studio, open (or create) an agent that uses the GitHub Copilot harness, then:

1. Go to the Build tab → Tools → Add → choose Model Context Protocol (MCP).
2. Fill in the form:

   Field	Value
   Server name	Claw VM
   Description	Operate a dedicated Windows VM: run commands, PowerShell, files, jobs.
   Server URL	https://<your-address>/mcp
   Authentication	API key
   Parameter type	Header
   Header name	x-api-key

3. Click Add. Copilot Studio connects to the server and lists its tools.
4. When prompted, Create a new connection and paste your API key into the x-api-key field.
5. Confirm all 14 tools appear (if they do, the handshake worked ✅), then Save.

The first time the agent uses a tool, Copilot Studio shows a one-time "Allow" consent card — approve it to let the agent call the server.

Full details and troubleshooting: docs/copilot-studio.md.

4. Try it

Open the Preview panel and ask your agent something real:

"Check what version of Windows and Node are on the machine."

"Create a folder C:\demo, write a file hello.txt in it, then read it back to me."

"Install the Azure CLI, then tell me its version."

"Clone github.com/expressjs/express, run npm install as a background job, and show me the output when it finishes."

Paste the ready-made operating instructions from examples/agent-instructions.md into your agent's Instructions so it knows to inspect first, install what it needs, use background jobs for slow work, and never echo secrets.

---

🔐 Security

copilot-studio-claw is deliberately powerful, so the trust model matters. Read this before you deploy anything real.

• The endpoint is an authenticated remote Administrator shell. Anyone with the API key can run anything on the VM. Guard the key like a production password — it's never stored in this repo.
• Use a disposable machine in a throwaway account. The VM should have no subscription-Owner rights, no Global Admin, and no production credentials or SSH keys sitting on it. Any external access it needs, you grant deliberately.
• The firewall is closed by default. Only 443 (HTTPS) and 80 (certificate issuance) are open to the world; RDP is restricted to your IP and is easy to turn off after setup.
• Secrets stay out of the repo. .env is git-ignored, logs are redacted, and the API key is generated on the machine — never committed.

Full trust-boundary model and the roadmap from API-key auth to Microsoft Entra ID: docs/security.md.

---

⚙️ Configuration

Everything is set through environment variables (see .env.example). Sensible defaults mean you usually only set API_KEY.

Variable	Default	What it does
API_KEY	(required)	The secret Copilot Studio must send. Generate with npm run new-apikey.
API_KEY_HEADER	x-api-key	Header the key is read from.
PORT	8787	Local port the server listens on (Caddy proxies to it).
HOST	127.0.0.1	Kept on loopback so it's never exposed directly.
MAX_OUTPUT_BYTES	200000	Caps tool output so responses stay within Copilot Studio's limit.
DEFAULT_TIMEOUT_SECONDS	60	Default timeout for a synchronous command.
MAX_TIMEOUT_SECONDS	600	Upper bound a single call may request.
POWERSHELL_PATH	pwsh	PowerShell 7 executable (falls back to Windows PowerShell if absent).
LOG_LEVEL	info	Log verbosity.

---

🧰 The toolbox

A small, general-purpose set on purpose — Copilot Studio limits how many tools an agent can juggle, so a few powerful ones beat dozens of narrow ones.

Tool	What it does
exec	Run a program with arguments; returns output, exit code, and duration.
powershell	Run a (multi-line) PowerShell 7 script.
fs_read · fs_write	Read or write a file (text or binary, with byte-range paging).
fs_list · fs_search	List a directory or search files/contents.
fs_op · fs_stat	Copy / move / delete / mkdir, and get file metadata.
job_start · job_status · job_output · job_cancel · job_list	Run and follow long tasks that outlast a single request.
system_info	Structured machine inspection (OS, hardware, disks, network, ports, runtimes, processes).

There is no "install software" tool — installing is just exec/powershell running winget, npm, pip, dotnet tool install, or Install-Module, the same way a person would.

---

🏗️ Architecture & docs

Doc	For
docs/architecture.md	The layering, the stateless request lifecycle, the job subsystem, and the adapter seam that lets it target other machines later.
docs/installation.md	Azure and manual (any Windows box) setup in depth.
docs/copilot-studio.md	Step-by-step connection guide + a 12-step end-to-end test.
docs/security.md	The full security model and auth roadmap.
docs/troubleshooting.md	Fixes for the common snags.
docs/development.md	Build, test, and how to add a new tool.

Built with Node.js + TypeScript, the MCP TypeScript SDK (Streamable HTTP), Caddy for TLS, WinSW for the Windows service, and Bicep for Azure.

---

🧹 Uninstall / tear down

Remove the whole Azure environment (VM, IP, network, disks) in one command:

az group delete --name "copilot-studio-claw-rg" --yes --no-wait

To just stop paying for compute while keeping the machine, deallocate it instead:

az vm deallocate --resource-group "copilot-studio-claw-rg" --name "claw-vm"

To remove only the Windows services (leaving the VM), run scripts/uninstall-service.ps1 on the VM.

---

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for setup, the PR flow, and the one golden rule for new tools (flat input schemas — the reason is explained there). Found a security issue? Please follow SECURITY.md rather than opening a public issue.

License

MIT © 2026 Liam O'Grady