### Dependencies Configuration Example (JSON)

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Example of specifying apt packages to be installed at container startup using the `dependencies` array in `settings.json`.

```json
{
  "dependencies": [
    "python3",
    "build-essential",
    "htop"
  ]
}
```

--------------------------------

### Global Dependencies Configuration Example (JSON)

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Example of a global settings file (`~/.hole/settings.json`) specifying default apt packages to be installed.

```json
{
  "dependencies": [
    "python3",
    "nodejs"
  ]
}
```

--------------------------------

### Install Hole via Wget (Shell Script)

Source: https://context7.com/lukashornych/hole/llms.txt

Installs the Hole CLI using wget to download and execute the installation script. Similar to the curl method, this ensures the latest version is installed and configured correctly.

```bash
# Install using wget
wget -qO- https://raw.githubusercontent.com/lukashornych/hole/main/install.sh | bash
```

--------------------------------

### Global Settings Example (JSON)

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Example of a global settings file (`~/.hole/settings.json`) defining default file exclusions, inclusions, and network domain whitelists.

```json
{
  "files": {
    "exclude": [".env", ".env.local"],
    "include": {
      "~/.npmrc": "/home/agent/.npmrc"
    }
  },
  "network": {
    "domainWhitelist": [
      "registry.npmjs.org"
    ]
  }
}
```

--------------------------------

### Per-Project Exclusions Example (JSON)

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Example of a per-project settings file (`.hole/settings.json`) specifying files and directories to be excluded from the agent's workspace.

```json
{
  "files": {
    "exclude": [
      ".env",
      ".env.local",
      "node_modules",
      "dist"
    ]
  }
}
```

--------------------------------

### Hole Configuration: Dependencies

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Example JSON configuration for specifying additional apt packages to be installed within the Docker container at startup. This ensures necessary tools are available for the agent.

```json
{
  "dependencies": ["python3", "build-essential", "htop"]
}
```

--------------------------------

### Complete Hole Project Configuration Example

Source: https://context7.com/lukashornych/hole/llms.txt

A comprehensive settings file combining all configuration options for a Node.js/Python project. Includes file exclusions/inclusions, network domain whitelisting, dependencies, and container resource limits.

```json
{
  "$schema": "https://raw.githubusercontent.com/lukashornych/hole/main/schema/settings.schema.json",
  "files": {
    "exclude": [
      ".env",
      ".env.local",
      ".env.production",
      "node_modules",
      "dist",
      "__pycache__",
      ".venv",
      "secrets"
    ],
    "include": {
      "~/.npmrc": "/home/agent/.npmrc",
      "~/.gitconfig": "/home/agent/.gitconfig"
    }
  },
  "network": {
    "domainWhitelist": [
      "registry.npmjs.org",
      "api.github.com",
      "pypi.org",
      "files.pythonhosted.org"
    ]
  },
  "dependencies": [
    "python3",
    "python3-pip",
    "nodejs",
    "npm"
  ],
  "container": {
    "memoryLimit": "8g",
    "memorySwapLimit": "12g"
  }
}
```

--------------------------------

### Project-Specific Domain Whitelist Example (JSON)

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Example of `settings.json` defining project-specific domains to be whitelisted for network access, in addition to default domains.

```json
{
  "files": {
    "exclude": [".env", "node_modules"]
  },
  "network": {
    "domainWhitelist": [
      "registry.npmjs.org",
      "api.github.com"
    ]
  }
}
```

--------------------------------

### Install Hole via Curl (Shell Script)

Source: https://context7.com/lukashornych/hole/llms.txt

Installs the Hole CLI using curl to download and execute the installation script. This script fetches the latest release, sets up the necessary directories, and adds a wrapper script to your PATH.

```bash
# Install using curl
curl -fsSL https://raw.githubusercontent.com/lukashornych/hole/main/install.sh | bash
```

--------------------------------

### File Inclusion Configuration Example (JSON)

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Configuration snippet for `files.include` in `settings.json`, demonstrating how to mount additional host files or directories into the sandbox.

```json
{
  "files": {
    "include": {
      "./shared-config": "/workspace/shared-config",
      "/home/user/data": "/data",
      "~/.npmrc": "/home/agent/.npmrc"
    }
  }
}
```

