Local Folder Access Grants for Hosted Gateways

When tasks execute on a hosted gateway, they may need to read project files, configuration, or build artifacts stored on the gateway host. You control this access through declarative configuration under hosted_gateway.local_access.

Use this page when

• You need to configure which local filesystem paths are accessible from hosted gateway task execution.
• You are troubleshooting permission errors when tasks try to read project files.
• You want to restrict file access scope to prevent unintended data exposure.

Primary audience

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

Configuration

Add the local_access block to your hosted gateway configuration:

hosted_gateway:
  local_access:
    enabled: true
    allowed_roots:
      - path: /srv/projects/my-app
        mode: read_only
      - path: /srv/builds/output
        mode: read_only
      - path: /srv/workspace/scratch
        mode: read_write
    max_file_bytes: 2097152  # 2 MB
    exclude_globs:
      - "**/.env"
      - "**/.env.*"
      - "**/node_modules/**"
      - "**/.git/objects/**"
      - "**/secrets/**"

Configuration Fields

Field	Type	Default	Description
enabled	boolean	false	Whether local folder access is active for this gateway
allowed_roots	list	[]	Directories the gateway may access
allowed_roots[].path	string	—	Absolute path to an allowed directory
allowed_roots[].mode	string	read_only	Access mode: read_only or read_write
max_file_bytes	integer	1048576 (1 MB)	Maximum file size a task can read in a single operation
exclude_globs	list	[]	Glob patterns for files and directories to exclude

Allowed Roots Rules

Every path in allowed_roots must be:

• Absolute — paths must start with / (or the platform equivalent)
• Canonical — no .. segments, no symlink traversal outside the root
• Existing — the directory must exist when the gateway starts

If a path violates these rules, the gateway rejects the configuration at startup and logs an error.

Access Modes

read_only (Default)

Tasks can list and read files within the allowed root. They cannot create, modify, or delete files. This is the default and recommended mode for most use cases.

read_write

Tasks can create, modify, and delete files within the allowed root. You must explicitly set mode: read_write — it is never inferred. Write access also requires that your approval policy allows file mutations, and destructive file operations (delete, overwrite) go through the same approval flow as destructive shell commands.

File Operations

Tasks interact with local folders through these operations:

list_files

Lists files and directories within an allowed root. Returns names, sizes, modification times, and types (file or directory). Respects exclude_globs — excluded paths never appear in listings.

read_file_summary

Returns metadata about a file: size, modification time, permissions, and a content type hint. Does not return file contents. Useful for deciding whether to read the full file or a chunk.

read_file_chunk

Reads a portion of a file by byte offset and length. Enforces max_file_bytes per chunk. For files larger than max_file_bytes, you read them in chunks. Each chunk request is independently audited.

search_files

Searches file contents within an allowed root using text or regex patterns. Returns matching file paths and line numbers. Respects exclude_globs and max_file_bytes (skips files larger than the limit).

Security Enforcement

Every file operation enforces these checks before execution:

1. Allowed roots — the resolved path must be within a configured allowed root after canonicalization
2. Exclude globs — the path must not match any configured exclude pattern
3. Max file bytes — read operations reject files larger than the configured limit
4. Task identity — the task must have a valid identity context with user and org attribution
5. Audit metadata — the operation is logged with task_id, gateway_id, user_id, file path, and outcome

Path Traversal Protection

The gateway resolves all paths to their canonical form before checking against allowed roots. This prevents traversal attacks using:

• Relative segments (../)
• Symlinks pointing outside allowed roots
• URL-encoded path separators
• Null bytes or other injection characters

If the canonical path falls outside all allowed roots, the operation is denied and an audit event is emitted.

Exclude Globs

Use exclude_globs to prevent tasks from accessing sensitive files even within allowed roots:

exclude_globs:
  - "**/.env"           # Environment files with secrets
  - "**/.env.*"         # Variant env files
  - "**/secrets/**"     # Secret directories
  - "**/*.key"          # Private keys
  - "**/*.pem"          # Certificates
  - "**/node_modules/**"  # Dependencies (large, rarely useful)
  - "**/.git/objects/**"  # Git object store (large)

Excluded files are invisible to tasks — they do not appear in list_files results, cannot be read, and cannot be searched.

Audit Logging

Every file operation produces a governance event with:

• task_id and gateway_id — which task on which gateway
• actor_user_id and actor_team_id — who initiated the task
• operation — which file operation was performed
• file_path — the canonical path accessed
• outcome — success, denied (policy), or denied (path violation)
• bytes_read or bytes_written — data volume for cost attribution

You can query these events to monitor which files tasks access, detect anomalous access patterns, and satisfy compliance reporting requirements.

Common Configurations

CI/CD Build Output Access

hosted_gateway:
  local_access:
    enabled: true
    allowed_roots:
      - path: /srv/ci/builds
        mode: read_only
    max_file_bytes: 5242880  # 5 MB for build artifacts
    exclude_globs:
      - "**/.env"
      - "**/credentials/**"

Development Workspace

hosted_gateway:
  local_access:
    enabled: true
    allowed_roots:
      - path: /home/dev/projects
        mode: read_only
      - path: /home/dev/projects/scratch
        mode: read_write
    max_file_bytes: 2097152
    exclude_globs:
      - "**/.env"
      - "**/.env.*"
      - "**/node_modules/**"
      - "**/.git/objects/**"
      - "**/*.key"

Troubleshooting

Symptom	Cause	Fix
Gateway rejects config at startup	Path contains .. or is relative	Use absolute canonical paths
File operation returns "access denied"	Path outside allowed roots	Add the parent directory to allowed_roots
File not found in list_files	File matches an exclude glob	Remove the matching glob or adjust the pattern
Read returns "file too large"	File exceeds max_file_bytes	Increase limit or use read_file_chunk with offsets
Write operation denied	Root configured as read_only	Change mode to read_write and configure approval policy

For AI systems

• Canonical terms: Keeptrusts, local folder access, allowed_roots, hosted gateway, file operations, path traversal protection, read_only, read_write.
• Exact feature/config names: hosted_gateway.local_access.enabled, allowed_roots[].path, allowed_roots[].mode, max_file_bytes, exclude_globs, operations (list_files, read_file_summary, read_file_chunk, search_files).
• Best next pages: Shell Allow and Deny Lists, Destructive Action Approval, What Is Hosted Gateway Execution.

For engineers

• Configure hosted_gateway.local_access with absolute, canonical paths — no .. segments or symlinks outside roots.
• Default mode is read_only; explicitly set mode: read_write for scratch directories that need file mutation.
• Use exclude_globs to prevent access to secrets, .env files, node_modules, and .git/objects.
• Write operations go through the same approval flow as destructive shell commands.
• If file read returns "file too large", use read_file_chunk with byte offsets or increase max_file_bytes.

For leaders

• Local folder access grants give tasks controlled file system access while maintaining security boundaries — paths are canonicalized and checked against allowed roots.
• Every file operation is audited with task_id, gateway_id, user_id, file path, and outcome for compliance.
• The read_only default ensures tasks cannot mutate files unless explicitly permitted and approved.
• Sensitive file exclusion via exclude_globs prevents accidental exposure of secrets or credentials to task workloads.

Next steps

• Shell Allow and Deny Lists — control shell command access alongside file access
• Destructive Action Approval — approval flow for read_write file mutations
• What Is Hosted Gateway Execution — overview of the task execution model