feat(agent): Windows + macOS agents — host/shell executor + OS-aware scheduling
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 7
- Forks
- 3
- Avg merge
- 2h 12m
- Merged PRs (30d)
- 30
Description
Goal
Support Windows and macOS agents (like Woodpecker's local backend), so jobs can target those platforms (Xcode/iOS on mac, .NET/MSVC on Windows). This issue captures the architecture assessment for later validation + scoping — not committing to an implementation yet.
Where we are today
We already have the two bones Woodpecker uses (host executor + platform routing), but both are incomplete:
- The Shell engine is the host executor — but it's Linux/Unix-only:
sh -c(agent/internal/engine/shell.go:85) and Unix process-group kill (syscall.SysProcAttr{Setpgid}+syscall.Kill(-pid, SIGKILL),shell.go:93-104). - The agent already advertises
os/archat registration (agent/internal/rpc/client.go:263-264,RegisterRequest.os/arch) — but the scheduler ignores it:SessionStorekeeps only tags/capacity/engine andFindIdleWithTagsmatches tags only (server/internal/grpcsrv/sessions.go). No job/profile carries an OS selector. - Plugins are 100% OCI Linux images (
plugins/, ~58 Dockerfiles); the Shell engine explicitly rejects plugin tasks (shell.go:72-81). - The agent is built/shipped Linux-only (
agent/DockerfileAlpine;release.ymlimage matrix; noGOOS/GOARCHcross-compile).
Three distances
- macOS shell agent — CLOSE. The Shell engine is POSIX, so it already runs on macOS; the agent is pure Go (
CGO_ENABLED=0) → cross-compiles todarwin/*trivially. Missing: OS/arch routing in the scheduler, a darwin binary in CI, and anos.TempDir()workspace default. Caveat: shell steps only — no container plugins on bare macOS (which matches how mac CI agents are used). - Windows shell agent — MEDIUM. Same routing + packaging, plus a Windows backend for the Shell engine:
cmd.exe/PowerShell instead ofsh -c, and a Windows process-tree kill (the currentsyscall.Kill(-pid,…)won't even compile on Windows). Isolated platform module. - Full plugin parity — FAR / likely out of scope. Would need Windows-container variants of every plugin (huge maintenance); bare macOS can't run containers at all. Pragmatic target is shell-step agents.
Proposed smallest-first path
- Scheduler routes by
os/arch— store them on the session (data already arrives) and AND-match them alongside tags; add anos:/platform:selector to the job spec or runner profile (reuses the v0.14.0 runner-profile scheduling / node_selector machinery). Server-only; no agent change — and this alone makes a macOS agent usable since its Shell engine already runs. - Cross-compile + publish
darwin/arm64(+windows/amd64) agent binaries. - macOS agent ships on 1+2 (shell-only; document the no-plugins caveat).
- Windows backend for the Shell engine (
cmd/PowerShell + Job-Object process kill). - (Punt) Windows/macOS plugin images.
Open questions for validation
- Distribution: standalone binary + service install, or also a container path?
- Routing UX: OS as a first-class
platform:on the job, vs. just conventional tags (os:windows)? - Do we want a
local/shellagent posture documented as first-class (security implications: host execution, no container isolation)?
Assessment done during the v0.49.0 cycle. No code yet — for discussion.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading agent/internal/engine/shell.go, agent/internal/rpc/client.go, and server/internal/grpcsrv/sessions.go, then inspect release.yml and the runner-profile scheduling machinery. The work is ready for implementation only after the routing UX, distribution model, local-agent posture, and shell-only plugin scope are decided; completion would cover the agreed platform-routing and packaging steps with the stated Windows backend or explicit scope boundary.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, go, powershell, shell
- Domain
- backend, ci-cd, devops, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100