### Configure Campers with Ansible Playbook

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

An example `campers.yaml` configuration demonstrating how to integrate Ansible playbooks for robust environment setup. This playbook installs Nginx on all hosts.

```yaml
playbooks:
  web-server:
    - name: Install Nginx
      hosts: all
      become: true
      tasks:
        - apt: {name: nginx, state: present}

camps:
  web:
    ansible_playbooks: [web-server]
```

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

### Run Local Web Server

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Starts a simple HTTP server on the remote Campers machine, accessible locally via port forwarding. This demonstrates running web applications within the Campers environment.

```python
python -m http.server 8000
```

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

### Configure Campers Instance Type and Disk Size

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

An example `campers.yaml` configuration snippet showing how to set default region, instance type, and disk size for the Campers environment. This allows customization of the cloud instance.

```yaml
defaults:
  region: us-east-1
  instance_type: t3.xlarge  # Upgrade to 4 vCPUs, 16GB RAM
  disk_size: 50
```

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

### Run Campers with uv

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Executes the Campers environment using the `uvx` command, recommended for a zero-installation experience. This command initiates the Campers runtime.

```bash
uvx campers run
```

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

### Data Science Setup with GPU and Jupyter (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/examples.md

This setup is designed for deep learning tasks, provisioning a GPU instance and installing necessary libraries like PyTorch. It forwards Jupyter Lab to the local browser for interactive work and can be configured for batch jobs.

```yaml
vars:
  project: deep-learning
  remote_dir: /home/ubuntu/${project}

playbooks:
  gpu-setup:
    - name: Install Drivers
      hosts: all
      become: true
      tasks:
        - name: Install CUDA
          apt: {name: nvidia-cuda-toolkit, state: present}
        - name: Install PyTorch
          pip: {name: [torch, torchvision, jupyterlab, tensorboard]}

camps:
  experiment:
    instance_type: g5.xlarge  # NVIDIA A10G
    region: us-west-2
    disk_size: 200
    
    # Forward Jupyter (8888)
    ports: [8888]
    
    ansible_playbooks: [gpu-setup]
    
    # Auto-start Jupyter
    command: jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root

  training:
    instance_type: p3.2xlarge # V100 GPU
    region: us-west-2
    ports: [6006] # TensorBoard
    ansible_playbooks: [gpu-setup]
    
    # Pull data on every start
    startup_script: |
      cd ${remote_dir}
      dvc pull data/

    # Run background monitoring + training
    command: |
      tensorboard --logdir logs --port 6006 &
      python train_model.py
```

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

### Install Mutagen on Windows

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Installs Mutagen, a file synchronization tool essential for high-performance file syncing in Campers, using Scoop on Windows.

```bash
scoop install mutagen
```

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

### Ansible Playbook for Python Development Environment Setup (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

An example Ansible playbook for setting up a Python development environment. It installs `uv` (a Python package installer) by downloading and executing an installation script. The `creates` argument ensures the task is idempotent.

```yaml
playbooks:
  # A playbook for Python dev
  python-dev:
    - name: Python environment
      hosts: all
      tasks:
        - name: Install uv
          shell: curl -LsSf https://astral.sh/uv/install.sh | sh
          args:
            creates: ~/.local/bin/uv
```

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

### Web Development with Docker Compose (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/examples.md

This setup allows running a backend, frontend, and database in the cloud using Docker Compose, providing full control over the development environment. It forwards common web development ports.

```yaml
camps:
  webapp:
    instance_type: t3.medium

    # Forward Frontend, API, and DB admin ports
    ports:
      - 3000  # React
      - 8000  # FastAPI
      - 5432  # Postgres

    setup_script: |
      # Install Docker & Compose
      curl -fsSL https://get.docker.com | sh
      sudo usermod -aG docker ubuntu

    command: docker compose up
```

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

### Install Campers with pip

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Installs the Campers package using pip, the standard Python package installer. This is an alternative to the recommended uv installation method.

```bash
pip install campers
```

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

### Setup Caddy for HTTPS Demos (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/examples.md

This Ansible playbook configures Caddy on a Campers instance to act as a reverse proxy, enabling HTTPS with automatic Let's Encrypt certificate provisioning. It installs Caddy, copies a Caddyfile configuration to proxy requests to a local application port (e.g., 3000), and reloads the Caddy service. This provides a production-quality, secure URL for demos.

