# run

Machine-side executor for scoped server operations.

## Responsibilities

- 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:

```bash
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:

```bash
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.