Register with platform and report heartbeat, version, capabilities, and capacity.
Claim and execute jobs for server lifecycle, file/config work, backups, updates, and bounded database or command work.
Collect server logs into local spool and upload acknowledged batches.
Transfer artifacts with chunking, checksums, resume, throttling, and low priority.
Optionally coordinate with a game client bridge when a specific game requires in-game commands or snapshots.

Required Directory Plan

Implementation should use dedicated directories for:

api/: platform-facing HTTP/gRPC client adapters.
protocol/: control, job, log, artifact, and game-client bridge DTOs.
domain/: executor domain types.
runtime/: local execution and server process orchestration.
spool/: local durable log/job/artifact queues.
artifact/: chunk transfer implementation.
logingest/: log collectors and uploaders.
config/: configuration structures and loading.
shared/: small shared helpers.

Logs and artifacts must have separate queues and priority controls.

Development Baseline

Tooling:

Go 1.25.1.
Module: browser.local/run.

Commands:

go test ./...
go run ./cmd/run

Runtime configuration:

RUN_MODE: local mode, default smoke.
RUN_PLATFORM_URL: platform base URL, default http://127.0.0.1:8080.
RUN_ENDPOINT_ID, RUN_DISPLAY_NAME, RUN_VERSION, RUN_REGISTRATION_TOKEN: worker identity and registration metadata.
RUN_WORKSPACE_ROOT, RUN_SPOOL_ROOT: scoped local server workspace and separate local log/artifact queues.
RUN_MAX_JOBS, RUN_HEARTBEAT_INTERVAL_MS, RUN_POLL_INTERVAL_MS, RUN_RETRY_BACKOFF_MS: worker capacity and scheduling controls.

For local direct debugging, copy run/.env.example to run/.env, edit the values, and run:

set -a
source .env
set +a
go run ./cmd/run

Use RUN_MODE=worker when you want the executor to register, heartbeat, claim jobs, and execute lifecycle templates. Use RUN_MODE=smoke for a one-shot config summary.

In Docker, RUN_PLATFORM_URL must be http://platform:8080 because platform is the compose service name. Locally, keep it as http://127.0.0.1:8080.

Current executable behavior includes smoke mode plus worker mode. Worker mode registers with platform, sends lightweight heartbeat metadata, claims lifecycle jobs, acknowledges leases, reports bounded progress, executes scoped process.install, process.start, and process.stop command templates inside per-server workspaces, polls cancellation, submits terminal results, and reconciles active jobs.

Lifecycle templates are JSON files addressed by logical keys under the server workspace. They resolve to direct executable/argument vectors, not shell strings. Absolute paths, parent traversal, raw credentials, direct sockets, shell launchers, unsafe environment keys, and unsafe output are rejected or redacted. Process stdout/stderr is written to the log spool, and lifecycle result metadata is queued through artifact hooks so control heartbeat and job result submission stay independent from log and artifact work.