How Strict Works: Zero-Account, Self-Healing Architecture for GitHub Actions Fleets
Most CI fleet tools ask you to buy into a cloud account, install root daemons, or route GitHub jobs through a third-party proxy. Strict takes a simpler path: a single TypeScript wire protocol shared between a local Tailscale server and an optional Cloudflare Worker, paired with zero-sudo Python host agents.
Keep GitHub Actions’ native runner registration and job execution untouched on your own hardware, while surrounding every runner slot with automated hygiene, lock-safe coordination, and tailnet observability.
1. Two control planes, one identical wire protocol
Rather than maintaining separate agent protocols for self-hosted vs. hosted
deployments, Strict defines its fleet state machine and REST schema once in
state.ts and workspace-core.ts, and mounts it behind two
interchangeable runtimes:
| Runtime | Standalone (standalone.ts) |
Cloud Monitoring (worker.ts) |
|---|---|---|
| Execution & storage |
Bun.serve (127.0.0.1:8787) with atomic writes to
state.json
|
Cloudflare Worker + D1 (strict-directory) + 1
WorkspaceState Durable Object per workspace
|
| Authentication |
Zero accounts: trusts Tailscale-User-Login behind
tailscale serve, loopback, or STRICT_ADMIN_TOKEN
|
GitHub OAuth, email magic links, Google/Apple OIDC + HS256 JWT
strict_session cookie
|
| Workspace ID & token |
Fixed ws0000000000 using
str_v1_ws0000000000_<64-hex>
|
Per-tenant str_v1_<workspaceId>_<64-hex> verified
with timingSafeEqualHex
|
| Periodic evaluator |
In-process timer calling evaluateWorkspaceAlerts
|
Durable Object 5-minute alarms (ALARM_INTERVAL_MS = 300_000)
|
| Alert dispatch | Webhooks + encrypted Cloudflare Email REST credentials (or env vars) |
Cloudflare Workers EMAIL binding (noreply@strict.ai)
+ webhooks
|
2. Two-phase locking and pre-job barriers
A subtle bug in naive self-hosted maintenance daemons is lock starvation—or worse,
pruning build caches while a runner picks up a job milliseconds later. Strict prevents
both with three coordinated file locks inside STATE_DIR:
-
Phase 1 (
agent-sync.lock): On every 30-second tick (StartInterval = 30on macOS;systemd --usertimer on Linux),strict_agent.pyacquiresagent-sync.lock, posts telemetry (diskFree, runner states,cpuCores,load1,load5,memUsedPct,toolchains,doctor, localtailscale status --json), reconciles runner drain directives, and releases the lock before any heavy cleanup or runner install starts. -
Phase 2 (
action.lock& non-blocking heartbeats): Multi-second tasks—like 7-tier cache reclamation or provisioning a new runner—run outsideagent-sync.lockunderaction.lock. While busy, subsequent 30s ticks detect_is_action_lock_busy()and still send lightweightreportOnly: trueheartbeats (respecting the server’sSYNC_MIN_INTERVAL_MS = 5000throttle) so the console never falsely marks a busy host offline. -
Pre-job barrier (
before-job.sh): When Strict configures a runner, it wiresACTIONS_RUNNER_HOOK_JOB_STARTEDin the runner’s.envtobefore-job.sh, which executesstrict_maintenance.py barrier. That command acquiresmaintenance.lockcleanly and exits—ensuring a newly starting GitHub job waits momentarily if tier cleanup or drain reconciliation is mid-flight rather than colliding onDerivedDataor workspace directories.
3. Persistent local NVMe + shared Tailnet cache
Strict treats caching as two complementary layers. First, a host’s own local NVMe
keeps DerivedData, SwiftPM, Cargo, Bun, Homebrew, and Docker/BuildKit
layers warm across consecutive runs on that box. Second, for multi-node fleets or
cross-host spillover, the standalone server exposes a built-in Tailnet Actions Cache
in cache.ts paired with strict_cache.py:
-
Running
strict add-runner owner/repo --cache-url http://<server>:8787(or exportingstrict cache env) setsSTRICT_CACHE_URLandACTIONS_CACHE_URLinside the runner environment with SHA-256 integrity checks and LRU size/TTL eviction. - All cache traffic rides point-to-point across your WireGuard Tailscale mesh at LAN speed with zero cloud bandwidth or egress fees.
4. Security & tenant isolation guarantees
Even when run without accounts on a home or office Tailnet, Strict enforces strict cryptographic and sandbox boundaries across the server and agent:
-
Hashed agent credentials: Agents persist their bearer token under
0600permissions, never log it, and redact tokens/URLs before truncating error text. Servers hash incoming tokens with SHA-256 and compare viatimingSafeEqualHex, returning403on cross-workspace tokens. -
Ephemeral secret scrubbing: Queued runner registration tokens and
provisioner SSH targets have their
secretTokenwiped immediately on claim, completion, or expiry (ACTION_TTL = 360_000,PROVISION_TTL = 180_000) and never leave the server via/state. -
AES-256-GCM integration secrets: Tailscale OAuth secrets, webhook
URLs, and standalone Cloudflare Email REST API tokens are encrypted at rest
(
v1.<iv>.<ciphertext>) and only decrypted outside storage transactions right before outbound delivery. -
Strict CSP & RBAC: Every HTML response ships with
default-src 'none'; style-src 'self'; script-src 'self'; frame-ancestors 'none', same-Originchecks on mutating POST endpoints, andcanMutate(role)checks (owner/adminonly) in Cloud mode.