### Setup Development Environment

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Commands to install dependencies and initialize the BOSH Agent repository.

```bash
brew update
brew install go
brew install git
brew install hg
```

```bash
go get -d github.com/cloudfoundry/bosh-agent
cd $GOPATH/src/github.com/cloudfoundry/bosh-agent
```

```bash
bin/go get github.com/golang/lint/golint
```

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

### Start Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Configures jobs according to the apply spec and starts all monitored services on the VM.

```APIDOC
## Start Action

### Description
Configures jobs according to the current apply spec and starts all monitored services on the VM via the job supervisor (monit).

### Method
POST (via NATS)

### Endpoint
agent.<agent_id>

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - Must be "start".
- **arguments** (array) - Required - Must be an empty array.
- **reply_to** (string) - Required - The NATS subject to which the response should be sent.

### Request Example
```json
{
  "method": "start",
  "arguments": [],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (string) - The string "started" indicating the services have been started.

#### Response Example
```json
{
  "value": "started"
}
```
```

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

### Start Monitored Services

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Starts all services on the VM via the job supervisor.

```bash
nats-pub agent.123-456-789 '{
  "method": "start",
  "arguments": [],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Invoke Custom Blobstore

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Example command line usage for a custom blobstore executable.

```bash
bosh-blobstore-custom -c /var/vcap/bosh/etc/blobstore-custom.json get 2340958ddfg /tmp/my-cool-file
```

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

### Apply Job Specification

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Deploys a job specification to the VM, including package installation and configuration.

```bash
nats-pub agent.123-456-789 '{
  "method": "apply",
  "arguments": [{
    "deployment": "my-deployment",
    "name": "web-server",
    "id": "instance-uuid-123",
    "az": "z1",
    "index": 0,
    "configuration_hash": "abc123def456",
    "job": {
      "name": "nginx",
      "template": "nginx",
      "templates": [{"name": "nginx", "version": "1.0"}]
    },
    "packages": {
      "nginx": {
        "name": "nginx",
        "version": "1.18.0",
        "sha1": "sha256:abc123...",
        "blobstore_id": "blob-id-123"
      }
    },
    "networks": {
      "default": {
        "type": "manual",
        "ip": "10.0.0.5",
        "netmask": "255.255.255.0",
        "gateway": "10.0.0.1"
      }
    },
    "rendered_templates_archive": {
      "sha1": "sha256:template-hash",
      "blobstore_id": "templates-blob-id"
    }
  }],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### SSH Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Manages temporary SSH access to the VM via setup and cleanup operations.

```bash
nats-pub agent.123-456-789 '{
  "method": "ssh",
  "arguments": ["setup", {
    "user": "bosh_temp_user",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC..."
  }],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

```bash
nats-pub agent.123-456-789 '{
  "method": "ssh",
  "arguments": ["cleanup", {
    "user_regex": "^bosh_temp_user"
  }],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Implement Custom Blobstore

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Create an executable named bosh-blobstore-<name> that handles get and put commands via standard input/output or arguments.

```bash
#!/bin/bash
# bosh-blobstore-custom - Custom blobstore implementation

CONFIG_FILE=""

# Parse arguments
while getopts "c:" opt; do
    case $opt in
        c) CONFIG_FILE="$OPTARG" ;;
    esac
done
shift $((OPTIND-1))

COMMAND="$1"
shift

case "$COMMAND" in
    get)
        BLOB_ID="$1"
        FILENAME="$2"
        # Read config and download blob to filename
        ENDPOINT=$(jq -r '.endpoint' "$CONFIG_FILE")
        curl -s "$ENDPOINT/blobs/$BLOB_ID" -o "$FILENAME"
        ;;
    put)
        FILENAME="$1"
        BLOB_ID="$2"
        # Read config and upload file
        ENDPOINT=$(jq -r '.endpoint' "$CONFIG_FILE")
        curl -s -X PUT "$ENDPOINT/blobs/$BLOB_ID" --data-binary "@$FILENAME"
        ;;
    *)
        echo "Unknown command: $COMMAND" >&2
        exit 1
        ;;
esac
```

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

### Apply Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Deploys a job specification to the VM, installing packages and configuring jobs. This is the primary deployment mechanism.

```APIDOC
## Apply Action