--------------------------------

### Install Hole CLI using curl or wget

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Provides installation instructions for the Hole CLI using either `curl` or `wget` to download and execute the installation script. It also includes instructions for adding the local bin directory to the system's PATH.

```shell
curl -fsSL https://raw.githubusercontent.com/lukashornych/hole/main/install.sh | bash
# or
wget -qO- https://raw.githubusercontent.com/lukashornych/hole/main/install.sh | bash

export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Specify Container Dependencies for Agent Startup

Source: https://context7.com/lukashornych/hole/llms.txt

Installs additional apt packages at container startup before the agent CLI begins. Ubuntu apt repository domains are automatically added to the proxy whitelist when dependencies are specified. This is useful for ensuring the agent has the necessary tools to run.

```json
{
  "dependencies": [
    "python3",
    "python3-pip",
    "build-essential",
    "nodejs",
    "npm",
    "htop"
  ]
}
```

--------------------------------

### Start AI Agent Sandbox (CLI)

Source: https://context7.com/lukashornych/hole/llms.txt

Starts an AI agent in an isolated Docker sandbox. Supports interactive CLI, debug mode (bash shell), and network access logging. Attaches to the agent and cleans up resources on exit.

```bash
# Start sandbox for Claude agent in current directory
hole start claude .

# Start sandbox with absolute path
hole start claude /path/to/project

# Start with debug mode - drops into bash shell instead of agent CLI
hole start claude . --debug

# Start with network access logging - writes accessed domains to log file on exit
hole start claude . --dump-network-access

# Combine flags
hole start claude /path/to/project --debug --dump-network-access
```

--------------------------------

### Start Hole Sandbox for Claude Agent

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Initiates a sandboxed environment for the Claude Code agent. This command sets up the necessary containers and networks, mounting the project directory for the agent to access. It requires the path to the project directory.

```bash
./hole.sh start claude /path/to/project

```

```bash
./hole.sh start claude .

```

--------------------------------

### Hole.sh Version Check and Update Mechanism

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Details the version checking and update process within `hole.sh`. It includes silent version checks during 'start' and 'version' commands and an 'update' command to fetch and install the latest version from GitHub. Configuration for GitHub repository and API is defined at the script's top.

```bash
# GITHUB_REPO="lukashornych/hole"
# GITHUB_API="https://api.github.com/repos/${GITHUB_REPO}"
# GITHUB_INSTALL_SCRIPT="https://raw.githubusercontent.com/${GITHUB_REPO}/main/install.sh"

# Example of silent version check logic (conceptual)
# if [ -f "version" ]; then
#   installed_version=$(cat version)
#   latest_version=$(curl -s --max-time 1 ${GITHUB_API}/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
#   if [ "$installed_version" != "$latest_version" ]; then
#     echo "A new version ($latest_version) is available. Run 'hole update' to install."
#   fi
# fi