```yaml
playbooks:
  caddy-proxy:
    - name: Setup Caddy
      hosts: all
      become: true
      tasks:
        - apt: {name: caddy, state: present, update_cache: true}
        - copy:
            dest: /etc/caddy/Caddyfile
            content: |
              {{ public_ip | replace('.', '-') }}.sslip.io {
                reverse_proxy localhost:3000
              }
          notify: Reload Caddy
      handlers:
        - name: Reload Caddy
          systemd: {name: caddy, state: reloaded}

camps:
  demo-https:
    instance_type: t3.medium
    public_ports: [80, 443]
    ansible_playbooks: [caddy-proxy]
    command: npm start
```

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

### Expose Client Demos with Public Ports (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/examples.md

This configuration snippet demonstrates how to expose specific ports (e.g., 80, 3000) of a Campers instance to the public internet. It also includes a setup script for Docker and defines a command to run the application. This allows clients to access the running application via its public IP address.

```yaml
vars:
  project: client-demo
  remote_dir: /home/ubuntu/${project}

camps:
  demo:
    instance_type: t3.medium

    # Public access for clients
    public_ports: [80, 3000]

    # Also tunnel to localhost for your own dev access
    ports: [3000]

    setup_script: |
      curl -fsSL https://get.docker.com | sh
      sudo usermod -aG docker ubuntu

    command: docker compose up
```

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

### Initialize Campers Environment

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Initializes a new Campers environment by creating a `campers.yaml` configuration file. This file defines the infrastructure as code for the environment.

```bash
campers init
```

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

### Run Campers Environment

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Starts the Campers environment, which includes provisioning an AWS instance, establishing a Mutagen file sync session, and providing an SSH shell to the remote machine.

```bash
campers run
```

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

### Install Mutagen on macOS

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Installs Mutagen, a file synchronization tool essential for high-performance file syncing in Campers, using Homebrew on macOS.

```bash
brew install mutagen-io/mutagen/mutagen
```

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

### Ansible Playbook for Base System Setup (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

An example of an Ansible playbook defined within the `playbooks` section of `campers.yaml`. This specific playbook, named `base`, installs common system packages like git, htop, tmux, and curl using the `apt` module.

```yaml
playbooks:
  # A simple playbook to install tools
  base:
    - name: Base system setup
      hosts: all
      become: true
      tasks:
        - name: Install packages
          apt: {name: [git, htop, tmux, curl], state: present}
```

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

### Campers Installation and Initialization Commands

Source: https://github.com/kamilc/campers/blob/main/README.md

Provides essential commands for installing and setting up the Campers tool. It includes installation instructions using pip and uv, as well as commands for initializing a Campers configuration in the current directory and spinning up a camp.

```bash
# Install via pip
pip install campers

# Or run instantly with uv (recommended)
uvx campers run

# Initialize a configuration in your current directory
campers init

# Spin up your camp
campers run
```

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

### Campers CLI Commands Example

Source: https://github.com/kamilc/campers/blob/main/README.md

Provides examples of using the 'campers' command-line interface to manage different defined environments. Includes commands for running specific camps, listing all camps with their status and costs, and demonstrates the expected output format for the 'list' command.

```bash
# Start the cheap coding environment
campers run dev

# Switch to the GPU machine for notebooks
campers run experiment

# Launch the heavy training job
campers run training

# Start a client demo (share the public IP with clients)
campers run demo

# Check status of all your camps (showing estimated monthly costs)
campers list
# ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
# ┃ NAME               ┃ INSTANCE-ID  ┃ STATUS     ┃ REGION         ┃ COST/MONTH           ┃
# ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
# │ campers-dev        │ i-0abc123def │ running    │ us-east-1      │ $29.95/month         │
# │ campers-experiment │ i-0def456abc │ stopped    │ us-east-1      │ $4.00/month          │
# └────────────────────┴──────────────┴────────────┴────────────────┴──────────────────────┘
```

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

### Campers Lifecycle Scripts Example (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Illustrates the use of lifecycle scripts within a `camp` configuration in `campers.yaml`. This example for a `training` camp specifies Ansible playbooks for provisioning (`ansible_playbooks`), a startup script for pulling data and activating environments (`startup_script`), and the main command to execute.

```yaml
camps:
  training:
    # 1. Install system deps
    ansible_playbooks: [python-setup]
    
    # 2. Pull latest data (every run)
    startup_script: |
      cd ${remote_dir}
      dvc pull data/
      source .venv/bin/activate
    
    # 3. Run the job
    command: python train.py
```

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

### Pytest Fixture Example (`conftest.py`)

Source: https://github.com/kamilc/campers/blob/main/tests/README.md

Demonstrates a Python function for a Pytest unit test that utilizes a mock AWS fixture to create an EC2 instance and assert its state. This showcases fixture usage for test setup and assertions.