### Description
Deploys a job specification to the VM, installing packages and configuring jobs according to the provided apply spec. This is the primary mechanism for deploying software to BOSH-managed VMs.

### Method
POST (via NATS)

### Endpoint
agent.<agent_id>

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - Must be "apply".
- **arguments** (array) - Required - An array containing a single object representing the apply spec.
  - **deployment** (string) - Required - The name of the deployment.
  - **name** (string) - Required - The name of the job.
  - **id** (string) - Required - The instance ID of the job.
  - **az** (string) - Required - The availability zone of the instance.
  - **index** (integer) - Required - The index of the instance within the AZ.
  - **configuration_hash** (string) - Required - A hash representing the configuration.
  - **job** (object) - Required - Job details.
    - **name** (string) - Required - The name of the job.
    - **template** (string) - Required - The name of the template.
    - **templates** (array) - Required - List of templates.
      - **name** (string) - Required - Template name.
      - **version** (string) - Required - Template version.
  - **packages** (object) - Required - Details of packages to be installed.
    - **[package_name]** (object) - Required - Package details.
      - **name** (string) - Required - Package name.
      - **version** (string) - Required - Package version.
      - **sha1** (string) - Required - SHA1 checksum of the package.
      - **blobstore_id** (string) - Required - Blobstore ID for the package.
  - **networks** (object) - Required - Network configuration.
    - **[network_name]** (object) - Required - Network details.
      - **type** (string) - Required - Network type (e.g., "manual").
      - **ip** (string) - Required - IP address.
      - **netmask** (string) - Required - Netmask.
      - **gateway** (string) - Required - Gateway.
  - **rendered_templates_archive** (object) - Required - Details of the rendered templates archive.
    - **sha1** (string) - Required - SHA1 checksum of the archive.
    - **blobstore_id** (string) - Required - Blobstore ID for the archive.
- **reply_to** (string) - Required - The NATS subject to which the response should be sent.

### Request Example
```json
{
  "method": "apply",
  "arguments": [
    {
      "deployment": "my-deployment",
      "name": "web-server",
      "id": "instance-uuid-123",
      "az": "z1",
      "index": 0,
      "configuration_hash": "abc123def456",
      "job": {
        "name": "nginx",
        "template": "nginx",
        "templates": [{"name": "nginx", "version": "1.0"}]
      },
      "packages": {
        "nginx": {
          "name": "nginx",
          "version": "1.18.0",
          "sha1": "sha256:abc123...",
          "blobstore_id": "blob-id-123"
        }
      },
      "networks": {
        "default": {
          "type": "manual",
          "ip": "10.0.0.5",
          "netmask": "255.255.255.0",
          "gateway": "10.0.0.1"
        }
      },
      "rendered_templates_archive": {
        "sha1": "sha256:template-hash",
        "blobstore_id": "templates-blob-id"
      }
    }
  ],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (object) - An object indicating the status of the apply task.
  - **agent_task_id** (string) - The ID of the asynchronous task.
  - **state** (string) - The initial state of the task (e.g., "running").

#### Response Example (Initial async response)
```json
{
  "value": {
    "agent_task_id": "task-123",
    "state": "running"
  }
}
```

#### Success Response (Final async response)
- **value** (string) - The string "applied" indicating successful completion.

#### Response Example (Final async response)
```json
{
  "value": "applied"
}
```
```

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

### Get VM State

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Retrieves current VM status, including vitals and process information.

```bash
nats-pub agent.123-456-789 '{
  "method": "get_state",
  "arguments": [],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

```bash
nats-pub agent.123-456-789 '{
  "method": "get_state",
  "arguments": ["full"],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Get State Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Retrieves the current state of the VM, including job status, network configuration, vitals, and processes.

