empeira 0.1.0.pre.alpha.1

data/docs/proxy.md

@@ -0,0 +1,136 @@
+# Proxy policy
+
+Normal external HTTP/HTTPS access stays behind Squid. Enabling the workspace proxy
+makes it available to every node; global and hostname rules remain the destination
+allowlist:
+
+```yaml
+proxy:
+  enabled: true
+  global:
+    - forgeapi.puppet.com
+  rules:
+    - hosts: ["lab-*"]
+      allow: ["*.github.com"]
+    - hosts: ["*-web-*"]
+      allow: [github.com, nginx.org]
+```
+
+```console
+empeira up
+empeira node run lab-web-1-01.example.net --provider container
+empeira proxy show lab-web-1-01.example.net
+```
+
+The diagnostic prints:
+
+```text
+Effective proxy policy for lab-web-1-01.example.net
+All workspace nodes may use this policy after 'empeira up' reconciles the proxy.
+Global:
+  forgeapi.puppet.com
+Matched rules:
+  lab-*
+  *-web-*
+Allowed:
+  forgeapi.puppet.com
+  *.github.com
+  github.com
+  nginx.org
+Managed bootstrap destinations are separate from this normal policy.
+```
+
+The diagnostic resolves desired policy even for a hostname that does not exist.
+It reports when the normal proxy is disabled and does not claim that live
+infrastructure has already been reconciled.
+
+## Matching and destinations
+
+Defaults are `proxy.global: []` and `proxy.rules: []`. Every node receives
+all global destinations plus `allow` from **every** matching rule. Duplicate entries
+are removed while preserving configuration order. A rule matches when any of its
+`hosts` patterns matches the complete lowercase hostname. Patterns must be lowercase.
+`*` matches any sequence, including dots, and `?` matches one character. Examples
+include `*-web-*`, `lab-*` and `*-db-??.*`. There is no regex, first-match,
+last-match or deny-rule syntax. Container and VM providers use the same resolver.
+
+Destination rules are separate from hostname globs:
+
+| Entry | Meaning |
+| --- | --- |
+| `github.com` | Exact DNS destination |
+| `*.github.com` | Squid domain family, including the apex and its subdomains |
+| `https://github.com`, `github.com/path`, `github.com:443` | Invalid |
+| IP literals, whitespace, internal Empeira names | Invalid |
+
+Only HTTP port 80 and HTTPS CONNECT port 443 are allowed. Allowed DNS destinations
+are reachable regardless of their target IP range, including private, loopback,
+link-local and reserved addresses. Domains without a matching allow rule remain
+denied. There is no TLS interception. Server-side outbound traffic gets
+`proxy.global` only; node hostname rules do not expand server access.
+
+## Node policy and reconciliation
+
+When `proxy.enabled` is true, all nodes are authorized as proxy clients. Nodes get
+upper/lowercase proxy variables and internal `NO_PROXY` entries, including explicitly
+configured `network.egress` hosts. Those named hosts use the common workspace
+gateway for their configured ports. VM access uses the same destination policy bound
+directly to the VM instance's reserved peer address. The proxy is reached at
+`proxy.empeira.internal:3128` on the isolated network. A request without a matching
+global or hostname rule remains denied.
+
+After changing global destinations or rules, or updating Empeira's generated Squid
+policy, run `empeira up`. It regenerates current node bindings and reloads Squid
+after readiness without replacing the proxy or unrelated services. Unchanged
+policy and bindings do not trigger a reload. A checkpoint in the existing
+inventory records the proxy ID and digest of the small configuration files only
+after the native reload succeeds; a failed or interrupted reload is retried by
+the next `up` even when files already contain the requested policy.
+Container and VM nodes consume the new policy without a restart; open proxy
+connections can end during reconciliation. Enabling/disabling proxy mode is a
+separate topology change and may require explicit node cleanup as reported by `up`.
+
+Changing direct-egress destinations also changes the server's `NO_PROXY`
+environment. `up` replaces a server whose environment definition changes while
+retaining CA storage and node identities. Changing only destination ports or
+transparent redirect rules preserves the server when its definition is unchanged.
+
+## Managed bootstrap
+
+Managed bootstrap destinations are separate from normal user policy. Reviewed
+agent and distribution endpoints in `agent.install` and `bootstrap.guests` allow
+Puppet/OpenVox and required guest packages to be installed without duplicating them
+in `proxy.global`. The temporary authenticated bootstrap proxy uses workspace DNS
+and retains its private, loopback, link-local and reserved destination-address
+restrictions independently of normal proxy policy. Its credential is not stored in
+the guest seed, JSON inventory or logs. A /32 source ACL admits only the provisioning
+node. The proxy and its private configuration are removed after use. When the normal
+workspace proxy is disabled, a node has no proxy access once bootstrap ends.
+
+`bootstrap.guests.*.destinations` grants network access only; it never writes an APT
+source. Ubuntu and Debian retain the base image's sources. The temporary agent
+repository and every other `/etc/apt` change made during bootstrap are restored and
+verified before the proxy is removed and before Puppet starts. The reviewed Ubuntu
+defaults permit archive/security only for amd64 and ports only
+for arm64.
+
+Default OpenVox sources include `apt.voxpupuli.org` and
+`yum.voxpupuli.org`; distribution mirrors come from reviewed base images.
+Custom agent sources are configured under `agent.install` and are not embedded
+in Empeira. Their versions, checksums and destination lists are user-managed.
+Package managers verify repository signatures. See the
+[official OpenVox installation sources](https://voxpupuli.org/openvox/install/),
+[Ubuntu archives](https://archive.ubuntu.com/ubuntu/) and
+[Rocky repositories](https://dl.rockylinux.org/pub/rocky/).
+
+For later package updates performed by Puppet, enable the normal proxy and add the required
+destinations to global or matching normal rules. They can remain permitted
+permanently. Requests to all other destinations remain denied.
+
+Puppetfile synchronization and image refreshes belong to the independent update
+plane. They do not use this workspace proxy or its allowlists. Forge runs in a
+disposable helper with normal container-runtime networking and supplied user proxy
+variables. Git uses the invoking user's host Git/SSH configuration and network
+access, without copying private keys. No update starts Squid, CoreDNS or other
+workspace services. See [update-plane architecture](architecture.md#runtime-and-update-planes).
+Self-update and the aggregate `update all` remain unavailable.

data/docs/troubleshooting.md

@@ -0,0 +1,361 @@
+# Troubleshooting
+
+Start with `empeira config validate`, `empeira status` and `empeira node list`.
+Status is read-only and reports unavailable engines or invalid inventory as
+unknown/diagnostic states. Its successful exit means a report was produced, not
+that infrastructure is healthy. `up` performs readiness checks.
+
+## HTTP and transport errors
+
+HTTP failures identify the operation, requested URL, actual status and server reason
+phrase, followed by the available response. For example:
+
+```text
+Operation: Download agent package
+URL: https://packages.example.org/apt/pool/agent.deb
+HTTP status: 404 Not Found
+Response:
+  Package is unavailable
+```
+
+URLs retain their host and path; user information, sensitive query values, known
+credentials, authorization headers and cookies are redacted. Multiline text and JSON
+remain readable. HTML, truncation and unavailable/empty bodies are labelled; binary
+bodies are omitted. Diagnostic output is limited to 8 KiB after redaction.
+
+DNS, connection, timeout, TLS and proxy failures are reported as transport failures.
+If no HTTP response was received, no status is invented. APT, DNF, Docker/Podman and
+Git/r10k retain their native details; unavailable URL/status/body fields are identified
+as unavailable separately. Empeira sends no extra requests for diagnosis. A 401 can
+offer one agent-repository login in a TTY; CI uses both `EMPEIRA_AGENT_REPO_USERNAME`
+and `EMPEIRA_AGENT_REPO_PASSWORD`. Rejected interactive and ENV logins are distinguished.
+HTTP 403 does not trigger login, and HTTP 407 identifies proxy authentication. Registry
+authentication continues to use native `docker login` / `podman login` and the reported
+registry host; Empeira does not log into registries automatically.
+
+APT helper credentials use literal `login` and `password` tokens in a temporary
+0600 file under `/etc/apt/auth.conf.d`. APT treats surrounding quotes and added
+backslashes as credential bytes, so Empeira does not add them. A successful login
+rewrites this file before retrying the same metadata command. The host-side package
+download reuses the credentials for the same HTTPS origin. APT's token format cannot
+represent whitespace inside a credential value.
+
+## KVM and QEMU
+
+A present `/dev/kvm` is insufficient: the invoking user needs read/write access
+and a working KVM API. Empeira reports device ownership, groups and capability
+failures. If access is through the `kvm` group, add your user and start a fresh session:
+
+```console
+sudo usermod -aG kvm "$USER"
+```
+
+On WSL2, run `wsl.exe --shutdown` from Windows and reopen WSL after changing groups.
+Do not change device permissions globally. Missing `/dev/kvm` or absent accelerator
+support is not repaired by a group change. The QEMU build must support KVM/HVF for
+the detected platform. Empeira refuses software emulation and does not provision
+Windows-host QEMU automatically. See [installation](installation.md).
+
+Missing `xorriso` prevents initial cloud-init seed creation. Install it with the
+other VM prerequisites. Restarting an existing initialized VM does not require a
+new seed build. ARM64 also needs the firmware reported by preflight.
+
+## SSH login failures
+
+For a VM, `node ssh` defaults to `empeira` and the existing managed private key,
+including when bootstrap is incomplete. For containers, it uses the local user's
+name and normal OpenSSH keys/agent/config. Neither path injects a replacement key
+or provisions a login user. Verify your Puppet-created account,
+authorized keys, home permissions, daemon, PAM and login profile. Use `--user`,
+`--identity` and `--port` independently when appropriate:
+
+```console
+empeira node ssh host1 --user deploy --identity ~/.ssh/test_ed25519
+empeira node ssh host1 --port 2222
+empeira node shell host1
+```
+
+If SSH reports `Too many authentication failures`, your agent may offer too many
+keys before the intended one. For containers, select the identity in your normal
+OpenSSH `Host` configuration and set `IdentitiesOnly yes` there when needed. VM
+access selects its managed or explicit identity and disables password authentication.
+
+VM management uses a private VirtIO-Serial execution service, separate from
+system SSH. `node ssh` defaults to guest port 22 and never checks or forwards
+through management. A failed system login reports the native SSH error and does
+not restart the daemon or replace authentication. Root shadow `!`, sudoers, PAM,
+regular accounts and authorized keys do not govern management.
+
+For an actual management failure, inspect `node logs` and the private serial
+console. From the guest console run:
+
+```bash
+cloud-init status --long
+journalctl -u empeira-management.service
+ls -l /dev/virtio-ports/org.empeira.management.0
+```
+
+The cloud image requires Python 3 before package bootstrap (`/usr/bin/python3`
+or `/usr/libexec/platform-python` on Rocky Linux). Preserve SELinux enforcement
+and inspect AVC messages if it denies a guest operation. Removing the interpreter,
+service, VirtIO port or filesystem can interrupt management. Empeira preserves
+storage, reports unknown completion and uses no authentication fallback. Console
+credentials stay under Puppet's control; there are no later password resets.
+Older VM layouts require explicit `node destroy` and recreation. Current destroy
+uses stored ownership without requiring a compatible guest layout. Existing VMs are never migrated or deleted automatically.
+
+VM creation failures retain the original diagnostic and add the retained node's
+cleanup command. Inspect the underlying failure first; an incomplete VM requires
+explicit node destruction and recreation after the cause is corrected.
+
+For a container, shell is runtime exec. For a VM, shell is a root PTY over private
+VirtIO and works with root locked or SSH stopped. `node console` is the separate
+serial recovery path. Press Enter there, then use the current console credentials.
+The initial default is `root` / `empeira`, unless disabled/overridden or changed by
+Puppet. **Ctrl-] detaches**. Empeira does not reset credentials to repair a failed login.
+Stopped nodes need `node start`. Investigate changed SSH host keys instead of
+turning off checking. Destroy/recreate removes a disposable node's private known-hosts entry.
+
+VM sessions release the workspace mutation lock. Status and independent workspace
+operations remain available, and multiple VM SSH sessions may coexist. Stop, destroy
+or restart of that same VM conflicts with the shared instance guard: detach with
+**Ctrl-]** for console sessions, or exit SSH, then retry. Do not delete lock files.
+
+## Proxy destination denied
+
+Run `empeira proxy show HOSTNAME` and check every matching rule. Verify the node
+exists in the workspace, `proxy.enabled` is true, and `up` has reconciled the
+configuration and current node addresses. Allowed DNS destinations may resolve to
+private or reserved IP addresses; only HTTP port 80 and HTTPS CONNECT port 443 are
+permitted. After updating Empeira, run `empeira up` to replace a proxy still using
+the previous IP restrictions. Managed bootstrap access retains its own destination
+restrictions and does not grant normal access afterward. See [proxy](proxy.md).
+
+## Hiera and EYAML
+
+Mount visibility failures identify the local source, container destination and
+sanitized native exit status/output. A stopped container cannot run a mount probe;
+inspect its existing server logs rather than assuming a sharing or permission
+problem. A successful probe with different directory listings indicates a
+different engine view of the source. Empeira does not weaken mount checks or
+change host permissions automatically.
+
+An explicit `environment_timeout` in the project's `environment.conf` overrides
+the native server setting. Empeira preserves it. Bare `puppet config print`
+includes that override; server startup and reconciliation verify only the native
+server value. Set the environment override to zero or remove it when immediate
+code reloads are required. No explicit cache invalidation is performed.
+
+`config show` includes `effective_hiera_mounts`. A skipped optional source is
+reported during `up`; mount it locally or correct the source path, then run `up`
+again. Set `required: true` when absence must stop startup. Invalid targets,
+collisions, symlink escapes and known modulepath exclusions are errors even for
+optional mounts. Existing mounted data changes are live without a restart.
+
+When EYAML is enabled, both key paths must resolve to readable regular PEM files.
+Relative paths are resolved against the selected canonical control repository.
+Check engine visibility/UID mapping and the paths in `hiera.yaml`, without printing
+private material. See [Hiera and EYAML](hiera-and-eyaml.md).
+
+## Retained, missing or stale resources
+
+If agent installation reports an unavailable package version, compare
+`agent.version` and the configured repository `suffix` with the versions
+published by that source. The retained node can be inspected with `node shell`.
+For `method: package`, use the complete installed package version and verify
+its URL and SHA-256. A checksum mismatch stops before package installation.
+Valid agent-cache hits need no network access or credentials. On a cache miss,
+a damaged artifact or with caching disabled, `401 Unauthorized` calls for both
+`EMPEIRA_AGENT_REPO_USERNAME` and `EMPEIRA_AGENT_REPO_PASSWORD`; `403 Forbidden`
+means access is denied and `404 Not Found` means a source or package is missing.
+A signature error calls
+for checking the configured signing key or RPM signature. Credentials do not
+belong in YAML. Failed APT/DNF restoration retains the node and prevents the
+first Puppet run and subsequent `node start` or `node puppet` operations. Existing
+release packages are rejected before changes; use a clean base image or a signed
+custom source. Protected DNF release-RPM repositories are unsupported; configure
+`agent.install.dnf` instead.
+
+If node creation fails during key preparation, verify that the selected agent
+package was installed and provides `/opt/puppetlabs/bin/puppet` and
+`/opt/puppetlabs/puppet/bin/ruby`. Keep replacement agents out of
+`bootstrap.packages`: configure `agent.package`, `agent.version` and
+`agent.install` instead, then destroy and recreate the incomplete node.
+The agent choice does not change server or database images.
+
+A failed bootstrap retains the container or VM and hostname for diagnosis:
+
+```console
+empeira node logs vm1
+empeira node ssh vm1
+empeira node console vm1
+empeira node destroy vm1
+empeira node run vm1 --provider vm
+```
+
+APT cleanup errors now identify the failed archive or removal operation, exit code,
+timeout and sanitized native output. A guest failure is distinct from an SSH
+transport failure with unknown completion. A readable backup that can be removed
+manually does not establish the earlier SSH outcome. The already verified backup
+removal is retried once only for recognizable transient SSH connection errors.
+Permission, host-key and authentication errors, command timeouts and persistent failures
+remain fatal. Successful manual cleanup alone does not mark an incomplete node as
+provisioned or permit Puppet; correct the reported cause and recreate the node.
+
+Incomplete nodes remain available for diagnostics but cannot start or run Puppet.
+Destroy and recreate them after correcting the source of the failure. Missing or corrupt
+pinned base images require restoring the exact cached image before an existing
+overlay can resume. Image changes never replace node state automatically.
+Ownership conflicts or changed runtime IDs require inspection; deterministic names
+are insufficient to adopt/delete resources. Never delete inventory or the stable
+mutation lock file to bypass a failure. Unknown state schemas fail closed.
+
+`down` removes services/networks but retains CA and database volumes. Existing nodes,
+even stopped ones, must be destroyed first. `destroy` permanently removes all owned
+workspace nodes, infrastructure and retained CA/database data without a prompt.
+If `up` reports that a managed service exited after start, inspect its container logs
+using the runtime command printed in the error. A route-helper failure can otherwise
+hide an earlier service exit; `status` shows which service stopped.
+`destroy` can also run when `.empeira.yaml` or user configuration is invalid. It uses
+the validated inventory to select the owning runtime and removes only owned resources.
+Keep the project marker file and valid inventory in place for this recovery path.
+It preserves the control repository, module directory and native caches so a subsequent `up` can reuse
+unchanged Puppetfile modules. Missing retained volumes or database credentials
+are not permission to initialize empty replacements. Preserve state and volumes
+together during recovery. See [architecture](architecture.md#persistent-state-and-ownership).
+
+## Project marker and browser
+
+“An Empeira Git project is required” means the current directory is outside a Git
+worktree, or Git cannot run. Enter your control repository and check
+`git rev-parse --show-toplevel`. A missing-marker error prints the canonical root,
+exact `.empeira.yaml` path and shell-safe `touch` command. An empty marker is valid;
+placing it in a subdirectory does not opt in the root. `--project` is not supported.
+
+`empeira browser` prints a dynamic loopback HTTPS URL. The default UI has a self-signed
+certificate and may take a few seconds to initialize. Open internal URLs in that
+Chromium desktop, not directly in the host browser. External websites failing is
+expected: the browser has no Internet grant. `status` shows Browser and Browser-ui;
+`up` reconciles an existing browser, and `down` removes it and its disposable profile.
+Run `empeira up` before the first browser request. The browser command does not start
+or reconcile stopped workspace infrastructure. If it reports a missing workspace,
+network, or CoreDNS service, restore the control plane with `empeira up` and retry.
+`browser.start_url` defaults to `about:blank` and is not checked for reachability.
+For an internal application that starts later, simply reload the page in Chromium.
+If ownership or loopback/network checks fail, investigate the runtime resource rather
+than attaching an unrestricted network or publishing services publicly. Browser-to-VM
+URLs use the VM hostname and application port directly. Check VM network health,
+CoreDNS records and whether the guest application listens on its peer interface.
+
+OpenVox View should use `PUPPETDB_HOST=puppetdb.empeira.internal`,
+`PUPPETDB_PORT=8080`, and `PUPPETDB_TLS=false`. Check internal DNS and PuppetDB's
+HTTP query readiness if it cannot load data. No client TLS credentials are needed.
+Do not publish PuppetDB to the host: its HTTP API is intentionally unauthenticated
+within the disposable isolated network.
+The configuration server uses the HTTPS relay on port 8081 with a workspace
+CA-issued server certificate. This is required by the PuppetDB terminus; check
+the relay and backend separately if catalogs or reports fail. The backend itself
+listens only on HTTP port 8080.
+
+The browser relay builds `resources/relay/Containerfile` locally. On build errors,
+check the selected runtime's registry access and the configured relay recipe/image;
+changing the Puppet/OpenVox server image is not a relay dependency fix.
+
+## Shared peer network
+
+Unsupported inventory/definition revisions require explicit recovery or recreation.
+Preserve state while investigating ownership errors; never delete live channel
+directories, force-remove attached networks, reset Podman Machine or kill processes
+by name. No automatic migration is provided.
+
+Native rootless Podman requires writable TUN and KVM inside
+`podman unshare --rootless-netns`, iproute2, Netavark and disabled forwarding on the
+owned bridge. Docker requires its supported isolated bridge mode. A packet helper
+checksum, network, capability or recorded-ID mismatch fails closed. A live QEMU or
+channel with an unavailable control socket must be investigated before retrying.
+
+On macOS, select exactly one running rootless Podman Machine and its matching default
+connection. Share the canonical Empeira state path with that machine: the exported
+helper must have the same SHA-256 from both hosts. No rootful fallback is available.
+Subnet exhaustion means known host/VPN or runtime routes cover all candidates;
+inspect those routes instead of disabling overlap checks. IPv6 peer networking is
+not supported.
+
+## Artifact updates
+
+`update modules` and `update images` do not start or reconcile infrastructure. Image
+changes take effect during the next `empeira up`. Module updates write directly into
+`modules.path` and can be visible to a running server immediately. `up` never synchronizes modules; missing modules fail before runtime mutation with
+`Run: empeira update modules`. Missing images are acquired automatically; existing
+images are reused without remote checks.
+Failed explicit updates may leave partially changed module files; fix the cause and
+rerun the update. Existing plausible modules are usable without a freshness check. Diagnose Forge, registry, version/ref, authentication and normal
+host/container connectivity errors; changing the workspace proxy allowlist does
+not repair update-plane connectivity. User proxy settings and runtime registry
+credentials apply. Git uses the invoking user's normal SSH identity and configuration.
+
+Image updates preserve the native Docker/Podman buildcache (`build --pull`, without
+`--no-cache`) and select the configured default plus workspace-used container node
+variants. Native remote metadata checks have a 30-second budget (Podman may need
+up to five more seconds for local temporary-manifest cleanup). Authentication,
+unsupported/malformed metadata or timeout errors identify the image and filtered
+diagnostic; no full pull is attempted as a fallback. Docker/Podman must support their
+native manifest commands. An old index digest may need a native immutable-reference
+lookup for platform comparison; a registry that has deleted that manifest can prevent
+the comparison. Fix registry access or explicitly remove only the affected unused
+local artifact before retrying. Builds and pulls have a 600-second timeout. A timed-out CLI process group
+is killed and reaped, its temporary build context is removed, and filtered buffered
+diagnostics identify the affected image. Successful tool logs remain hidden.
+
+Update helpers are removed after completion where the engine is reachable. If an
+engine stops responding during cleanup, restore access and inspect the reported
+update-helper failure before removing anything; names alone do not establish
+ownership. `self-update` and `update all` remain unavailable until release package
+replacement is implemented. Image updates are not atomic across the full catalog;
+earlier successful pulls/builds remain after a later failure.
+
+## User preferences and registry authentication
+
+`config show` includes effective `runtime.container_engine` and `images.registry`
+after optional `~/.empeira.yaml` preferences. Only those two keys are allowed there;
+move project behavior into the control repository rather than adding user-level
+server, network or service overrides. Invalid user YAML fails with its file and
+configuration path. The file is optional; absence is not an error.
+
+For likely registry authentication/authorization failures (401/403, unauthorized,
+authentication required, access denied or insufficient scope), Empeira prints the
+native login command for the resolved registry, for example
+`docker login registry.example.net` or `podman login ghcr.io`. Authenticate
+and verify repository permissions, then retry the original Empeira command. A login
+cannot grant permissions your account does not have. Runtime credential helpers and
+auth files are used directly; Empeira never manages registry credentials.
+
+`manifest unknown`, `name unknown` and missing-image errors point to the repository
+or tag. Timeouts, refused connections and DNS failures require network diagnosis;
+certificate/x509 failures require runtime CA trust diagnosis. These errors do not
+produce login advice. Sanitized native diagnostics are retained for all categories;
+metadata failures never fall back to a full pull.
+
+## Workspace gateway and direct egress
+
+`status` reports Gateway/DNS/Proxy readiness and overall Workspace network health.
+After an egress edit or DNS change, run `empeira up`; nodes keep their identities.
+A failed hostname lookup leaves egress blocked. Check the host/corporate resolver
+and every A record first. An IPv6-only destination is unsupported, not silently allowed.
+
+For DIRECT traffic, inspect `network.egress`: exactly one host/IP and the actual
+TCP port must be allowed. `NO_PROXY` is application selection, not authorization.
+No proxy fallback occurs. A denied SYN normally times out; Empeira cannot infer
+from that timeout alone whether a remote service, route or firewall caused it.
+`Network is unreachable` instead suggests a missing node default route; rerun `up`
+to repair managed container routes and inspect the VM workspace NIC gateway.
+
+Gateway firewall drift or disabled forwarding is reported separately by the
+readiness probe. Failed apply stops/blocks the gateway; never attach a node to an
+external runtime network as a workaround. Docker workspace bridge attachment
+errors require an accessible Linux-engine host namespace and an identifiable
+iptables backend. The helper changes only owned bridge rules. Do not disable the
+host firewall globally. Check Docker Desktop host-network restrictions separately.
+Proxy errors require checking Squid source bindings and `proxy.global`/`proxy.rules`,
+not adding unrelated direct grants. Corporate DNS still follows host discovery;
+IPv6-only upstreams must be replaced with reachable IPv4 resolvers for this backend.

data/lib/empeira/addons/environment.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'etc'
+
+module Empeira
+  module Addons
+    class Environment
+      API_VERSION = '1'
+
+      def initialize(context:, name:, ref:, path:, inherited: ENV.to_h)
+        @context = context
+        @name = name
+        @ref = ref
+        @path = path
+        @inherited = inherited
+      end
+
+      def export(arguments: [])
+        environment = @inherited.keys.grep(/^EMPEIRA_/).to_h { |key| [key, nil] }
+        flatten(@context.configuration, 'EMPEIRA_CONFIG', [], environment)
+        flatten(@context.configuration.dig('addons', @name, 'config') || {}, 'EMPEIRA_ADDON_CONFIG', [], environment)
+        environment.merge!(runtime)
+        validate_size!(@inherited.merge(environment).compact, arguments)
+        environment
+      end
+
+      private
+
+      def runtime
+        values = { 'EMPEIRA_VERSION' => BuildInfo.load.version, 'EMPEIRA_ADDON_API_VERSION' => API_VERSION,
+                   'EMPEIRA_ADDON_NAME' => @name, 'EMPEIRA_ADDON_VERSION' => @ref,
+                   'EMPEIRA_ADDON_PATH' => @path.expand_path.to_s }
+        values['EMPEIRA_CONTROL_REPO'] = @context.project.path.expand_path.to_s if @context.project
+        values['EMPEIRA_WORKSPACE'] = @context.workspace.path.expand_path.to_s if @context.workspace
+        values
+      end
+
+      def private_path?(path)
+        Configuration::Schema::ADDON_PRIVATE_PATHS.any? do |pattern|
+          pattern.size == path.size && pattern.zip(path).all? { |expected, key| expected == '*' || expected == key }
+        end
+      end
+
+      def flatten(value, prefix, path, output)
+        return if value.nil? || private_path?(path)
+
+        case value
+        when Hash then flatten_mapping(value, prefix, path, output)
+        when Array
+          output["#{prefix}_COUNT"] = value.size.to_s
+          value.each_with_index { |child, index| flatten(child, "#{prefix}_#{index}", path + [index.to_s], output) }
+        else output[prefix] = value.to_s
+        end
+      end
+
+      def flatten_mapping(value, prefix, path, output)
+        value.each do |key, child|
+          flatten(child, "#{prefix}_#{key.upcase.gsub(/[^A-Z0-9_]/, '_')}", path + [key], output)
+        end
+      end
+
+      def validate_size!(environment, arguments)
+        strings = environment.map { |key, value| "#{key}=#{value}" } + arguments + [@path.to_s]
+        if strings.any? { |value| value.include?("\0") }
+          raise Error.new(@name, 'configuration environment or arguments contain a null byte')
+        end
+
+        return if fits?(strings)
+
+        raise Error.new(@name,
+                        'environment and arguments exceed the operating system size limit; ' \
+                        'reduce configuration or inherited environment')
+      end
+
+      def fits?(strings)
+        size = strings.sum { |value| value.bytesize + 1 + 8 }
+        limit = Etc.sysconf(Etc::SC_ARG_MAX) || 131_072
+        size < limit - 16_384 && strings.all? { |value| value.bytesize < 131_072 }
+      end
+    end
+  end
+end

data/lib/empeira/addons/error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Addons
+    class Error < Empeira::Error
+      attr_reader :exit_status
+
+      def initialize(name, message, exit_status: 1)
+        @exit_status = exit_status
+        super("Addon #{name}: #{message}")
+      end
+    end
+  end
+end