[Grid agent] Package and document portable service operation and secret handling #134

New Issue

hugo · 2026-08-17T19:31:38Z

hugo commented

2026-08-17 19:31:38 +00:00

Objective

Package and document the agent for safe unattended operation while preserving one portable binary and the same behavior in foreground, integrated-TUI, and split service/TUI modes.

Runtime and configuration

Document minimal quick start, exact endpoint URL/API-key contract, grid credentials, authorized UUIDs, behavior/limits, storage, fake mode, integrated/split modes, control authentication, and safe shutdown/recovery.
Provide configuration examples with placeholders only and a command that validates configuration without contacting the grid or LLM. Define precedence, reloadable versus restart-only fields, schema versioning, and migration/error behavior.
Provide a hardened Linux systemd unit/example because headless service operation is required. Keep the binary independent of systemd and provide equivalent Windows service-wrapper/SCM guidance plus portable foreground operation; avoid OS-specific core APIs.
Use platform-appropriate config/data locations and restrictive secret-file checks where supported. Explain limitations on filesystems that cannot enforce permissions. Never put secrets on command lines, unit files, example logs, crash reports, or TUI screens.
Document control-plane binding/TLS, firewall expectations, log rotation/retention, backup/recovery of non-secret state, health/readiness checks, upgrades/rollback, emergency pause, orphan-build recovery, and API-key/grid-password rotation.

Build and dependency evidence

Produce compact release builds with intentional feature selection and record binary size/dependency inventory. Audit that the agent path is native Rust with no CLR, scripting runtime, provider SDK, subprocess adapter, or undeclared native library.
Keep all code/APIs cross-platform. Any Gitea workflow additions or edits run only on ubuntu-latest; use portable compile/static checks rather than macOS/Windows Gitea jobs.

Acceptance criteria

A clean operator can follow the docs to run fake foreground, integrated TUI, split service/TUI, and Linux systemd modes without reading source.
Windows service guidance exercises the same portable service/control protocol and shutdown semantics.
Install/upgrade does not overwrite operator config, secrets, conversations, or audit journals.
Documentation includes threat model, privacy/redaction behavior, resource defaults, failure playbooks, and explicit unsupported operations.

Dependencies

Depends on stable configuration, service/control, TUI, observability, and test interfaces. It must be complete before live-grid milestone validation.

## Objective Package and document the agent for safe unattended operation while preserving one portable binary and the same behavior in foreground, integrated-TUI, and split service/TUI modes. ## Runtime and configuration - Document minimal quick start, exact endpoint URL/API-key contract, grid credentials, authorized UUIDs, behavior/limits, storage, fake mode, integrated/split modes, control authentication, and safe shutdown/recovery. - Provide configuration examples with placeholders only and a command that validates configuration without contacting the grid or LLM. Define precedence, reloadable versus restart-only fields, schema versioning, and migration/error behavior. - Provide a hardened Linux `systemd` unit/example because headless service operation is required. Keep the binary independent of systemd and provide equivalent Windows service-wrapper/SCM guidance plus portable foreground operation; avoid OS-specific core APIs. - Use platform-appropriate config/data locations and restrictive secret-file checks where supported. Explain limitations on filesystems that cannot enforce permissions. Never put secrets on command lines, unit files, example logs, crash reports, or TUI screens. - Document control-plane binding/TLS, firewall expectations, log rotation/retention, backup/recovery of non-secret state, health/readiness checks, upgrades/rollback, emergency pause, orphan-build recovery, and API-key/grid-password rotation. ## Build and dependency evidence - Produce compact release builds with intentional feature selection and record binary size/dependency inventory. Audit that the agent path is native Rust with no CLR, scripting runtime, provider SDK, subprocess adapter, or undeclared native library. - Keep all code/APIs cross-platform. Any Gitea workflow additions or edits run only on `ubuntu-latest`; use portable compile/static checks rather than macOS/Windows Gitea jobs. ## Acceptance criteria - [ ] A clean operator can follow the docs to run fake foreground, integrated TUI, split service/TUI, and Linux systemd modes without reading source. - [ ] Windows service guidance exercises the same portable service/control protocol and shutdown semantics. - [ ] Install/upgrade does not overwrite operator config, secrets, conversations, or audit journals. - [ ] Documentation includes threat model, privacy/redaction behavior, resource defaults, failure playbooks, and explicit unsupported operations. ## Dependencies Depends on stable configuration, service/control, TUI, observability, and test interfaces. It must be complete before live-grid milestone validation.

hugo added this to the 14 - metacrate grid agent milestone 2026-08-17 19:31:38 +00:00

hugo added the enhancement label 2026-08-17 19:31:38 +00:00

hugo referenced this issue

2026-08-17 19:32:14 +00:00

implement an AI driven agent that runs in opensim #117

hugo referenced this issue from a commit

2026-08-18 10:27:16 +00:00

Package portable grid agent operation (#134)

hugo commented

2026-08-18 10:27:31 +00:00

Implemented and pushed as commit 00707fd. Added schema-versioned placeholder configurations, platform config/data discovery, storage environment precedence, offline --check-config and --print-paths operation, and fail-closed Unix secret permissions. Added hardened systemd packaging, state-preserving POSIX and Windows installers, equivalent Windows service/control/shutdown guidance, and a complete operations runbook covering TLS/firewalls, retention, backup/recovery, upgrades/rollback, emergency handling, secret rotation, threat/privacy/resource limits, failure playbooks, and unsupported operations. Recorded native release size/hash/dependency evidence. Verification: focused packaging tests (3/3), config tests (9/9), all-feature strict Clippy, rustdoc warnings-as-errors, formatting, and diff checks passed. The Windows Rust target check reached the existing AWS-LC native build and was blocked solely because x86_64-w64-mingw32-gcc is not installed on this host; platform-conditioned behavior and installer contracts are covered by tests. Namespace audit confirms the service remains metacrate-grid-agent and the libremetaverse facade has no metacrate references.

Implemented and pushed as commit 00707fd. Added schema-versioned placeholder configurations, platform config/data discovery, storage environment precedence, offline --check-config and --print-paths operation, and fail-closed Unix secret permissions. Added hardened systemd packaging, state-preserving POSIX and Windows installers, equivalent Windows service/control/shutdown guidance, and a complete operations runbook covering TLS/firewalls, retention, backup/recovery, upgrades/rollback, emergency handling, secret rotation, threat/privacy/resource limits, failure playbooks, and unsupported operations. Recorded native release size/hash/dependency evidence. Verification: focused packaging tests (3/3), config tests (9/9), all-feature strict Clippy, rustdoc warnings-as-errors, formatting, and diff checks passed. The Windows Rust target check reached the existing AWS-LC native build and was blocked solely because x86_64-w64-mingw32-gcc is not installed on this host; platform-conditioned behavior and installer contracts are covered by tests. Namespace audit confirms the service remains metacrate-grid-agent and the libremetaverse facade has no metacrate references.

hugo closed this issue

2026-08-18 10:27:31 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/MetaCrate#134