```APIDOC
## Get State Action

### Description
Retrieves the current state of the VM including job status, network configuration, vitals (CPU, memory, disk usage), and running processes.

### Method
POST (via NATS)

### Endpoint
agent.<agent_id>

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - Must be "get_state".
- **arguments** (array) - Optional - Can be empty for basic state or contain "full" to include vitals.
- **reply_to** (string) - Required - The NATS subject to which the response should be sent.

### Request Example (Basic State)
```json
{
  "method": "get_state",
  "arguments": [],
  "reply_to": "director.abc123"
}
```

### Request Example (Full State with Vitals)
```json
{
  "method": "get_state",
  "arguments": ["full"],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (object) - An object containing the VM's state information.
  - **agent_id** (string) - The agent's unique identifier.
  - **job_state** (string) - The current state of the job (e.g., "running").
  - **deployment** (string) - The name of the deployment.
  - **name** (string) - The name of the job.
  - **index** (integer) - The index of the instance.
  - **id** (string) - The instance ID.
  - **az** (string) - The availability zone.
  - **networks** (object) - Network configuration.
    - **[network_name]** (object) - Network details.
      - **ip** (string) - The IP address.
  - **vm** (object) - VM details.
    - **name** (string) - The VM name.
  - **processes** (array) - List of running processes.
    - **name** (string) - Process name.
    - **state** (string) - Process state.
    - **uptime** (object) - Process uptime.
      - **secs** (integer) - Seconds of uptime.
    - **mem** (object) - Memory usage.
      - **kb** (integer) - Memory in kilobytes.
      - **percent** (number) - Percentage of memory used.
    - **cpu** (object) - CPU usage.
      - **total** (number) - Total CPU percentage.
  - **vitals** (object) - VM vitals (only present if "full" argument is used).
    - **cpu** (object) - CPU usage details.
      - **sys** (string) - System CPU time.
      - **user** (string) - User CPU time.
      - **wait** (string) - CPU wait time.
    - **mem** (object) - Memory usage details.
      - **kb** (string) - Total memory in kilobytes.
      - **percent** (string) - Percentage of memory used.
    - **disk** (object) - Disk usage details.
      - **system** (object) - System disk usage.
        - **percent** (string) - Percentage of system disk used.
      - **persistent** (object) - Persistent disk usage.
        - **percent** (string) - Percentage of persistent disk used.

#### Response Example
```json
{
  "value": {
    "agent_id": "agent-123",
    "job_state": "running",
    "deployment": "my-deployment",
    "name": "web-server",
    "index": 0,
    "id": "instance-uuid-123",
    "az": "z1",
    "networks": {"default": {"ip": "10.0.0.5"}},
    "vm": {"name": "vm-abc123"},
    "processes": [
      {"name": "nginx", "state": "running", "uptime": {"secs": 3600}, "mem": {"kb": 1024, "percent": 0.5}, "cpu": {"total": 0.1}}
    ],
    "vitals": {
      "cpu": {"sys": "1.0", "user": "2.0", "wait": "0.5"},
      "mem": {"kb": "4096000", "percent": "50"},
      "disk": {"system": {"percent": "30"}, "persistent": {"percent": "20"}}
    }
  }
}
```
```

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

### SSH Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

The ssh action manages SSH access to the VM. It supports setup (creating temporary users with SSH keys) and cleanup (removing temporary users) operations.

```APIDOC
## SSH Action

The ssh action manages SSH access to the VM. It supports setup (creating temporary users with SSH keys) and cleanup (removing temporary users) operations.

### Method
NATS PUBLISH

### Endpoint
agent.<agent_id>

### Request Body
```json
{
  "method": "ssh",
  "arguments": ["setup" | "cleanup", <ssh_arguments>],
  "reply_to": "<director_reply_to_address>"
}
```

### Request Example
```bash
# Setup SSH access for a user
nats-pub agent.123-456-789 '{
  "method": "ssh",
  "arguments": ["setup", {
    "user": "bosh_temp_user",
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC..."
  }],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222

# Cleanup SSH access
nats-pub agent.123-456-789 '{
  "method": "ssh",
  "arguments": ["cleanup", {
    "user_regex": "^bosh_temp_user"
  }],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

### Response
#### Success Response (200)
- **value** (object) - Response details based on the command (setup/cleanup).
  - **command** (string) - The SSH command executed (e.g., "setup", "cleanup").
  - **status** (string) - The status of the command (e.g., "success").
  - **ip** (string, optional) - The IP address of the VM (for setup).
  - **host_public_key** (string, optional) - The public key of the VM host (for setup).

#### Response Example
```json
{
  "value": {
    "command": "setup",
    "status": "success",
    "ip": "10.0.0.5",
    "host_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB..."
  }
}
```

#### Cleanup Response Example
```json
{"value":{"command":"cleanup","status":"success"}}
```
```

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

### Interact with NATS Messaging

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Commands for starting the NATS server, subscribing to topics, and publishing messages to the agent.

```bash
gem install nats
nats-server
```

```bash
nats-sub '>' -s nats://localhost:4222
```

```bash
nats-pub agent.123-456-789 '{"method":"apply","arguments":[{"packages":[{"name":"package-name", "version":"package-version"}]}]}' -s nats://localhost:4222
```

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

### Get Task Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Retrieves the status of an asynchronous task. This is used to poll for completion of long-running operations.

```APIDOC
## Get Task Action

### Description
Retrieves the status of an asynchronous task. This is used to poll for completion of long-running operations.

### Method
NATS PUBLISH

### Endpoint
`agent.<agent_id>`

### Parameters
#### Arguments
- **task_id** (string) - Required. The ID of the task to check.

### Request Body
```json
{
  "method": "get_task",
  "arguments": ["<task_id>"],
  "reply_to": "<reply_to_queue>"
}
```

### Request Example
```json
// Check task status
{
  "method": "get_task",
  "arguments": ["task-123"],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **agent_task_id** (string) - The agent's internal task ID.
- **state** (string) - The current state of the task (e.g., "running", "done", "error").
- **value** (any) - The result of the task if it has completed.

#### Response Example
```json
// Response while running:
{
  "value": {
    "agent_task_id": "task-123",
    "state": "running"
  }
}

// Response when complete:
{
  "value": "applied" // Or the result of the original action
}
```
```

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

### Get Task Status

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Retrieves the status of an asynchronous task using its ID. Used for polling long-running operations.

```bash
nats-pub agent.123-456-789 '{
  "method": "get_task",
  "arguments": ["task-123"],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Fetch Logs Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Collects and archives logs from the VM to the blobstore.

```bash
nats-pub agent.123-456-789 '{
  "method": "fetch_logs",
  "arguments": ["job", ["nginx/*"]],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Build the BOSH agent binary

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/working_with_dev_versions.md

Generates the agent binary in the out directory. Apple silicon users must set CGO_ENABLED to 1 in the script before execution.

```bash
./bin/build
```

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

### Mount Disk Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Attaches and mounts a persistent disk to the VM at /var/vcap/store.

```bash
nats-pub agent.123-456-789 '{
  "method": "mount_disk",
  "arguments": ["disk-cid-abc123"],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Transfer the dev-agent binary to a BOSH VM

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/working_with_dev_versions.md

Copies the locally built binary to the /tmp directory of the target instance.

```bash
bosh -e <bosh-director> -d <deployment> scp <dev-agent> <instance_name>:/tmp
```

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

### Run BOSH Agent Locally

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Execute the agent binary with specific environment variables and configuration paths.

```bash
PATH=.../s3cli/out:$PATH bin/run -P ubuntu -C path_to_config.json
```

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

### Compile Package Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Compiles a source package and uploads the resulting artifact to the blobstore.

```bash
nats-pub agent.123-456-789 '{
  "method": "compile_package",
  "arguments": [
    "source-blob-id",
    "sha256:source-package-digest",
    "my-package",
    "1.0.0",
    {
      "dependency-package": {
        "name": "dependency-package",
        "version": "2.0.0",
        "sha1": "sha256:dep-digest",
        "blobstore_id": "dep-blob-id"
      }
    }
  ],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Run Lifecycle Script

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Executes BOSH lifecycle scripts (e.g., pre-start, post-deploy) across all jobs on a VM. Requires the script name and an empty options map.

```bash
nats-pub agent.123-456-789 '{
  "method": "run_script",
  "arguments": ["pre-start", {}],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

```bash
nats-pub agent.123-456-789 '{
  "method": "run_script",
  "arguments": ["post-deploy", {}],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Create BOSH Agent Workspace

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Create a new directory structure for your BOSH Agent Go workspace. This ensures the project is set up correctly within the Go module system.

```bash
mkdir -p ~/workspace/bosh-agent-workspace/src/github.com/cloudfoundry
cd ~/workspace/bosh-agent-workspace/src/github.com/cloudfoundry
```

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

### Run Script Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Executes lifecycle scripts (pre-start, post-start, pre-stop, post-stop, post-deploy) across all jobs on the VM.

```APIDOC
## Run Script Action

### Description
Executes lifecycle scripts (pre-start, post-start, pre-stop, post-stop, post-deploy) across all jobs on the VM.

### Method
NATS PUBLISH

### Endpoint
`agent.<agent_id>`

### Parameters
#### Arguments
- **script_name** (string) - Required. The name of the lifecycle script to run (e.g., "pre-start", "post-deploy").
- **env** (object) - Optional. A map of environment variables to set for the script.

### Request Body
```json
{
  "method": "run_script",
  "arguments": ["<script_name>", {}],
  "reply_to": "<reply_to_queue>"
}
```

### Request Example
```json
// Run pre-start scripts
{
  "method": "run_script",
  "arguments": ["pre-start", {}],
  "reply_to": "director.abc123"
}

// Run post-deploy scripts
{
  "method": "run_script",
  "arguments": ["post-deploy", {}],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (object) - An empty object indicating success.

#### Response Example
```json
{
  "value": {}
}
```
```

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

### Interact with BOSH Agent using Go Client

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Use the AgentClient to perform lifecycle operations like pinging, state retrieval, job application, and disk management.

```go
package main

import (
    "fmt"
    "time"

    "github.com/cloudfoundry/bosh-utils/httpclient"
    "github.com/cloudfoundry/bosh-utils/logger"

    "github.com/cloudfoundry/bosh-agent/v2/agentclient/http"
    "github.com/cloudfoundry/bosh-agent/v2/agentclient/applyspec"
)

func main() {
    log := logger.NewLogger(logger.LevelDebug)
    httpClient := httpclient.NewHTTPClient(httpclient.DefaultClient, log)

    // Create agent client
    client := http.NewAgentClient(
        "https://10.0.0.5:6868",  // Agent endpoint
        "director-uuid",          // Director ID for authentication
        time.Second,              // Task polling delay
        3,                        // Tolerated error count
        httpClient,
        log,
    )

    // Ping the agent
    response, err := client.Ping()
    if err != nil {
        panic(err)
    }
    fmt.Printf("Ping response: %s\n", response)

    // Get agent state
    state, err := client.GetState()
    if err != nil {
        panic(err)
    }
    fmt.Printf("Job state: %s\n", state.JobState)

    // Apply a job spec
    spec := applyspec.ApplySpec{
        Deployment: "my-deployment",
        Name:       "web-server",
        Index:      0,
        // ... additional spec fields
    }
    err = client.Apply(spec)
    if err != nil {
        panic(err)
    }

    // Start jobs
    err = client.Start()
    if err != nil {
        panic(err)
    }

    // Setup SSH access
    sshResult, err := client.SetUpSSH("temp_user", "ssh-rsa AAAA...")
    if err != nil {
        panic(err)
    }
    fmt.Printf("SSH IP: %s\n", sshResult.Ip)

    // Mount a persistent disk
    err = client.MountDisk("disk-cid-123")
    if err != nil {
        panic(err)
    }

    // Compile a package
    compiledRef, err := client.CompilePackage(
        agentclient.BlobRef{
            Name:        "my-package",
            Version:     "1.0",
            SHA1:        "sha256:abc123",
            BlobstoreID: "source-blob-id",
        },
        []agentclient.BlobRef{}, // dependencies
    )
    if err != nil {
        panic(err)
    }
    fmt.Printf("Compiled blob ID: %s\n", compiledRef.BlobstoreID)
}
```

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

### Clone IDE Preferences

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Clone the IDE Preferences repository to obtain improved keybindings for IntelliJ. This step is optional.

```bash
git clone git@github.com:Pivotal-Boulder/IDE-Preferences.git
```

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

### Link Keymap XML

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Link the IntelliJ keymap XML file from the cloned IDE Preferences repository. This allows IntelliJ to use the improved keybindings.

```bash
cd ~/Library/Preferences/IntelliJIdea13/keymaps
ln -sf ~/workspace/IDE-Preferences/IntelliJKeymap.xml
```

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

### Migrate Disk Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Copies data from an old persistent disk to a new one.

```bash
nats-pub agent.123-456-789 '{
  "method": "migrate_disk",
  "arguments": [],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Mount Disk Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

The mount_disk action attaches and mounts a persistent disk to the VM at the store directory (/var/vcap/store). It handles disk partitioning and filesystem creation if needed.

```APIDOC
## Mount Disk Action

The mount_disk action attaches and mounts a persistent disk to the VM at the store directory (/var/vcap/store). It handles disk partitioning and filesystem creation if needed.

### Method
NATS PUBLISH

### Endpoint
agent.<agent_id>

### Parameters
#### Path Parameters
- **disk_cid** (string) - Required - The CID of the persistent disk to mount.

### Request Body
```json
{
  "method": "mount_disk",
  "arguments": ["<disk_cid>"],
  "reply_to": "<director_reply_to_address>"
}
```

### Request Example
```bash
# Mount a persistent disk by its CID
nats-pub agent.123-456-789 '{
  "method": "mount_disk",
  "arguments": ["disk-cid-abc123"],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

### Response
#### Success Response (200)
- **value** (object) - An object containing the agent task ID and state.
  - **agent_task_id** (string) - The ID of the asynchronous agent task.
  - **state** (string) - The current state of the task (e.g., "running").

#### Response Example
```json
{"value":{"agent_task_id":"task-789","state":"running"}}
```

#### Final Response Example
```json
{"value":{}}
```
```

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

### List Disk Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Retrieves a list of all persistent disk CIDs attached to the VM.

```bash
nats-pub agent.123-456-789 '{
  "method": "list_disk",
  "arguments": [],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Clone BOSH Agent Repository

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Clone the BOSH Agent repository into your newly created Go workspace. This makes the agent's source code available for development.

```bash
git clone https://github.com/cloudfoundry/bosh-agent
```

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

### Ping the BOSH Agent

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Verifies agent responsiveness by sending a ping command.

```bash
nats-pub agent.123-456-789 '{"method":"ping","arguments":[],"reply_to":"director.abc123"}' -s nats://localhost:4222
```

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

### Fetch Logs Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

The fetch_logs action collects logs from the VM, creates a tarball, and uploads it to the blobstore. It supports filtering by log type (job or agent) and specific filters.

```APIDOC
## Fetch Logs Action

The fetch_logs action collects logs from the VM, creates a tarball, and uploads it to the blobstore. It supports filtering by log type (job or agent) and specific filters.

### Method
NATS PUBLISH

### Endpoint
agent.<agent_id>

### Request Body
```json
{
  "method": "fetch_logs",
  "arguments": ["<log_type>", ["<filter1>", "<filter2>", ...]],
  "reply_to": "<director_reply_to_address>"
}
```

### Request Example
```bash
# Fetch job logs
nats-pub agent.123-456-789 '{
  "method": "fetch_logs",
  "arguments": ["job", ["nginx/*"]],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

### Response
#### Success Response (200)
- **value** (object) - An object containing the agent task ID and state for asynchronous log fetching.
  - **agent_task_id** (string) - The ID of the asynchronous agent task.
  - **state** (string) - The current state of the task (e.g., "running").

#### Response Example (Async)
```json
{"value":{"agent_task_id":"task-logs","state":"running"}}
```

#### Final Response Example
```json
{
  "value": {
    "blobstore_id": "logs-tarball-id",
    "sha1": "sha256:logs-tarball-digest"
  }
}
```
```

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

### Retrieve Agent Information

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Fetches metadata including the API version to ensure compatibility.

```bash
nats-pub agent.123-456-789 '{"method":"info","arguments":[],"reply_to":"director.abc123"}' -s nats://localhost:4222
```

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

### Info Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Retrieves metadata about the agent, including its API version, useful for compatibility checks.

```APIDOC
## Info Action

### Description
Returns metadata about the agent, including its API version. This is useful for determining compatibility between the Director and Agent.

### Method
POST (via NATS)

### Endpoint
agent.<agent_id>

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - Must be "info".
- **arguments** (array) - Required - Must be an empty array.
- **reply_to** (string) - Required - The NATS subject to which the response should be sent.

### Request Example
```json
{
  "method": "info",
  "arguments": [],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (object) - An object containing agent metadata.
  - **api_version** (integer) - The API version supported by the agent.

#### Response Example
```json
{
  "value": {
    "api_version": 1
  }
}
```
```

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

### Update Settings Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Updates the agent's runtime settings including trusted certificates. This allows dynamic configuration updates without VM recreation.

```APIDOC
## Update Settings Action

### Description
Updates the agent's runtime settings including trusted certificates. This allows dynamic configuration updates without VM recreation.

### Method
NATS PUBLISH

### Endpoint
`agent.<agent_id>`

### Parameters
#### Arguments
- **settings** (object) - Required. An object containing the settings to update. Currently supports `trusted_certs`.
  - **trusted_certs** (string) - Optional. A string containing PEM-encoded trusted certificates.

### Request Body
```json
{
  "method": "update_settings",
  "arguments": [{"trusted_certs": "<pem_encoded_certificates>"}],
  "reply_to": "<reply_to_queue>"
}
```

### Request Example
```json
// Update agent settings with new certificates
{
  "method": "update_settings",
  "arguments": [{
    "trusted_certs": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"
  }],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (string) - Indicates that the settings have been updated.

#### Response Example
```json
{
  "value": "updated"
}
```
```

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

### Stop Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Gracefully stops all monitored services on the VM. Protocol version 3+ waits for services to fully stop before returning.

```APIDOC
## Stop Action

### Description
Gracefully stops all monitored services on the VM. Protocol version 3+ waits for services to fully stop before returning.

### Method
POST (via NATS)

### Endpoint
agent.<agent_id>

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - Must be "stop".
- **arguments** (array) - Required - Must be an empty array.
- **reply_to** (string) - Required - The NATS subject to which the response should be sent.

### Request Example
```json
{
  "method": "stop",
  "arguments": [],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (string) - The string "stopped" indicating the services have been stopped.

#### Response Example
```json
{
  "value": "stopped"
}
```
```

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

### Unmount Disk Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Safely unmounts a persistent disk from the VM.

```bash
nats-pub agent.123-456-789 '{
  "method": "unmount_disk",
  "arguments": ["disk-cid-abc123"],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Configure SSH Debugging

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/bin/repack-stemcell/README.md

Sets an SSH public key to be baked into the stemcell, allowing access via the bosh_debug user.

```bash
export BOSH_DEBUG_PUB_KEY="ssh-rsa blahblah"
```

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

### Fetch Agent Logs

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Use this method to retrieve logs from the BOSH agent. Specify the log type and any filters in the arguments.

```bash
nats-pub agent.123-456-789 '{
  "method": "fetch_logs",
  "arguments": ["agent", []],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### List Disk Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

The list_disk action returns a list of all persistent disk CIDs currently attached to the VM.

```APIDOC
## List Disk Action

The list_disk action returns a list of all persistent disk CIDs currently attached to the VM.

### Method
NATS PUBLISH

### Endpoint
agent.<agent_id>

### Request Body
```json
{
  "method": "list_disk",
  "arguments": [],
  "reply_to": "<director_reply_to_address>"
}
```

### Request Example
```bash
# List all mounted persistent disks
nats-pub agent.123-456-789 '{
  "method": "list_disk",
  "arguments": [],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

### Response
#### Success Response (200)
- **value** (array) - An array of strings, where each string is a persistent disk CID.

#### Response Example
```json
{"value":["disk-cid-abc123", "disk-cid-def456"]}
```
```

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

### Migrate Disk Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

The migrate_disk action copies data from the old persistent disk to the new one during disk replacement operations.

```APIDOC
## Migrate Disk Action

The migrate_disk action copies data from the old persistent disk to the new one during disk replacement operations.

### Method
NATS PUBLISH

### Endpoint
agent.<agent_id>

### Request Body
```json
{
  "method": "migrate_disk",
  "arguments": [],
  "reply_to": "<director_reply_to_address>"
}
```

### Request Example
```bash
# Migrate data between persistent disks
nats-pub agent.123-456-789 '{
  "method": "migrate_disk",
  "arguments": [],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

### Response
#### Success Response (200)
- **value** (object) - An object containing the agent task ID and state.
  - **agent_task_id** (string) - The ID of the asynchronous agent task.
  - **state** (string) - The current state of the task (e.g., "running").

#### Response Example
```json
{"value":{"agent_task_id":"task-migrate","state":"running"}}
```

#### Final Response Example
```json
{"value":{}}
```
```

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

### Sync DNS Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Updates the local DNS records on the VM from a blob provided by the Director. This enables service discovery within BOSH deployments.

```APIDOC
## Sync DNS Action

### Description
Updates the local DNS records on the VM from a blob provided by the Director. This enables service discovery within BOSH deployments.

### Method
NATS PUBLISH

### Endpoint
`agent.<agent_id>`

### Parameters
#### Arguments
- **dns_blob_id** (string) - Required. The ID of the DNS blob.
- **dns_blob_sha1** (string) - Required. The SHA1 digest of the DNS blob.
- **dns_blob_size** (integer) - Required. The size of the DNS blob in bytes.

### Request Body
```json
{
  "method": "sync_dns",
  "arguments": ["<dns_blob_id>", "<dns_blob_sha1>", <dns_blob_size>],
  "reply_to": "<reply_to_queue>"
}
```

### Request Example
```json
// Sync DNS records
{
  "method": "sync_dns",
  "arguments": ["dns-blob-id", "sha256:dns-digest", 12345],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (string) - Indicates that DNS records have been synced.

#### Response Example
```json
{
  "value": "synced"
}
```
```

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

### Manage Dependencies with Dep

Source: https://github.com/cloudfoundry/bosh-agent/blob/main/docs/dev_setup.md

Commands to update project dependencies using the dep tool.

```bash
dep ensure
```

```bash
dep ensure github.com/pivotal-golang/clock/fakeclock
```

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

### Ping Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Performs a health check to verify the agent is responsive. Returns 'pong' on success.

```APIDOC
## Ping Action

### Description
Provides a simple health check to verify the agent is responsive and operational. It returns "pong" when successfully executed.

### Method
POST (via NATS)

### Endpoint
agent.<agent_id>

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent.

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - Must be "ping".
- **arguments** (array) - Required - Must be an empty array.
- **reply_to** (string) - Required - The NATS subject to which the response should be sent.

### Request Example
```json
{
  "method": "ping",
  "arguments": [],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **value** (string) - The string "pong" indicating the agent is responsive.

#### Response Example
```json
{
  "value": "pong"
}
```
```

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

### Stop Monitored Services

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Gracefully stops all services on the VM.

```bash
nats-pub agent.123-456-789 '{
  "method": "stop",
  "arguments": [],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Update Agent Settings

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Updates the agent's runtime settings, such as trusted certificates. This allows dynamic configuration changes.

```bash
nats-pub agent.123-456-789 '{
  "method": "update_settings",
  "arguments": [{
    "trusted_certs": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"
  }],
  "reply_to": "director.abc123"
}' -s nats://localhost:4222
```

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

### Run Errand Action

Source: https://context7.com/cloudfoundry/bosh-agent/llms.txt

Executes an errand script from a job template and returns stdout, stderr, and exit code. Errands are one-off tasks like database migrations or smoke tests.

```APIDOC
## Run Errand Action

### Description
Executes an errand script from a job template and returns stdout, stderr, and exit code. Errands are one-off tasks like database migrations or smoke tests.

### Method
NATS PUBLISH

### Endpoint
`agent.<agent_id>`

### Parameters
#### Arguments
- **errand_name** (string) - Optional. The name of the errand to run. If not provided, the default errand is run.

### Request Body
```json
{
  "method": "run_errand",
  "arguments": ["<errand_name>"],
  "reply_to": "<reply_to_queue>"
}
```

### Request Example
```json
// Run the default errand
{
  "method": "run_errand",
  "arguments": [],
  "reply_to": "director.abc123"
}

// Run a specific errand by name
{
  "method": "run_errand",
  "arguments": ["smoke-tests"],
  "reply_to": "director.abc123"
}
```

### Response
#### Success Response (200)
- **stdout** (string) - The standard output of the errand.
- **stderr** (string) - The standard error of the errand.
- **exit_code** (integer) - The exit code of the errand.

#### Response Example
```json
{
  "value": {
    "stdout": "Running smoke tests...\nAll tests passed!",
    "stderr": "",
    "exit_code": 0
  }
}
```
```