```python
def test_ec2_instance_launch(mock_aws: MockEC2) -> None:
    instance = mock_aws.create_instance("test-instance")
    assert instance.state == "running"

```

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

### SSH Command for VS Code Remote SSH

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

An example SSH command provided by Campers to connect to the remote instance. This command can be used directly in VS Code's Remote Explorer to establish a remote connection.

```bash
ssh -i /path/to/key.pem ubuntu@1.2.3.4
```

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

### Configure AWS Credentials

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Sets up AWS credentials for interacting with AWS services. This can be done via the `aws configure` command or by exporting the AWS_PROFILE environment variable.

```bash
aws configure
# Or export AWS_PROFILE=my-profile
```

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

### Campers Configuration File Structure (YAML)

Source: https://context7.com/kamilc/campers/llms.txt

An example of a complete `campers.yaml` file demonstrating various configuration options, including variable definitions, Ansible playbooks, global defaults, and specific camp configurations for different environments.

```yaml
# campers.yaml

# Define reusable variables
vars:
  project_name: ml-pipeline
  remote_base: /home/ubuntu
  remote_path: "${remote_base}/${project_name}"

# Define reusable Ansible playbooks
playbooks:
  python-setup:
    - name: Install Python tools
      hosts: all
      tasks:
        - name: Install pip packages
          pip:
            name:
              - numpy
              - pandas
              - jupyter
            state: present

  cuda-setup:
    - name: Install CUDA toolkit
      hosts: all
      tasks:
        - name: Install CUDA drivers
          apt:
            name: nvidia-cuda-toolkit
            state: present

# Global defaults applied to all camps
defaults:
  region: us-east-1
  instance_type: t3.medium
  disk_size: 50
  include_vcs: false
  ignore:
    - "*.pyc"
    - "__pycache__"
    - "*.log"
    - ".DS_Store"
    - "node_modules"
  env_filter:
    - "^AWS_.*"
    - "^GITHUB_.*"
    - "^WANDB_API_KEY"
  ssh_allowed_cidr: "0.0.0.0/0"

# Machine configurations
camps:
  # Development environment
  dev:
    instance_type: t3.large
    disk_size: 100
    ports: [8000, 5432]
    command: |
      cd ${remote_path}
      docker-compose up

  # Jupyter notebook environment
  experiment:
    instance_type: g4dn.xlarge
    ami:
      query:
        name: "Deep Learning Base AMI (Ubuntu*)*"
        owner: "amazon"
    ports: [8888]
    ansible_playbooks: [python-setup]
    startup_script: |
      cd ${remote_path}
      pip install -r requirements.txt
    command: |
      cd ${remote_path}
      jupyter lab --ip=0.0.0.0 --port=8888 --no-browser

  # Training environment with public access
  training:
    instance_type: p3.2xlarge
    disk_size: 500
    region: us-west-2
    ports: [6006, 8080]
    public_ports: [6006]
    public_ports_allowed_cidr: "203.0.113.0/24"
    ansible_playbooks: [python-setup, cuda-setup]
    startup_script: |
      cd ${remote_path}
      dvc pull data/
    command: |
      cd ${remote_path}
      tensorboard --logdir logs --port 6006 &
      python train_model.py

  # Demo environment with custom sync paths
  demo:
    instance_type: t3.small
    public_ports: [80, 443]
    sync_paths:
      - local: ./frontend
        remote: /home/ubuntu/app/frontend
      - local: ./backend
        remote: /home/ubuntu/app/backend
    command: |
      cd /home/ubuntu/app
      npm start

```

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

### Define Client Demo Environment Configuration

Source: https://github.com/kamilc/campers/blob/main/README.md

Configures a 'demo' camp for client demonstrations, using a standard instance type. It opens public ports for external access, allowing clients to connect via the instance's public IP, and runs an npm start command.

```yaml
demo:
  instance_type: t3.medium
  # Open ports for external access (clients can hit the public IP)
  public_ports: [80, 3000]
  command: npm start
```

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

### Heavy Compilation Environment (Rust/C++) (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/examples.md

Offloads long compilation times to a high-core CPU instance. This configuration sets up Rust and C++ build tools, enabling efficient compilation of large projects.

```yaml
vars:
  project: rust-engine
  remote_dir: /home/ubuntu/${project}

camps:
  builder:
    instance_type: c6a.12xlarge  # 48 vCPUs!
    disk_size: 50

    setup_script: |
      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
      sudo apt-get install -y build-essential clang

    command: cargo build --release
```

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

### Define Training Environment Configuration (TensorBoard)

Source: https://github.com/kamilc/campers/blob/main/README.md

