Clarify or implement runtime semantics for gateway.enabled and gateway.home
@Gucc111 is already working on this.
Since Jun 17, 2026.
- Dominant language
- TypeScript
- Stars
- 4k
- Forks
- 453
- Avg merge
- 12h 30m
- Merged PRs (30d)
- 46
Description
Problem
gateway.enabled and gateway.home can be represented/saved through the config/UI, but the runtime does not currently consume these fields.
This appears to be an accidental config/runtime contract mismatch rather than intentional behavior: users can save fields that look operational, but they do not affect gateway startup, lifecycle, or home directory resolution.
Current Behavior
gateway.enabledcan be present in config.gateway.homecan be present in config.- Runtime gateway parsing/startup does not use these fields.
- Gateway behavior is instead driven by other fields such as
bindAddress,port,idleSessionTimeout,staticAssetsPath, andmaxPerSessionMcpInstances. gateway.homeis not clearly connected to existingPILOT_HOMEpath resolution.gateway.enableddoes not affect an already-started CLI gateway process.
Expected Behavior
These fields should either be removed from the user-facing config surface or given explicit runtime semantics.
Possible intended semantics:
-
gateway.enabledandgateway.homeare not supported runtime controls:- Remove them from the UI/config editor, or mark them as reserved/unsupported.
- Avoid suggesting that changing them will affect runtime behavior.
-
gateway.enabledandgateway.homeare supported:- Define whether
gateway.homeis equivalent to or derived fromPILOT_HOME. - Define whether
gateway.enabledcontrols only UI-managed gateway lifecycle or also CLI startup. - Implement runtime behavior and status reporting accordingly.
- Define whether
Impact
Users may believe they can disable the gateway or switch the PilotDeck home directory through config, while the actual runtime continues unchanged. This is especially confusing for multi-instance setups, isolated test environments, and debugging config reload issues.
Evidence / Code Areas
Relevant areas to inspect:
- UI/config surface that saves
gateway.enabledandgateway.home - Runtime gateway config parser
- CLI gateway startup path
- Existing
PILOT_HOME/ PilotDeck home resolution helpers - Gateway status and reload reporting
Product Decision Needed
Please decide whether these fields are supported runtime controls or unsupported/reserved config fields.
Acceptance Criteria
gateway.enabledandgateway.homeno longer create false expectations.- Either the UI/config no longer exposes them as effective runtime controls, or runtime behavior explicitly supports them.
- If supported, documentation and tests cover the exact lifecycle/path semantics.
- Runtime status/API responses make the effective gateway state clear.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.