# Example of update command logic (conceptual)
# if [ "$1" == "update" ]; then
#   # ... fetch latest version ...
#   # ... compare versions ...
#   # ... download and run install.sh ...
# fi
```

--------------------------------

### Check Hole Version (CLI)

Source: https://context7.com/lukashornych/hole/llms.txt

Displays the installed Hole version and checks for available updates. If an update is found, it suggests running the 'hole update' command.

```bash
hole version
# Output: hole 1.2.3
# Output: A new version of hole is available: 1.3.0 (installed: 1.2.3). Run 'hole update' to upgrade.
```

--------------------------------

### Hole CLI: Basic Commands

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Provides essential commands for interacting with the Hole CLI. Includes commands for displaying usage information, checking the installed version, and updating the tool to the latest release.

```shell
hole help
hole version
hole update
```

--------------------------------

### Hole Project Naming Convention Example

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Demonstrates the naming convention for Hole project containers, which combines a prefix with a sanitized project path, agent name, and instance ID. This ensures unique identification and separation of multiple sandboxes for the same project.

```bash
# Example: /Users/lho/www/oss/hole with claude agent
# Resulting container name: hole-users-lho-www-oss-hole-claude-a1b2c3
```

--------------------------------

### Hole Configuration: Container Resource Limits

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Example JSON configuration for setting resource limits for the Docker container, such as memory and swap limits. These settings help manage the resources consumed by the AI agent.

```json
{
  "container": {
    "memoryLimit": "8g",
    "memorySwapLimit": "12g"
  }
}
```

--------------------------------

### Hole CLI: Debug and Network Access Flags

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Demonstrates the use of command-line flags for the 'hole start' command. The `--debug` flag opens a bash shell for inspection, while `--dump-network-access` logs accessed domains upon exit.

```shell
hole start claude . --debug
hole start claude . --dump-network-access
```

--------------------------------

### Hole Configuration: Domain Whitelist

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Example JSON configuration to specify a whitelist of domains that the AI agent is allowed to access. This enhances network security by restricting outbound connections.

```json
{
  "network": {
    "domainWhitelist": ["registry.npmjs.org", "api.github.com"]
  }
}
```

--------------------------------

### Update Hole CLI (CLI)

Source: https://context7.com/lukashornych/hole/llms.txt

Downloads and installs the latest release of the Hole CLI from GitHub. This command ensures you have the most recent version with bug fixes and new features.

```bash
hole update
# Output: Checking for updates...
# Output: Updating hole: 1.2.3 -> 1.3.0
```

--------------------------------

### Hole Configuration: File Inclusions

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Example JSON configuration for including additional host files or directories into the sandbox. It maps host paths to absolute container paths, supporting `~` expansion and relative path resolution.

```json
{
  "files": {
    "include": {
      "~/.npmrc": "/home/agent/.npmrc",
      "./shared-config": "/workspace/shared-config",
      "/home/user/data": "/data"
    }
  }
}
```

--------------------------------

### Hole Configuration: File Exclusions

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Example JSON configuration for excluding specific files and directories from being accessible to the AI agent within the sandbox. These paths are mounted as `/dev/null` or empty volumes.

```json
{
  "files": {
    "exclude": [".env", ".env.local", "node_modules", "dist"]
  }
}
```

--------------------------------

### Start AI Agent Sandbox with Hole CLI

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Initiates an AI agent sandbox in a specified project directory. Supports agents like 'claude' and allows specifying the project path. The sandbox is ephemeral and destroyed upon exit.

```shell
hole start claude .
# or
hole start claude /path/to/project
```

--------------------------------

### Uninstall Hole via Wget (Shell Script)

Source: https://context7.com/lukashornych/hole/llms.txt

Removes the Hole CLI installation and all associated Docker volumes using wget to execute the uninstall script. This is an alternative method for cleanly removing the tool.

```bash
# Uninstall using wget
wget -qO- https://raw.githubusercontent.com/lukashornych/hole/main/uninstall.sh | bash
```

--------------------------------

### Uninstall Hole via Curl (Shell Script)

Source: https://context7.com/lukashornych/hole/llms.txt

Removes the Hole CLI installation and all associated Docker volumes using curl to execute the uninstall script. This provides a clean way to remove the tool and its data.

```bash
# Uninstall using curl
curl -fsSL https://raw.githubusercontent.com/lukashornych/hole/main/uninstall.sh | bash
```

--------------------------------

### Show Hole Help Information (CLI)

Source: https://context7.com/lukashornych/hole/llms.txt

Displays usage information and a list of available commands, agents, and options for the Hole CLI. This is useful for understanding how to use the tool.

```bash
hole help
# Output:
# Usage: hole {command} {agent} {path} [options]
#
# Commands:
#   start     Create a sandbox, attach to the agent CLI, and destroy on exit
#   update    Update hole to the latest release
#   help      Show this help message
#   version   Print the installed hole version
#
# Agents:
#   claude    Claude Code agent
#
# Options:
#   --debug                 Open a bash shell instead of the agent CLI
#   --dump-network-access   After the agent exits, write distinct accessed domains
#                           to {agent}-network-access-{id}.log in the project directory
```

--------------------------------

### Define Docker Compose Services for Sandbox Environment

Source: https://context7.com/lukashornych/hole/llms.txt

Sets up the sandbox environment with two services: a proxy for network filtering and the agent container. It configures build contexts, volumes, networks, health checks, and environment variables.

```yaml
services:
  # Network proxy with domain whitelist filtering
  proxy:
    build:
      context: .
      dockerfile: proxy/Dockerfile
    volumes:
      - ./proxy/tinyproxy.conf:/etc/tinyproxy/tinyproxy.conf:ro
      - ./proxy/allowed-domains.txt:/etc/tinyproxy/allowed-domains.txt:ro
    networks:
      - sandbox   # Internal network (no direct internet)
      - internet  # Bridge network with internet access
    healthcheck:
      test: ["CMD-SHELL", "nc -z localhost 8888"]
      interval: 2s
      timeout: 2s
      retries: 5

  # Claude Code CLI agent
  claude:
    build:
      context: .
      dockerfile: agents/claude/Dockerfile
    command: ["claude", "--dangerously-skip-permissions"]
    stdin_open: true
    tty: true
    volumes: 
      - hole-agent-home-claude:/home/agent  # Persistent credentials
      - ${PROJECT_DIR:-.}:/workspace        # Project files
    environment:
      - HTTP_PROXY=http://proxy:8888
      - HTTPS_PROXY=http://proxy:8888
      - NO_PROXY=localhost,127.0.0.1
    depends_on:
      proxy:
        condition: service_healthy
    networks:
      - sandbox  # Internal only - no direct internet