Sets up a 'training' camp for heavy training jobs, using a powerful GPU instance. It forwards TensorBoard to localhost:6006, includes Ansible playbooks for setup, and defines a startup script for data pulling and a command to run TensorBoard in the background alongside the main training script.

```yaml
training:
  instance_type: p3.2xlarge
  # Forward TensorBoard to localhost:6006
  ports: [6006]
  ansible_playbooks: [python-setup, deep-learning]

  # Run every time the instance starts (e.g., pull latest data)
  startup_script: |
    cd ${remote_path}
    dvc pull data/

  # Run background monitoring and main training script
  command: |
    cd ${remote_path}
    tensorboard --logdir logs --port 6006 &
    python train_model.py
```

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

### Secure Workstation for Data Residency Compliance (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/examples.md

This configuration ensures that sensitive data remains within a specific geographic region by provisioning the workstation in the same region. It filters environment variables to prevent accidental leakage of PII or PHI.

```yaml
vars:
  project: sensitive-analysis
  remote_dir: /home/ubuntu/${project}

defaults:
  # STRICTLY enforce the region where data resides
  region: eu-central-1  # Frankfurt (GDPR strict)
  
  # Filter out all environment variables to prevent accidental leakage
  # Only allow specific, safe variables
  env_filter:
    - ^SAFE_VAR_.*

camps:
  secure-workstation:
    instance_type: m5.2xlarge
    disk_size: 100
    
    command: |
      echo "Connected to secure workstation in eu-central-1."
      echo "Data analysis can proceed without downloading PII."
      bash
```

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

### Start Stopped Campers Instance

Source: https://context7.com/kamilc/campers/llms.txt

Resumes a stopped Campers instance and provides its new public IP address. Can be started using the camp name or instance ID. Shows cost impact and instructions for reconnecting.

```bash
# Start by camp name
campers start training

# Start by instance ID
campers start i-0abc123def456

# Example output:
# Instance i-0abc123def has been successfully started.
#   Public IP: 54.123.45.67
# 💰 Cost Impact:
#   Previous: $4.00/month
#   New: $3,060.00/month
#   Increase: $3,056.00/month
# To establish SSH/Mutagen/ports: campers run training
```

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

### Manage Mutagen Sync Sessions

Source: https://context7.com/kamilc/campers/llms.txt

This snippet demonstrates how to interact with Mutagen for synchronizing files with a remote session. It includes waiting for initial synchronization, checking the sync status, and terminating the session. Ensure Mutagen is installed and configured for the session.

```python
import mutagen

session_name = "your_session_name"

# Wait for initial synchronization to complete
try:
    mutagen.wait_for_initial_sync(session_name, timeout=300)
    print("Initial sync completed")
except RuntimeError as e:
    print(f"Sync timeout: {e}")

# Monitor sync status
status = mutagen.get_sync_status(session_name)
print(f"Sync status: {status}")
# Example outputs:
# "Watching for changes"
# "Staging files on beta (Staged entries (alpha): 45)"

# Terminate session when done
mutagen.terminate_session(
    session_name=session_name,
    ssh_wrapper_dir="/tmp/campers",
    host="54.123.45.67"
)
print("Sync session terminated")
```

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

### Run Campers with AWS Profile (Bash)

Source: https://github.com/kamilc/campers/blob/main/docs/examples.md

This bash command demonstrates how to set an AWS profile environment variable before running Campers. This allows the remote instance, configured with the `AWS_PROFILE` sync, to automatically use the specified AWS profile for subsequent AWS CLI commands executed on the instance.

```bash
export AWS_PROFILE=dev-account
campers run
# On remote: aws s3 ls (uses dev-account profile)
```

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

### Launch EC2 Instance using Campers (Python)

Source: https://context7.com/kamilc/campers/llms.txt

Provision an EC2 instance using the Campers Python library. The `EC2Manager` handles automatic AMI resolution, key pair creation, and security group setup for a specified region.

```python
from campers.providers.aws.compute import EC2Manager

# Initialize EC2 manager for specific region
ec2_manager = EC2Manager(region="us-east-1")

```

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

### Sync AWS Credentials with Campers (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/examples.md

This configuration demonstrates how to sync local AWS credentials (`~/.aws` directory) and project code to a remote Campers instance. It forwards the `AWS_PROFILE` environment variable, allowing the remote instance to use specific AWS profiles for commands. This is useful for managing multiple AWS accounts or roles but carries a security implication as all local profiles are copied.

