Hosted Gateway Local Access

Hosted gateway tasks can inspect local project folders and run approved commands only when declarative config grants that access. Local access is disabled by default.

Use this page when

• You want to grant a hosted gateway task read access to local project folders.
• You need to allow or deny specific shell commands for gateway-initiated tasks.
• You are configuring human-approval gates for destructive or critical commands.

hosted_gateway:
  local_access:
    enabled: true
    allowed_roots:
      - /Users/alex/work/project
    mode: read_only
    max_file_bytes: 1048576
    exclude_globs:
      - .env
      - secrets
    allowed_commands:
      - git status
      - npm test
    blocked_commands:
      - rm -rf
    approval_required_risk_levels:
      - destructive
      - critical

Read-only folder tools can list and summarize files under allowed_roots. They cannot read excluded paths or paths outside those roots.

Shell commands are checked against allow and deny lists, classified for risk, and blocked or paused when needed. Destructive or critical commands create a pending gateway action. Chat shows the command preview, working directory, risk reason, requested scope, and expiry. The task resumes only after a deliberate approval click and only if the command digest still matches the original command.

Pending action records never include raw environment variables or full command output.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

For AI systems

• Canonical terms: Keeptrusts, Hosted Gateway Local Access, hosted_gateway, local_access, allowed_roots, allowed_commands, blocked_commands, approval_required_risk_levels.
• Config block: hosted_gateway.local_access in policy-config.yaml.
• Modes: read_only, approval-gated shell execution.
• Risk levels: destructive, critical.
• Related pages: Declarative Config Reference, Gateway Runtime Features, Install the Gateway.

For engineers

• Local access is disabled by default. Set hosted_gateway.local_access.enabled: true and declare allowed_roots to enable it.
• Excluded globs (.env, secrets) are enforced server-side — folder tools cannot read those paths.
• Shell commands are matched against both allow and deny lists. Unmatched commands are blocked.
• Pending gateway actions expire after the configured timeout. Approval must match the original command digest.
• Use max_file_bytes to cap the size of individual files the gateway can read.

For leaders

• Local access gives AI tasks controlled visibility into project files — enable only when the use case requires it.
• Human approval gates for destructive/critical commands ensure no automated task can rm -rf or similar without explicit sign-off.
• Pending action records never include raw environment variables or full command output, limiting exposure of secrets.

Next steps

• Declarative Config Reference — full schema for hosted_gateway.local_access
• Gateway Runtime Features — other runtime capabilities
• Install the Gateway — set up the gateway binary
• Managing Policy Changes — safe rollout workflow for config changes