networks:
  sandbox:
    internal: true   # No external connectivity
  internet:
    driver: bridge   # Normal bridge with internet

volumes:
  hole-agent-home-claude:
    external: true   # Created by hole.sh, survives teardown

```

--------------------------------

### Add Allowed Domains to Proxy Configuration

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Demonstrates how to add new domain patterns to the proxy's whitelist. These patterns are used to control which external domains the AI agent can access. After editing the file, the proxy service needs to be rebuilt and restarted.

```bash
docker compose -p <project-name> up -d --build proxy

```

--------------------------------

### Tinyproxy Configuration for Network Filtering

Source: https://context7.com/lukashornych/hole/llms.txt

Provides the Tinyproxy configuration for the network proxy service. It includes settings for port, listening address, timeouts, allowed connections, and enables a filter for a specified list of allowed domains with default-deny.

```conf
User nobody
Group nobody

Port 8888
Listen 0.0.0.0
Timeout 600

Allow 0.0.0.0/0

ConnectPort 443
ConnectPort 80

Filter "/etc/tinyproxy/allowed-domains.txt"
FilterDefaultDeny Yes
FilterExtended On
FilterURLs Off

LogLevel Info
MaxClients 50

```

--------------------------------

### Hole Per-Project Settings Location (CLI)

Source: https://context7.com/lukashornych/hole/llms.txt

Indicates the location for project-specific Hole configuration settings. These settings are merged with global settings, with project values taking precedence.

```bash
# Per-project settings location (in project root)
.hole/settings.json
```

--------------------------------

### Hole Global Settings Location (CLI)

Source: https://context7.com/lukashornych/hole/llms.txt

Specifies the default location for global Hole configuration settings. This file is used to apply settings across all projects unless overridden by per-project settings.

```bash
# Global settings location
~/.hole/settings.json
```

--------------------------------

### Add Local Bin to PATH (Shell)

Source: https://context7.com/lukashornych/hole/llms.txt

Configures your shell environment to include the Hole executable directory in your system's PATH. This allows you to run the 'hole' command from any location in your terminal.

```bash
# Add ~/.local/bin to PATH if not already present (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Uninstall Hole CLI using curl or wget

Source: https://github.com/lukashornych/hole/blob/dev/README.md

Provides uninstallation instructions for the Hole CLI using either `curl` or `wget` to download and execute the uninstallation script. Ensure any running sandboxes are exited before uninstalling.

```shell
curl -fsSL https://raw.githubusercontent.com/lukashornych/hole/main/uninstall.sh | bash
# or
wget -qO- https://raw.githubusercontent.com/lukashornych/hole/main/uninstall.sh | bash
```

--------------------------------

