Quickly sandbox your AI agent.
Python
Use self-hosted arm64 runners, env-var secrets, bicep fixes
Tyler Payne412e507aad16
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.mdindex 751ea4f..723a3f1 100644--- a/.claude/skills/release/SKILL.md+++ b/.claude/skills/release/SKILL.md@@ -12,6 +12,16 @@ For first-time setup, scaffold the workflow with `uvr workflow init` (see `referIf the project has existing CI checks (tests, linting, etc.) that aren't yet wired into the release workflow, see `references/custom-jobs.md` before your first release.+## 0. Self-hosted runner++The arm64 macOS builds require a self-hosted runner. Before dispatching, start the runner agent in a background shell:++```bash+gha-runners/local/run.sh &+```++Confirm it registers with GitHub before proceeding.+## 1. BranchYou must not be on main. If you are, create a release branch and switch to it.diff --git a/.gitignore b/.gitignoreindex bfba4bb..7712d0c 100644--- a/.gitignore+++ b/.gitignore@@ -52,3 +52,6 @@ node_modules/docs/.vitepress/dist/docs/.vitepress/cache/.DS_Store++# GHA runners — track cloud infra, ignore local runner agent+gha-runners/local/\ No newline at end of filediff --git a/packages/dev/quicksand-gh-runners/README.md b/packages/dev/quicksand-gh-runners/README.mdnew file mode 100644index 0000000..fadd973--- /dev/null+++ b/packages/dev/quicksand-gh-runners/README.md@@ -0,0 +1,51 @@+# quicksand-gh-runners++CLI to manage persistent self-hosted GitHub Actions runner VMs on Azure.++## Prerequisites++Set these environment variables:++```bash+export AZURE_SUBSCRIPTION_ID="<your-subscription-id>"+export ADO_ORG="<your-ado-org>" # only needed for feed-access+export ADO_FEED="<your-ado-feed>" # only needed for feed-access+```++## Setup++One-time provisioning creates the Azure resource group, VNet, Key Vault, and three runner VMs (Linux x64, Linux arm64, Windows x64) via a Bicep template:++```bash+quicksand-runners setup+```++This deploys Ubuntu 24.04 LTS VMs (Linux) and Windows Server 2022 (Windows), each with 256 GB Premium SSD and auto-shutdown at 9 pm EST. Linux VMs are bootstrapped with cloud-init to install Docker, Buildx, uv, and KVM support.++After provisioning, register the GitHub runner agent on each VM by following the instructions at the repo's runner settings page.++## Usage++```bash+quicksand-runners start [runner] # Start runner VMs+quicksand-runners stop [runner] # Deallocate runner VMs+quicksand-runners status [runner] # Show power state and shutdown time+quicksand-runners extend [time] # Extend auto-shutdown (e.g. "11pm")+quicksand-runners feed-access # Grant runner managed identity access to Azure Artifacts+```++The `runner` argument is optional -- omit it to target all runners. Valid values: `x64`, `arm64`, `win`.++## Architecture++| VM | Azure Size | OS | Labels |+|----|-----------|-----|--------|+| `quicksand-runner-x64` | Standard_D4s_v5 | Ubuntu 24.04 | `self-hosted, linux, x64` |+| `quicksand-runner-arm64` | Standard_D4ps_v5 | Ubuntu 24.04 (arm64) | `self-hosted, linux, arm64` |+| `quicksand-runner-win` | Standard_D4s_v5 | Windows Server 2022 | `self-hosted, windows, x64` |++All VMs are in a single VNet with inbound traffic denied by NSG. The x64 Linux runner has a system-assigned managed identity for publishing to Azure Artifacts.++## Configuration++Runner names, Azure resource group, and location are in `quicksand_gh_runners/config.py`. Sensitive values (subscription ID, ADO org/feed) are read from environment variables.diff --git a/packages/dev/quicksand-gh-runners/main.bicep b/packages/dev/quicksand-gh-runners/main.bicepindex d2d5b60..057b13c 100644--- a/packages/dev/quicksand-gh-runners/main.bicep+++ b/packages/dev/quicksand-gh-runners/main.bicep@@ -15,6 +15,9 @@ param windowsAdminPassword string@description('Object ID of the Key Vault admin user')param kvAdminObjectId string+@description('Admin username for all runner VMs')+param adminUsername string = 'runneradmin'+// Variablesvar prefix = 'quicksand'var vnetName = 'vnet-${prefix}-runners'@@ -169,13 +172,13 @@ resource linuxVms 'Microsoft.Compute/virtualMachines@2024-03-01' = [}osProfile: {computerName: take(runner.name, 15)- adminUsername: 'runneradmin'+ adminUsername: adminUsernamelinuxConfiguration: {disablePasswordAuthentication: truessh: {publicKeys: [{- path: '/home/runneradmin/.ssh/authorized_keys'+ path: '/home/${adminUsername}/.ssh/authorized_keys'keyData: sshPublicKey}]@@ -245,7 +248,7 @@ resource winVm 'Microsoft.Compute/virtualMachines@2024-03-01' = {}osProfile: {computerName: 'runner-win'- adminUsername: 'runneradmin'+ adminUsername: adminUsernameadminPassword: windowsAdminPassword}}diff --git a/packages/dev/quicksand-gh-runners/quicksand_gh_runners/cli.py b/packages/dev/quicksand-gh-runners/quicksand_gh_runners/cli.pyindex 34d2eca..730eb08 100644--- a/packages/dev/quicksand-gh-runners/quicksand_gh_runners/cli.py+++ b/packages/dev/quicksand-gh-runners/quicksand_gh_runners/cli.py@@ -14,8 +14,15 @@ from azure.mgmt.compute import ComputeManagementClientfrom . import config+# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+def _get_compute_client() -> ComputeManagementClient:+ if not config.SUBSCRIPTION_ID:+ print("Error: AZURE_SUBSCRIPTION_ID is not set")+ sys.exit(1)return ComputeManagementClient(DefaultAzureCredential(), config.SUBSCRIPTION_ID)@@ -38,22 +45,14 @@ def _vm_power_state(client: ComputeManagementClient, vm_name: str) -> str:def _get_shutdown_time(vm_name: str) -> str | None:- """Get the auto-shutdown time for a VM from DevTestLab schedules."""result = subprocess.run([- "az",- "resource",- "show",- "--resource-group",- config.RESOURCE_GROUP,- "--resource-type",- "Microsoft.DevTestLab/schedules",- "--name",- f"shutdown-computevm-{vm_name}",- "--query",- "properties.dailyRecurrence.time",- "-o",- "tsv",+ "az", "resource", "show",+ "--resource-group", config.RESOURCE_GROUP,+ "--resource-type", "Microsoft.DevTestLab/schedules",+ "--name", f"shutdown-computevm-{vm_name}",+ "--query", "properties.dailyRecurrence.time",+ "-o", "tsv",],capture_output=True,text=True,@@ -68,6 +67,33 @@ def _get_shutdown_time(vm_name: str) -> str | None:return None+def _parse_time(time_str: str) -> str:+ est = timezone(timedelta(hours=-5))++ match = re.match(r"^(\d{1,2})(am|pm)$", time_str.lower())+ if match:+ hour = int(match.group(1))+ if match.group(2) == "pm" and hour != 12:+ hour += 12+ elif match.group(2) == "am" and hour == 12:+ hour = 0+ est_dt = datetime.now(est).replace(hour=hour, minute=0, second=0)+ utc_dt = est_dt.astimezone(UTC)+ return f"{utc_dt.hour:02d}{utc_dt.minute:02d}"++ match = re.match(r"^(\d{2}):?(\d{2})$", time_str)+ if match:+ return f"{match.group(1)}{match.group(2)}"++ print(f"Cannot parse time: {time_str!r}. Use e.g. '10pm', '11pm', '22:00'")+ sys.exit(1)+++# ---------------------------------------------------------------------------+# Commands+# ---------------------------------------------------------------------------++def cmd_start(args: argparse.Namespace) -> None:runners = _resolve_runners(args.runner)client = _get_compute_client()@@ -112,29 +138,6 @@ def cmd_status(args: argparse.Namespace) -> None:print(f" {alias:6s} {vm_name:30s} error: {e}")-def _parse_time(time_str: str) -> str:- """Parse a human time like '10pm', '11pm', '22:00' into HHMM UTC."""- est = timezone(timedelta(hours=-5))-- match = re.match(r"^(\d{1,2})(am|pm)$", time_str.lower())- if match:- hour = int(match.group(1))- if match.group(2) == "pm" and hour != 12:- hour += 12- elif match.group(2) == "am" and hour == 12:- hour = 0- est_dt = datetime.now(est).replace(hour=hour, minute=0, second=0)- utc_dt = est_dt.astimezone(UTC)- return f"{utc_dt.hour:02d}{utc_dt.minute:02d}"-- match = re.match(r"^(\d{2}):?(\d{2})$", time_str)- if match:- return f"{match.group(1)}{match.group(2)}"-- print(f"Cannot parse time: {time_str!r}. Use e.g. '10pm', '11pm', '22:00'")- sys.exit(1)--def cmd_extend(args: argparse.Namespace) -> None:runners = _resolve_runners(args.runner)utc_time = _parse_time(args.time) if args.time else "0300" # default: 10pm EST@@ -142,15 +145,10 @@ def cmd_extend(args: argparse.Namespace) -> None:for alias, vm_name in runners.items():result = subprocess.run([- "az",- "vm",- "auto-shutdown",- "--resource-group",- config.RESOURCE_GROUP,- "--name",- vm_name,- "--time",- utc_time,+ "az", "vm", "auto-shutdown",+ "--resource-group", config.RESOURCE_GROUP,+ "--name", vm_name,+ "--time", utc_time,],capture_output=True,text=True,@@ -165,7 +163,10 @@ def cmd_feed_access(_args: argparse.Namespace) -> None:"""Register the x64 runner's managed identity in Azure DevOps and grant feed access."""import requests- # 1. Get the managed identity principal ID from the x64 runner VM+ if not config.ADO_ORG or not config.ADO_FEED:+ print("Error: ADO_ORG and ADO_FEED env vars must be set")+ sys.exit(1)+client = _get_compute_client()vm = client.virtual_machines.get(config.RESOURCE_GROUP, config.RUNNERS["x64"])if not vm.identity or not vm.identity.principal_id:@@ -174,23 +175,22 @@ def cmd_feed_access(_args: argparse.Namespace) -> None:principal_id = vm.identity.principal_idprint(f"Managed identity principal ID: {principal_id}")- # 2. Get a bearer token for Azure DevOpscredential = DefaultAzureCredential()token = credential.get_token(config.ADO_SCOPE).tokenheaders = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}- # 3. Register as a service principal in the Azure DevOps orgprint(f"Registering service principal in {config.ADO_ORG}...")resp = requests.post(- f"https://vssps.dev.azure.com/{config.ADO_ORG}/_apis/graph/serviceprincipals?api-version=7.1-preview.1",+ f"https://vssps.dev.azure.com/{config.ADO_ORG}/_apis/graph/serviceprincipals"+ f"?api-version=7.1-preview.1",headers=headers,json={"originId": principal_id},)if resp.status_code == 409:print(" Already registered — fetching existing descriptor...")- # List service principals and find the one matching our principal IDlist_resp = requests.get(- f"https://vssps.dev.azure.com/{config.ADO_ORG}/_apis/graph/serviceprincipals?api-version=7.1-preview.1",+ f"https://vssps.dev.azure.com/{config.ADO_ORG}/_apis/graph/serviceprincipals"+ f"?api-version=7.1-preview.1",headers=headers,)list_resp.raise_for_status()@@ -206,10 +206,10 @@ def cmd_feed_access(_args: argparse.Namespace) -> None:descriptor = resp.json()["descriptor"]print(f" Subject descriptor: {descriptor}")- # 4. Resolve subject descriptor to an identity descriptor (needed by feed permissions API)print(" Resolving identity descriptor...")resp = requests.get(- f"https://vssps.dev.azure.com/{config.ADO_ORG}/_apis/identities?subjectDescriptors={descriptor}&api-version=7.1-preview.1",+ f"https://vssps.dev.azure.com/{config.ADO_ORG}/_apis/identities"+ f"?subjectDescriptors={descriptor}&api-version=7.1-preview.1",headers=headers,)resp.raise_for_status()@@ -220,11 +220,10 @@ def cmd_feed_access(_args: argparse.Namespace) -> None:identity_descriptor = identities[0]["descriptor"]print(f" Identity descriptor: {identity_descriptor}")- # 5. Grant contributor access to the artifacts feed- # Role IDs: 1=reader, 2=collaborator, 3=contributor, 4=administratorprint(f"Granting contributor access to feed '{config.ADO_FEED}'...")resp = requests.patch(- f"https://feeds.dev.azure.com/{config.ADO_ORG}/_apis/packaging/feeds/{config.ADO_FEED}/permissions?api-version=7.1-preview.1",+ f"https://feeds.dev.azure.com/{config.ADO_ORG}/_apis/packaging/feeds/"+ f"{config.ADO_FEED}/permissions?api-version=7.1-preview.1",headers=headers,json=[{"identityDescriptor": identity_descriptor, "role": 3}],)@@ -257,15 +256,10 @@ def cmd_setup(args: argparse.Namespace) -> None:print(f"Creating resource group {config.RESOURCE_GROUP}...")subprocess.run([- "az",- "group",- "create",- "--name",- config.RESOURCE_GROUP,- "--location",- config.LOCATION,- "--output",- "none",+ "az", "group", "create",+ "--name", config.RESOURCE_GROUP,+ "--location", config.LOCATION,+ "--output", "none",],check=True,)@@ -285,20 +279,14 @@ def cmd_setup(args: argparse.Namespace) -> None:print("Deploying Bicep template...")subprocess.run([- "az",- "deployment",- "group",- "create",- "--resource-group",- config.RESOURCE_GROUP,- "--template-file",- str(bicep_path),+ "az", "deployment", "group", "create",+ "--resource-group", config.RESOURCE_GROUP,+ "--template-file", str(bicep_path),"--parameters",f"sshPublicKey={ssh_key}",f"windowsAdminPassword={win_password}",f"kvAdminObjectId={user_object_id}",- "--output",- "none",+ "--output", "none",],check=True,)@@ -312,27 +300,27 @@ def cmd_setup(args: argparse.Namespace) -> None:def main() -> int:parser = argparse.ArgumentParser(- prog="quicksand-runners",- description="Manage self-hosted GitHub Actions runner VMs",+ prog="runners",+ description="Manage self-hosted GitHub Actions runner VMs on Azure",)sub = parser.add_subparsers(dest="command", required=True)for name, fn in [("start", cmd_start), ("stop", cmd_stop), ("status", cmd_status)]:p = sub.add_parser(name)p.add_argument(- "runner",- nargs="?",- choices=list(config.RUNNERS),+ "runner", nargs="?", choices=list(config.RUNNERS),help="Runner to target (default: all)",)p.set_defaults(func=fn)p_extend = sub.add_parser("extend", help="Extend auto-shutdown time")p_extend.add_argument(- "time", nargs="?", help="New shutdown time, e.g. '10pm', '11pm' (default: 10pm EST)"+ "time", nargs="?",+ help="New shutdown time, e.g. '10pm', '11pm' (default: 10pm EST)",)p_extend.add_argument(- "runner", nargs="?", choices=list(config.RUNNERS), help="Runner to target (default: all)"+ "runner", nargs="?", choices=list(config.RUNNERS),+ help="Runner to target (default: all)",)p_extend.set_defaults(func=cmd_extend)@@ -341,7 +329,8 @@ def main() -> int:p_setup.set_defaults(func=cmd_setup)p_feed = sub.add_parser(- "feed-access", help="Grant runner managed identity access to Azure Artifacts feed"+ "feed-access",+ help="Grant runner managed identity access to Azure Artifacts feed",)p_feed.set_defaults(func=cmd_feed_access)diff --git a/packages/dev/quicksand-gh-runners/quicksand_gh_runners/config.py b/packages/dev/quicksand-gh-runners/quicksand_gh_runners/config.pyindex 6a24c5b..b61cddb 100644--- a/packages/dev/quicksand-gh-runners/quicksand_gh_runners/config.py+++ b/packages/dev/quicksand-gh-runners/quicksand_gh_runners/config.py@@ -1,6 +1,8 @@"""Azure configuration for runner VMs."""-SUBSCRIPTION_ID = "d4fe558f-6660-4fe7-99ec-ae4716b5e03f" # MSR LIT+import os++SUBSCRIPTION_ID = os.environ.get("AZURE_SUBSCRIPTION_ID", "")RESOURCE_GROUP = "rg-quicksand-runners"LOCATION = "eastus"@@ -14,6 +16,6 @@ DEFAULT_SHUTDOWN_TIME = "0200" # 9pm EST = 02:00 UTCSHUTDOWN_TIMEZONE = "UTC"# Azure DevOps-ADO_ORG = "msraif"-ADO_FEED = "packages"+ADO_ORG = os.environ.get("ADO_ORG", "")+ADO_FEED = os.environ.get("ADO_FEED", "")ADO_SCOPE = "499b84ac-1321-427f-aa17-267ca6975798/.default"diff --git a/pyproject.toml b/pyproject.tomlindex 53a5e01..a8b62a6 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -27,19 +27,19 @@ workflow_version = "0.28.1"skill_version = "0.27.1a3"[tool.uvr.matrix]-aif-agent-sandbox = [["ubuntu-latest"], ["macos-latest"]]-aif-cua-agent-sandbox = [["ubuntu-latest"], ["macos-latest"]]+aif-agent-sandbox = [["ubuntu-latest"], ["self-hosted", "macos", "arm64"]]+aif-cua-agent-sandbox = [["ubuntu-latest"], ["self-hosted", "macos", "arm64"]]quicksand = [["ubuntu-latest"]]-quicksand-alpine = [["ubuntu-latest"], ["macos-latest"]]-quicksand-alpine-desktop = [["ubuntu-latest"], ["macos-latest"]]+quicksand-alpine = [["ubuntu-latest"], ["self-hosted", "macos", "arm64"]]+quicksand-alpine-desktop = [["ubuntu-latest"], ["self-hosted", "macos", "arm64"]]quicksand-base-scaffold = [["ubuntu-latest"]]quicksand-core = [["ubuntu-latest"]]quicksand-image-tools = [["ubuntu-latest"]]quicksand-overlay-scaffold = [["ubuntu-latest"]]-quicksand-qemu = [["windows-latest"], ["ubuntu-latest"], ["macos-latest"]]+quicksand-qemu = [["windows-latest"], ["ubuntu-latest"], ["self-hosted", "macos", "arm64"], ["self-hosted", "linux", "arm64"]]quicksand-smb = [["ubuntu-latest"]]-quicksand-ubuntu = [["ubuntu-latest"], ["macos-latest"]]-quicksand-ubuntu-desktop = [["ubuntu-latest"], ["macos-latest"]]+quicksand-ubuntu = [["ubuntu-latest"], ["self-hosted", "macos", "arm64"]]+quicksand-ubuntu-desktop = [["ubuntu-latest"], ["self-hosted", "macos", "arm64"]][tool.uv.sources]quicksand = { workspace = true }diff --git a/uvr_hooks.py b/uvr_hooks.pyindex 0a341d5..a13d30d 100644--- a/uvr_hooks.py+++ b/uvr_hooks.py@@ -15,7 +15,7 @@ from uv_release_monorepo.shared.models import BuildStage, ReleasePlan# macOS because the Linux arm64 runners lack KVM for overlay builds.RETAG_RUNNERS: list[list[str]] = [["ubuntu-latest"],- ["macos-latest"],+ ["self-hosted", "macos", "arm64"],]_WHEEL_RE = re.compile(