```yaml
defaults:
  env_filter:
    # Forward the profile name env var
    - AWS_PROFILE

  sync_paths:
    # 1. Sync your code
    - local: .
      remote: /home/ubuntu/${project}
    
    # 2. Sync your AWS credentials
    - local: ~/.aws
      remote: /home/ubuntu/.aws
      ignore:
        - "cli/cache" # Don't sync CLI cache junk
```

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

### Create Mutagen Sync Session in Python

Source: https://context7.com/kamilc/campers/llms.txt

Establishes bidirectional file synchronization between local and remote paths using MutagenManager. This function handles checking Mutagen installation, cleaning up orphaned sessions, and creating new synchronization sessions with specified paths, host details, username, key file, ignore patterns, and SSH wrapper configurations.

```python
from campers.services.sync import MutagenManager

mutagen = MutagenManager()

# Check if Mutagen is installed
try:
    mutagen.check_mutagen_installed()
except RuntimeError as e:
    print(f"Mutagen not available: {e}")
    exit(1)

# Clean up any orphaned sessions from previous runs
session_name = "campers-abc123"
mutagen.cleanup_orphaned_session(session_name)

# Create synchronization session
try:
    mutagen.create_sync_session(
        session_name=session_name,
        local_path=".",
        remote_path="/home/ubuntu/project",
        host="54.123.45.67",
        key_file="/home/user/.campers/keys/abc123.pem",
        username="ubuntu",
        ignore_patterns=["*.pyc", "__pycache__", "*.log", ".DS_Store"],
        include_vcs=False,
        ssh_wrapper_dir="/tmp/campers",
        ssh_port=22
    )
    print("Sync session created successfully")
except RuntimeError as e:
    print(f"Failed to create sync: {e}")
```

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

### Campers YAML Configuration Example

Source: https://github.com/kamilc/campers/blob/main/README.md

This YAML configuration defines settings for Campers, including reusable variables for project names and remote paths, and specifies Ansible playbooks for setting up Python tools and deep learning libraries on the remote instance.

```yaml
# campers.yml

# Define reusable variables to keep config clean
vars:
  project_name: my-ml-project
  # Use standard linux paths
  remote_path: /home/ubuntu/${project_name}

# Define reusable Ansible playbooks (idempotent setup)
playbooks:
  python-setup:
    - name: Install Python Tools
      hosts: all
      tasks:
        - pip: {name: [numpy, pandas, jupyter], state: present}

  deep-learning:
    - name: Install PyTorch & TensorBoard
      hosts: all
      tasks:
        - pip: {name: [torch, torchvision, tensorboard], state: present}

```

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

### Camp Configuration for Amazon Linux Instance (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

An example `camp` configuration in `campers.yaml` for launching an Amazon Linux 2023 instance. It specifies `ec2-user` as the `ssh_username` and uses a dynamic query to find the appropriate Amazon Linux 2023 AMI.

```yaml
camps:
  amazon-linux:
    ssh_username: ec2-user
    ami:
      query: {name: "al2023-ami-*", owner: "amazon"}
```

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

### Manage EC2 Instance Lifecycle in Python

Source: https://context7.com/kamilc/campers/llms.txt

Performs lifecycle operations on EC2 instances, including stopping, starting, and terminating them, using the EC2Manager. It handles potential errors during these operations and provides feedback on the instance's state changes. Termination also includes cleanup of associated resources.

```python
from campers.providers.aws.compute import EC2Manager

ec2_manager = EC2Manager(region="us-east-1")

instance_id = "i-0abc123def456"

# Stop instance
try:
    result = ec2_manager.stop_instance(instance_id)
    print(f"Stopped: {result['state']}")
except RuntimeError as e:
    print(f"Failed to stop: {e}")

# Start instance
try:
    result = ec2_manager.start_instance(instance_id)
    print(f"Started with new IP: {result['public_ip']}")
    print(f"Key file: {result['key_file']}")
except RuntimeError as e:
    print(f"Failed to start: {e}")

# Terminate instance and clean up resources
try:
    ec2_manager.terminate_instance(instance_id)
    print("Instance terminated and resources cleaned up")
except RuntimeError as e:
    print(f"Failed to terminate: {e}")

ec2_manager.close()
```

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

### Destroy Campers Environment

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Terminates the Campers instance and deletes associated resources, including the disk. This completely stops all costs associated with the environment.

```bash
campers destroy
```

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

### Launch and Connect to Cloud Instance

Source: https://context7.com/kamilc/campers/llms.txt

Provisions a cloud instance with file synchronization and port forwarding. Can be done programmatically with the Python SDK or via the CLI. Supports specifying camp names, instance types, disk sizes, regions, and ports to forward. JSON output is available.

