Cross-platform agents, standalone server, script engines, custom roles, platform binaries #3

Merged
gsadmin merged 13 commits from dev into main 2026-08-08 02:04:50 +00:00
Owner

Cross-platform delivery and access control: the agent now runs on Linux and macOS, one self-contained binary stands up the whole server, scripts pick their engine (PS7 / 5.1 / Bash), and custom roles govern who can do what over which devices. 11 commits, all verified locally (181 tests green across shared/agent/backend, svelte-check clean, production WebUI build, live screenshot pass against a seeded stack) and CI green end-to-end including the new multi-platform packaging.

Cross-platform agent

  • Linux and macOS support via a portable net10.0 flavor: JSON config at /etc/executer/agent.json (registry seam), chmod-600 credentials under /var/lib/executer, DMI-sysfs/ioreg hardware identity, portable inventory (os-release/sysctl, /sys/block disks, DriveInfo volumes, NIC enumeration), systemd (Type=notify) / launchd service lifecycle through the same CLI verbs. Remote shell stays Windows-only for now.
  • Idempotent pwsh bootstrap on unix (Homebrew on macOS, official installer script on Linux) — convenience only, since script execution uses the embedded SDK.
  • RID-aware payload trim; unix binaries ship as executer-agent.

Standalone combined server

  • One self-contained ExecuteRServer binary serves the static-SPA WebUI, the API, a built-in /messaging/* WebSocket relay, and supervises a bundled nats-server sidecar. setup generates keys + config; service install registers a Windows service or systemd unit. Verified live from the packaged zip: SPA, /api/ready all-true, login, and a browser WebSocket through the relay.

Script engines

  • Per-script engine: PowerShell 7 (embedded SDK, in-process, all platforms — unchanged default), Windows PowerShell 5.1 (generated wrapper renders typed PowerShell literals for parameters/secrets, dot-sources the prelude, splats the payload), Bash (env-var parameters, complex values as JSON; Git Bash on Windows, WSL shim deliberately excluded). Editor selector switches Monaco language; unavailable engines fail the job with a clear message. Verified with real powershell.exe and Git Bash runs.
  • Parameter expansion now calls SessionStateProxy.InvokeCommand.ExpandString directly on the job's idle in-process runspace — no wrapper pipeline, identical semantics.
  • Bundled gallery modules: PSResourceGet 1.2.0, Archive 1.2.6, ThreadJob 2.2.0 staged next to the binary on every platform (MSI installs them; agent prepends the dir to PSModulePath, inherited by 5.1 children) — Install-PSResource works on bare endpoints with no bootstrap dance.

Custom roles (RBAC)

  • Role objects bundle ~18 grantable permissions, optionally scoped to device groups (enforced across device listing/detail, job dispatch incl. group fan-out, shell, file delivery, inventory refresh, tags), with per-role OIDC claim values mapping IdP groups onto custom roles (legacy Admin/Operator/Viewer mapping still resolves onto the seeded system roles).
  • Endpoints demand perm:{key} policies resolved through a short-TTL role cache — permission edits apply without re-login; pre-upgrade users and cookies carry over by name.
  • New Access page: local users (create, role assign, password reset) and roles (permission grid, claim values, device scope); nav hides unusable sections. Rails: system roles immutable, roles with users undeletable, the last full-access user can never be deleted or demoted.
  • End-to-end HTTP test: admin login → wildcard permissions → role admin 200; viewer session → devices 200, management 403.

CI & packaging

  • CI builds every platform binary: agent for win-x64 / linux-x64 / linux-arm64 / osx-x64 / osx-arm64 (+ MSI) and the standalone server (win-x64, linux-x64), uploaded as a binaries artifact with checksums; releases attach the full set. Also fixes the multi-TFM publish break (NETSDK1129) that reddened two runs.
  • Agent package directory is a bind mount in compose for out-of-band agent updates without a server rebuild.
  • Fresh screenshots throughout (Access page, role editor, engine selector) and README coverage for all of the above.

🤖 Generated with Claude Code

Cross-platform delivery and access control: the agent now runs on Linux and macOS, one self-contained binary stands up the whole server, scripts pick their engine (PS7 / 5.1 / Bash), and custom roles govern who can do what over which devices. 11 commits, all verified locally (181 tests green across shared/agent/backend, svelte-check clean, production WebUI build, live screenshot pass against a seeded stack) and CI green end-to-end including the new multi-platform packaging. ## Cross-platform agent - **Linux and macOS support** via a portable `net10.0` flavor: JSON config at `/etc/executer/agent.json` (registry seam), chmod-600 credentials under `/var/lib/executer`, DMI-sysfs/ioreg hardware identity, portable inventory (os-release/sysctl, /sys/block disks, DriveInfo volumes, NIC enumeration), systemd (`Type=notify`) / launchd service lifecycle through the same CLI verbs. Remote shell stays Windows-only for now. - **Idempotent pwsh bootstrap** on unix (Homebrew on macOS, official installer script on Linux) — convenience only, since script execution uses the embedded SDK. - RID-aware payload trim; unix binaries ship as `executer-agent`. ## Standalone combined server - One self-contained `ExecuteRServer` binary serves the static-SPA WebUI, the API, a built-in `/messaging/*` WebSocket relay, and supervises a bundled `nats-server` sidecar. `setup` generates keys + config; `service install` registers a Windows service or systemd unit. Verified live from the packaged zip: SPA, `/api/ready` all-true, login, and a browser WebSocket through the relay. ## Script engines - Per-script engine: **PowerShell 7** (embedded SDK, in-process, all platforms — unchanged default), **Windows PowerShell 5.1** (generated wrapper renders typed PowerShell literals for parameters/secrets, dot-sources the prelude, splats the payload), **Bash** (env-var parameters, complex values as JSON; Git Bash on Windows, WSL shim deliberately excluded). Editor selector switches Monaco language; unavailable engines fail the job with a clear message. Verified with real `powershell.exe` and Git Bash runs. - Parameter expansion now calls `SessionStateProxy.InvokeCommand.ExpandString` directly on the job's idle in-process runspace — no wrapper pipeline, identical semantics. - **Bundled gallery modules**: PSResourceGet 1.2.0, Archive 1.2.6, ThreadJob 2.2.0 staged next to the binary on every platform (MSI installs them; agent prepends the dir to `PSModulePath`, inherited by 5.1 children) — `Install-PSResource` works on bare endpoints with no bootstrap dance. ## Custom roles (RBAC) - **Role objects** bundle ~18 grantable permissions, optionally scoped to device groups (enforced across device listing/detail, job dispatch incl. group fan-out, shell, file delivery, inventory refresh, tags), with per-role **OIDC claim values** mapping IdP groups onto custom roles (legacy Admin/Operator/Viewer mapping still resolves onto the seeded system roles). - Endpoints demand `perm:{key}` policies resolved through a short-TTL role cache — permission edits apply without re-login; pre-upgrade users and cookies carry over by name. - New **Access** page: local users (create, role assign, password reset) and roles (permission grid, claim values, device scope); nav hides unusable sections. Rails: system roles immutable, roles with users undeletable, the last full-access user can never be deleted or demoted. - End-to-end HTTP test: admin login → wildcard permissions → role admin 200; viewer session → devices 200, management 403. ## CI & packaging - CI builds **every platform binary**: agent for win-x64 / linux-x64 / linux-arm64 / osx-x64 / osx-arm64 (+ MSI) and the standalone server (win-x64, linux-x64), uploaded as a `binaries` artifact with checksums; releases attach the full set. Also fixes the multi-TFM publish break (`NETSDK1129`) that reddened two runs. - Agent package directory is a **bind mount** in compose for out-of-band agent updates without a server rebuild. - Fresh screenshots throughout (Access page, role editor, engine selector) and README coverage for all of the above. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
gsadmin added 13 commits 2026-08-08 01:42:06 +00:00
/data/agent (the AGENT_PACKAGE_PATH default, checked before the baked
image copy) now maps to API/AgentPackage on the host, so dropping a new
Agent.msi/Agent.zip there ships an agent update with no backend build.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
`Package-Server.ps1` produces a self-contained single-file ExecuteRServer
per platform (win-x64/linux-x64) that embeds the WebUI as a static SPA
(ADAPTER=static build; SSR disabled — the app is fully client-driven),
relays /messaging/agent and /messaging/browser over WebSocket to a
bundled nats-server sidecar it supervises (spawned before the NATS
client connects, restarted with backoff, killed on shutdown), and runs
as a Windows service or systemd unit via `service install|uninstall`.
`setup` generates the NATS operator keys, sidecar config (relative
include paths — nats-server mangles Windows drive-letter absolutes) and
appsettings.json. Windows publishes carry the app icon.

Verified end to end from the packaged zip: setup → run → SPA served,
/api/ready shows natsConnected:true, admin login 200, and a WebSocket
to /messaging/browser receives the NATS INFO greeting through the relay.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Ignore the static WebUI build output
CI / build-test (push) Successful in 4m31s
CI / images (push) Successful in 3m8s
86c8305ca3
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent runs on linux and macOS
CI / build-test (push) Failing after 3m24s
CI / images (push) Has been skipped
32e5c690a5
The agent multi-targets net10.0-windows (full stack: WMI inventory,
ConPTY shell, DPAPI, registry, SCM service) and net10.0 for linux/macOS:

- Configuration: /etc/executer/agent.json stands in for the registry —
  the same key paths address JSON sections, so the policy > config >
  default precedence chain is unchanged (FileRegistryStore, atomic
  writes, chmod 600).
- Credentials: root-owned mode-600 file in /var/lib/executer (DPAPI has
  no unix analogue; directory is 700).
- Identity: DMI sysfs + /etc/machine-id on linux, IOPlatformUUID/serial
  via ioreg + sysctl on macOS.
- Inventory: os-release/sw_vers, /proc/cpuinfo/meminfo or sysctl,
  /sys/block disks (linux), DriveInfo volumes, NetworkInterface adapters.
- Service: systemd unit on linux, launchd daemon on macOS, behind the
  same install/remove/start/stop/initialize/status commands.
- PowerShell scripts still run IN-PROCESS via the embedded SDK engine on
  every platform; a background idempotent bootstrap additionally installs
  the standalone pwsh host on unix (official installer script / brew) and
  never blocks or fails startup. Remote shell is ConPTY-based and refuses
  cleanly off Windows.

Payload trimming is now RID-aware so unix publishes keep their natives.
Windows behavior is unchanged; linux-x64 publish verified, all 169 tests
green with Agent.Tests exercising the cross-platform flavor.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Script engines: PowerShell 7 in-process, Windows PowerShell 5.1, Bash
CI / build-test (push) Failing after 3m13s
CI / images (push) Has been skipped
48d165e360
Each script picks its engine. The embedded PowerShell 7 engine remains
the default with the full feature set on every platform. Windows
PowerShell 5.1 shells out to powershell.exe with near parity: a
generated wrapper renders parameters as typed PowerShell literals
(hashtables and arrays included), defines the secrets dictionary
(natively case-insensitive), dot-sources the prelude and splats the
payload; progress records are the accepted limitation. Bash runs the
prelude+script with parameters and secrets as environment variables
(complex values as JSON) on unix or via Git Bash on Windows — the WSL
System32 shim is deliberately ignored because it drops environment
variables. Engines unavailable on a device fail the job with a clear
message instead of running.

The editor gains an engine selector that also switches Monaco's
language. Verified with real out-of-process runs: powershell.exe 5.1
(v=5, typed splat, $Secrets) and Git Bash (env-var params + secrets).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replaces the fixed Viewer/Operator/Admin policy tiers with role objects.
A role bundles grantable permissions (devices, groups, scripts,
functions, jobs, automation, secrets, shell, files, settings, access),
optionally limits members to a device-group scope, and lists the OIDC
claim values that map identity-provider groups onto it — so who can do
what over which devices is fully configurable for local and SSO users
alike.

Three system roles matching the old tiers are seeded and immutable;
pre-upgrade users and cookies resolve onto them by name. Endpoints now
demand specific permissions ("perm:{key}" policies resolved through a
cached role snapshot, so edits apply without re-login). Scoped roles
only see and target their groups' devices across device listing,
job dispatch (single and group fan-out), shell, file delivery,
inventory refresh and tags. Safety rails: the last full-access user
can never be deleted or demoted, system roles cannot be edited, and
roles with assigned users cannot be dropped.

New Access page manages users (create local accounts, assign roles,
reset passwords) and roles (permission grid, OIDC claim values, device
scope); navigation hides sections the session cannot use. Session
responses now carry the role name and effective permissions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Package-Agent gains -Runtimes and picks the right flavor per RID
(net10.0-windows for win, portable net10.0 elsewhere) — this also fixes
publishing after the multi-targeting change, which requires an explicit
framework. Unix binaries ship as executer-agent; the MSI still harvests
the win-x64 output.

CI packages the agent for win-x64/linux-x64/linux-arm64/osx-x64/
osx-arm64 plus the combined standalone server (win-x64, linux-x64) and
uploads everything as a "binaries" artifact with checksums. Releases
attach the same set (Server zips included), and the release workflow
sets up Node 22 for the static WebUI build the server bundle needs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
README: standalone server, unix agents, script engines, custom roles
CI / build-test (push) Successful in 8m28s
CI / images (push) Successful in 2m15s
34c10b2f87
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Test the full cookie sign-in flow against permission-gated endpoints
CI / build-test (push) Successful in 8m0s
CI / images (push) Successful in 2m22s
5c0f16c2a9
Admin sign-in returns the wildcard permission set and reaches role
administration; a Viewer session reads devices but is refused
management. Exercises login, claims, the policy provider and the
role cache end to end over HTTP.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
runspace.SessionStateProxy.InvokeCommand.ExpandString is a direct .NET
call into the engine on the job's idle in-process runspace — identical
double-quoted-string semantics without compiling a wrapper pipeline per
value. Malformed interpolation now falls back to the env-expanded text
explicitly instead of relying on an empty pipeline result.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Bundle PSResourceGet, Archive and ThreadJob with the agent
CI / build-test (push) Successful in 8m46s
CI / images (push) Successful in 1m41s
deff3158e6
The PowerShell SDK ships only the core engine modules, so gallery
access on a bare endpoint depended on whatever happened to be
installed. Package-Agent now stages pinned PSGallery downloads
(PSResourceGet 1.2.0, Archive 1.2.6, ThreadJob 2.2.0) into a Modules
directory next to the binary for every platform, the MSI installs it,
and the agent prepends it to PSModulePath — covering the embedded
engine and, via process-environment inheritance, Windows PowerShell
5.1 child processes too. Install-PSResource needs no NuGet-provider
bootstrap, and AllUsers installs land on the standard module path
where later jobs resolve them.

Verified in the embedded host with only the bundled directory on the
path: PSResourceGet loads and reports PSGallery, Compress-Archive
produces a zip, Start-ThreadJob round-trips. Also drops the payload
trim rules for modules the SDK no longer ships.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Skips Invoke-WebRequest progress-rendering overhead; the gallery
redirect is followed automatically.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Refresh screenshots: Access page, role editor, engine selector
CI / build-test (push) Successful in 9m33s
CI / images (push) Successful in 1m41s
CI / build-test (pull_request) Successful in 3m14s
CI / images (pull_request) Has been skipped
682dcfe929
Re-captures every nav-bearing page (the rail gained Access), the
script editor showing the engine selector with loaded Monaco content,
and adds two Access-control shots: the users/roles overview and the
role editor with the permission grid, OIDC claim values and device
scope. README embeds them in the custom-roles section and the gallery.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
gsadmin merged commit febf57cf89 into main 2026-08-08 02:04:50 +00:00
Sign in to join this conversation.