Skip to content

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.md
index 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 `refer
If 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. Branch
You must not be on main. If you are, create a release branch and switch to it.
diff --git a/.gitignore b/.gitignore
index 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 file
diff --git a/packages/dev/quicksand-gh-runners/README.md b/packages/dev/quicksand-gh-runners/README.md
new file mode 100644
index 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.bicep
index 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'
+
// Variables
var 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: adminUsername
linuxConfiguration: {
disablePasswordAuthentication: true
ssh: {
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: adminUsername
adminPassword: windowsAdminPassword
}
}
diff --git a/packages/dev/quicksand-gh-runners/quicksand_gh_runners/cli.py b/packages/dev/quicksand-gh-runners/quicksand_gh_runners/cli.py
index 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 ComputeManagementClient
from . 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_id
print(f"Managed identity principal ID: {principal_id}")
- # 2. Get a bearer token for Azure DevOps
credential = DefaultAzureCredential()
token = credential.get_token(config.ADO_SCOPE).token
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
- # 3. Register as a service principal in the Azure DevOps org
print(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 ID
list_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=administrator
print(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.py
index 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 UTC
SHUTDOWN_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.toml
index 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.py
index 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(