```python
from campers import Campers

# Initialize CLI programmatically
campers = Campers()

# Launch instance with default configuration
result = campers.run()

# Launch specific camp configuration
result = campers.run(camp_name="training")

# Override configuration parameters
result = campers.run(
    camp_name="dev",
    instance_type="t3.xlarge",
    disk_size=100,
    region="us-west-2",
    port=[8888, 6006],
    json_output=True
)

# Output:
# {
#   "instance_id": "i-0abc123def456",
#   "public_ip": "54.123.45.67",
#   "state": "running",
#   "key_file": "/home/user/.campers/keys/abc123.pem",
#   "security_group_id": "sg-0123456789",
#   "launch_time": "2025-01-15T10:30:00Z"
# }
```

```bash
# Launch with configuration file (campers.yaml)
campers run

# Launch specific camp
campers run training

# Override instance type and region
campers run --instance-type t3.xlarge --region us-west-2

# Forward multiple ports
campers run experiment --port 8888 --port 6006

# Use plain mode (no TUI)
campers run --plain

# Get JSON output
campers run dev --json-output
```

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

### Stop Campers Environment

Source: https://github.com/kamilc/campers/blob/main/docs/getting-started.md

Shuts down the running Campers instance while preserving data. This is a temporary stop, allowing for later resumption without losing work.

```bash
campers stop
```

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

### Launch EC2 Instance with Configuration

Source: https://context7.com/kamilc/campers/llms.txt

Launches an EC2 instance based on a provided configuration dictionary. This process includes creating necessary resources like key pairs and security groups. It handles potential configuration errors and launch failures. The function returns details of the launched instance.

```python
config = {
    "instance_type": "t3.medium",
    "disk_size": 50,
    "region": "us-east-1",
    "camp_name": "my-dev",
    "ssh_allowed_cidr": "0.0.0.0/0",
    "public_ports": [8888, 6006],
    "public_ports_allowed_cidr": "203.0.113.0/24",
}

try:
    instance_details = ec2_manager.launch_instance(
        config=config,
        instance_name="campers-my-dev-20250115"
    )
    print(f"Launched: {instance_details['instance_id']}")
    print(f"IP: {instance_details['public_ip']}")
    print(f"Key: {instance_details['key_file']}")
    print(f"State: {instance_details['state']}")
except ValueError as e:
    print(f"Configuration error: {e}")
except RuntimeError as e:
    print(f"Launch failed: {e}")

ec2_manager.close()
```

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

### Initialize Campers Configuration

Source: https://context7.com/kamilc/campers/llms.txt

Creates a default `campers.yaml` configuration file in the current directory. The `--force` flag overwrites an existing file.

```bash
# Create campers.yaml with default template
campers init

# Force overwrite existing configuration
campers init --force
```

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

### List All Campers Instances

Source: https://context7.com/kamilc/campers/llms.txt

Displays all instances managed by Campers, including cost estimates. Can filter by region. Provides a summary of total estimated monthly cost.

```bash
# List all instances across all regions
campers list

# List instances in specific region
campers list --region us-east-1

# Example output:
# NAME                 INSTANCE-ID          STATUS       REGION          TYPE            LAUNCHED     COST/MONTH
# ---------------------------------------------------------------------------------------------------------------
# campers-training     i-0abc123def         running      us-east-1       p3.2xlarge      2h ago       $3,060.00/month
# campers-dev          i-0def456abc         stopped      us-west-2       t3.medium       1d ago       $4.00/month
#
# Total estimated cost: $3,064.00/month
```

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

### Behave Configuration (`behave.ini`)

Source: https://github.com/kamilc/campers/blob/main/tests/README.md

Sets up Behave for integration tests, specifying the directory for feature files and disabling hook capturing to address issues with older Behave versions. This configuration is crucial for running BDD tests.

```ini
[behave]
paths = features/
capture_hooks = false

```

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

### Restrict SSH Access to Specific CIDR Block (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Configures network security by setting `ssh_allowed_cidr` within the `defaults` section of `campers.yaml`. This example restricts SSH access (port 22) to a specific IP address range (`203.0.113.0/24`), enhancing security.

```yaml
defaults:
  # Only allow SSH from my corporate VPN
  ssh_allowed_cidr: "203.0.113.0/24"
```

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

### Dynamic AMI Selection Query in Campers Config (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Shows how to dynamically select an AMI using the `ami.query` option in `campers.yaml`. This method finds the latest AMI matching specified criteria like name pattern, owner, and architecture, which is recommended for keeping instances up-to-date.