### Agent Home Volume Management in Docker Compose

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Explains the lifecycle and management of persistent Docker named volumes used for agent home directories. These volumes are created on first use, populated from the Docker image, survive sandbox teardown, and are declared as external in `docker-compose.yml` to prevent accidental removal.

```yaml
# Example snippet from docker-compose.yml (conceptual)
# volumes:
#   hole-agent-home-claude:
#     external: true
```

--------------------------------

### Hole File Inclusions Configuration (JSON)

Source: https://context7.com/lukashornych/hole/llms.txt

Specifies additional host files or directories to be mounted into the AI agent's sandbox. Supports various path formats for host locations and requires absolute paths for container locations.

```json
{
  "files": {
    "include": {
      "~/.npmrc": "/home/agent/.npmrc",
      "~/.gitconfig": "/home/agent/.gitconfig",
      "./shared-config": "/workspace/shared-config",
      "/home/user/datasets": "/data"
    }
  }
}
```

--------------------------------

### Add New Agent Type to Hole Project

Source: https://github.com/lukashornych/hole/blob/dev/CLAUDE.md

Outlines the steps required to integrate a new AI agent type into the Hole project. This involves creating a Dockerfile for the agent, defining its service in Docker Compose, configuring network access, updating domain whitelists, and modifying the CLI script.

```bash
# Example: Create agents/<agent-name>/Dockerfile
# Add service definition in docker-compose.yml
# Configure proxy dependency and network
# Add allowed domains to proxy/allowed-domains.txt
# Update hole.sh VALID_AGENTS array
# Update uninstall.sh agents array

```

--------------------------------

### Hole File Exclusions Configuration (JSON)

Source: https://context7.com/lukashornych/hole/llms.txt

Defines sensitive files and directories to be excluded from the AI agent's sandbox. Excluded files are mounted as /dev/null, and directories as empty volumes.

```json
{
  "$schema": "https://raw.githubusercontent.com/lukashornych/hole/main/schema/settings.schema.json",
  "files": {
    "exclude": [
      ".env",
      ".env.local",
      ".env.production",
      "node_modules",
      "dist",
      ".git/config",
      "secrets"
    ]
  }
}
```

--------------------------------

### Default Allowed Domains for Proxy Filter

Source: https://context7.com/lukashornych/hole/llms.txt

Lists the default domains allowed by the proxy's whitelist filter, which uses regex patterns. By default, only domains essential for Claude agent operation are permitted. Dots are escaped for regex.

```text
# Claude agent
api\.anthropic\.com
claude\.ai
platform\.claude\.com

```

--------------------------------

### Hole Settings Schema Definition (JSON)

Source: https://context7.com/lukashornych/hole/llms.txt

The JSON Schema defining the structure and validation rules for Hole AI agent sandbox settings files. It specifies properties for file inclusions/exclusions, network domain whitelisting, dependencies, and container resource limits.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Hole Settings",
  "description": "Configuration for the Hole AI agent sandbox",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "description": "JSON Schema reference for IDE autocompletion"
    },
    "files": {
      "type": "object",
      "properties": {
        "exclude": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 }
        },
        "include": {
          "type": "object",
          "additionalProperties": {
            "type": "string",
            "pattern": "^/"
          }
        }
      }
    },
    "network": {
      "type": "object",
      "properties": {
        "domainWhitelist": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 }
        }
      }
    },
    "dependencies": {
      "type": "array",
      "items": { "type": "string", "minLength": 1 }
    },
    "container": {
      "type": "object",
      "properties": {
        "memoryLimit": { "type": "string", "minLength": 1 },
        "memorySwapLimit": { "type": "string", "minLength": 1 }
      }
    }
  }
}
```

--------------------------------

### Configure Domain Whitelist for Agent Network Access

Source: https://context7.com/lukashornych/hole/llms.txt

Allows the agent to access additional domains beyond the defaults. Dots are automatically escaped for the proxy regex filter. This configuration is part of the agent's settings.

```json
{
  "network": {
    "domainWhitelist": [
      "registry.npmjs.org",
      "api.github.com",
      "pypi.org",
      "files.pythonhosted.org",
      "crates.io"
    ]
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.