```yaml
ami:
  query:
    name: "Deep Learning Base AMI (Ubuntu*)*"
    owner: "amazon"
    architecture: "x86_64" # or arm64
```

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

### Behave Step Definitions (`environment.py`)

Source: https://github.com/kamilc/campers/blob/main/tests/README.md

Provides Python implementations for Gherkin steps used in Behave BDD scenarios. It includes decorators for defining Given, When, and Then steps, managing context, and performing actions within tests.

```python
@given("the campers CLI is available")
def step_cli_available(context: Context) -> None:
    context.cli = CampersCLI()

@when("I run: {command}")
def step_run_command(context: Context, command: str) -> None:
    context.result = context.cli.run(command)

@then('the instance should be in state "{state}"')
def step_check_state(context: Context, state: str) -> None:
    assert context.result.state == state

```

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

### Campers Environment Variable Filtering Configuration

Source: https://github.com/kamilc/campers/blob/main/README.md

Demonstrates how to configure environment variable forwarding in Campers using a 'defaults' section with an 'env_filter'. This example shows how to selectively forward environment variables that match specific regex patterns, enhancing security.

```yaml
defaults:
  # Only forward specific safe variables
  env_filter:
    - ^AWS_.*
    - ^WANDB_API_KEY
```

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

### Load and Merge Campers Configuration (Python)

Source: https://context7.com/kamilc/campers/llms.txt

Load and merge Campers configuration from YAML files, supporting variable interpolation and defaults. The `ConfigLoader` handles loading from environment variables or specified paths and can retrieve merged configurations for specific camps or the default configuration.

```python
from campers.core.config import ConfigLoader

# Initialize loader
config_loader = ConfigLoader()

# Load configuration file (checks CAMPERS_CONFIG env var, then campers.yaml)
raw_config = config_loader.load_config()

# Load from specific path
raw_config = config_loader.load_config(config_path="/path/to/config.yaml")

# Get merged configuration for specific camp
merged_config = config_loader.get_camp_config(raw_config, camp_name="training")
# Result includes: built-in defaults → YAML defaults → camp-specific settings

# Get default configuration (no camp specified)
default_config = config_loader.get_camp_config(raw_config, camp_name=None)

# Validate configuration
try:
    config_loader.validate_config(merged_config)
    print("Configuration is valid")
except ValueError as e:
    print(f"Configuration error: {e}")
```

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

### Default Campers Settings (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Illustrates the `defaults` section in `campers.yaml`, where global settings like `region`, `instance_type`, `disk_size`, and `ssh_username` are defined. It also shows configurations for `sync_paths` and `ignore` files for directory synchronization.

```yaml
defaults:
  region: us-east-1
  instance_type: t3.medium
  disk_size: 50
  ssh_username: ubuntu

  # Sync current directory to remote directory
  sync_paths:
    - local: .
      remote: /home/ubuntu/${project}

  # Don't sync these local files
  ignore:
    - "*.pyc"
    - __pycache__
    - .venv/
    - .git/
```

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

### List and Find EC2 Instances with EC2Manager in Python

Source: https://context7.com/kamilc/campers/llms.txt

Queries and manages EC2 instances across AWS regions using EC2Manager. Supports listing all instances, filtering by a specific region, and finding instances by name tag or ID. It returns detailed information about matched instances, including their state, configuration, and launch time.

```python
from campers.providers.aws.compute import EC2Manager

ec2_manager = EC2Manager(region="us-east-1")

# List all instances across all regions
all_instances = ec2_manager.list_instances()
for inst in all_instances:
    print(f"{inst['name']}: {inst['instance_id']} ({inst['state']} in {inst['region']})")

# List instances in specific region
regional_instances = ec2_manager.list_instances(region_filter="us-west-2")

# Find instances by ID, Name tag, or MachineConfig
matches = ec2_manager.find_instances_by_name_or_id(
    name_or_id="training",
    region_filter="us-east-1"
)

if matches:
    instance = matches[0]
    print(f"Found: {instance['instance_id']}")
    print(f"Type: {instance['instance_type']}")
    print(f"State: {instance['state']}")
    print(f"Camp: {instance['camp_config']}")
    print(f"Launched: {instance['launch_time']}")

ec2_manager.close()
```

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

### Exact AMI ID Specification in Campers Config (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Demonstrates how to specify an exact AMI ID using the `ami.image_id` option in `campers.yaml`. This approach pins the instance to a particular AMI version, ensuring consistency but requiring manual updates for newer images.

```yaml
ami:
  image_id: ami-0123456789abcdef0
```

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

### Campers Configuration File Structure Overview (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Provides a structural overview of the `campers.yaml` file, illustrating the four main sections: `vars` for variables, `playbooks` for Ansible playbooks, `defaults` for global settings, and `camps` for machine definitions. This YAML snippet is for illustrative purposes.

```yaml
# 1. Variables (DRY configuration)
vars:
  project_name: my-app

# 2. Ansible Playbooks (Provisioning)
playbooks:
  base-setup: ...

# 3. Defaults (Global settings)
defaults:
  region: us-east-1

# 4. Camps (Machine definitions)
camps:
  dev: ...
  prod: ...
```

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

### Pytest Configuration (`pyproject.toml`)

Source: https://github.com/kamilc/campers/blob/main/tests/README.md

Configures Pytest options such as test directory paths and directories to ignore during recursive searching. This file centralizes Pytest settings for the project.

```toml
[tool.pytest.ini_options]
testpaths = ["tests/unit"]
norecursedirs = ["tmp", ".git", ".venv", "__pycache__"]

```

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

### Set Up Bi-directional File Synchronization with Mutagen

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Configure high-performance, bi-directional file synchronization between local and remote directories using Mutagen. Supports exclusion patterns and optional synchronization of version control directories.

```yaml
sync_paths:
  - local: .
    remote: /home/ubuntu/project
```

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

### Run Pytest with JUnit XML Output

Source: https://github.com/kamilc/campers/blob/main/tests/README.md

Command to execute Pytest unit tests and generate a JUnit XML report, which is commonly used by CI/CD systems for test result aggregation and reporting.

```bash
uv run pytest tests/unit --junitxml=results.xml

```

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

### Define Reusable Variables in Campers Config (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Demonstrates how to define reusable variables within the `vars` section of `campers.yaml`. These variables can be referenced using `${var_name}` syntax and support nested references and environment variable expansion.

```yaml
vars:
  project: my-ml-project
  remote_dir: /home/ubuntu/${project}
  python_version: "3.12"
```

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

### Define Experimentation Environment Configuration (Jupyter)

Source: https://github.com/kamilc/campers/blob/main/README.md

Configures an 'experiment' camp for interactive experimentation using Jupyter. It sets a GPU instance type, specifies a Deep Learning AMI, forwards port 8888, and includes a command to launch Jupyter Lab.

```yaml
experiment:
  instance_type: g4dn.xlarge
  # Use the Deep Learning AMI
  ami:
    query:
      name: "Deep Learning Base AMI (Ubuntu*)*"
      owner: "amazon"
  # Open Jupyter on your laptop's localhost:8888
  ports: [8888]
  ansible_playbooks: [python-setup]
  command: jupyter lab --ip=0.0.0.0 --port=8888
```

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

### Define Development Environment Configuration

Source: https://github.com/kamilc/campers/blob/main/README.md

Defines a 'dev' camp for a cheap development environment. It specifies the instance type and a command to execute upon startup, utilizing a remote path variable.

```yaml
camps:
  # 1. Cheap dev environment
  dev:
    instance_type: t3.medium
    # Uses variable defined above
    command: cd ${remote_path} && bash
```

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

### Camp Configuration for GPU Experiment Machine (YAML)

Source: https://github.com/kamilc/campers/blob/main/docs/configuration.md

Defines an `experiment` camp configuration in `campers.yaml` for a GPU-enabled instance. It specifies a `g5.xlarge` instance type, dynamically queries for a Deep Learning Base AMI, opens port 8888, and sets the command to launch Jupyter Lab.

```yaml
camps:
  # GPU machine for experiments
  experiment:
    instance_type: g5.xlarge
    ami:
      query:
        name: "Deep Learning Base AMI (Ubuntu*)*"
        owner: "amazon"
    ports: [8888]
    command: jupyter lab --ip=0.0.0.0 --port=8888
```

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

### Profile Slow Pytest Tests Command

Source: https://github.com/kamilc/campers/blob/main/tests/README.md

A bash command to run Pytest and report the durations of the slowest tests. This is helpful for identifying performance bottlenecks in the unit test suite.

```bash
uv run pytest tests/unit --durations=10

```

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

### Display Campers Instance Information

Source: https://context7.com/kamilc/campers/llms.txt

Retrieves detailed information about a specific Campers-managed instance. The instance can be identified by its camp name or instance ID.

```bash
# Get info by camp name
campers info training

# Get info by instance ID
campers info i-0abc123def456

# Example output:
# Instance Information: training
#   Instance ID: i-0abc123def456
#   State: running
#   Instance Type: p3.2xlarge
#   Region: us-east-1
#   Launch Time: 2025-01-15T10:30:00+00:00
#   Unique ID: abc123
```