### Start Development Server with Bun

Source: https://github.com/finsys/dockhand/blob/main/CONTRIBUTING.md

Start the development server using Bun. This command compiles and runs the application, making it accessible in your browser.

```bash
bun dev
```

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

### Install Dependencies with Bun

Source: https://github.com/finsys/dockhand/blob/main/CONTRIBUTING.md

Install project dependencies using the Bun package manager. This command should be run after cloning the repository.

```bash
bun install
```

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

### Create (and optionally start) a container

Source: https://context7.com/finsys/dockhand/llms.txt

Creates a new container within a specified environment. The container can be optionally started immediately after creation.

```APIDOC
## POST /api/containers

### Description
Creates a new container in the specified environment. If the image is not found locally, it will be pulled automatically. The container can be configured to start immediately after creation.

### Method
POST

### Endpoint
/api/containers

### Parameters
#### Query Parameters
- **env** (integer) - Required - The ID of the environment where the container will be created.

#### Request Body
- **name** (string) - Required - The name for the container.
- **image** (string) - Required - The Docker image to use for the container.
- **startAfterCreate** (boolean) - Optional - If true, the container will be started after creation.
- **ExposedPorts** (object) - Optional - Ports exposed by the container.
- **HostConfig** (object) - Optional - Configuration for the host, including port bindings and restart policies.
- **Env** (array of strings) - Optional - Environment variables for the container.

### Request Example
```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers?env=1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-nginx",
    "image": "nginx:latest",
    "startAfterCreate": true,
    "ExposedPorts": {"80/tcp": {}},
    "HostConfig": {
      "PortBindings": {"80/tcp": [{"HostPort": "8080"}]},
      "RestartPolicy": {"Name": "unless-stopped"}
    },
    "Env": ["NGINX_HOST=example.com"]
  }'
```

### Response Example
```json
{"success": true, "id": "def456"}
```
```

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

### List or Create Docker Environments

Source: https://context7.com/finsys/dockhand/llms.txt

Use `GET` to list existing environments. Use `POST` to create new environments, specifying connection type and details. Supports local socket, direct HTTP/HTTPS, and Hawser proxy connections.

```bash
curl -b cookies.txt http://localhost:3000/api/environments
```

```bash
curl -b cookies.txt -X POST http://localhost:3000/api/environments \
  -H "Content-Type: application/json" \
  -d '{"name": "local", "connectionType": "socket", "socketPath": "/var/run/docker.sock"}'
```

```bash
curl -b cookies.txt -X POST http://localhost:3000/api/environments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-server",
    "connectionType": "direct",
    "host": "docker.prod.example.com",
    "port": 2376,
    "protocol": "https",
    "tlsCa": "-----BEGIN CERTIFICATE-----\n...",
    "tlsCert": "-----BEGIN CERTIFICATE-----\n...",
    "tlsKey": "-----BEGIN RSA PRIVATE KEY-----\n..."
  }'
```

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

### List or create a Compose stack

Source: https://context7.com/finsys/dockhand/llms.txt

This endpoint allows listing existing Compose stacks or creating a new one. For creation, provide stack details including name, compose definition, and optional environment variables. Use `start: false` to create without immediate deployment.

```bash
# List stacks (includes git, internal, and adopted external stacks)
curl -b cookies.txt "http://localhost:3000/api/stacks?env=1"
# → [{"name": "myapp", "containers": [...], "status": "running", "sourceType": "internal"}]
```

```bash
# Create stack without starting
curl -b cookies.txt -X POST "http://localhost:3000/api/stacks?env=1" \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "myapp",
    "compose": "version: '\''3'\'';
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
",
    "start": false,
    "envVars": [{"key": "APP_ENV", "value": "production", "isSecret": false}]
  }'
# → {"success": true, "started": false}
```

```bash
# Create and deploy (streams SSE progress)
curl -b cookies.txt -X POST "http://localhost:3000/api/stacks?env=1" \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "myapp",
    "compose": "...",
    "start": true,
    "rawEnvContent": "APP_ENV=production\n# comment\nDB_HOST=db"
  }'
# SSE events: data: {"status": "Deploying stack..."}
# data: {"success": true, "started": true, "output": "..."}
```

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

### Authenticate User with LDAP Credentials

Source: https://context7.com/finsys/dockhand/llms.txt

Authenticate users against an LDAP provider. Ensure the provider configuration matches your LDAP setup.

```bash
curl -c cookies.txt -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "jdoe", "password": "ldappass", "provider": "ldap:2"}'
```

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

### Container lifecycle actions

Source: https://context7.com/finsys/dockhand/llms.txt

Performs lifecycle actions such as starting, stopping, restarting, pausing, or unpausing a container.

```APIDOC
## POST /api/containers/[id]/start|stop|restart|pause|unpause

### Description
Executes lifecycle actions on a specified container within an environment.

### Method
POST

### Endpoint
/api/containers/[id]/start
/api/containers/[id]/stop
/api/containers/[id]/restart
/api/containers/[id]/pause
/api/containers/[id]/unpause

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the container.

#### Query Parameters
- **env** (integer) - Required - The ID of the environment the container belongs to.

### Request Example (Start)
```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/start?env=1"
```

### Request Example (Stop)
```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/stop?env=1"
```

### Request Example (Restart)
```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/restart?env=1"
```

### Response Example
```json
{"success": true}
```
```

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

### Container Lifecycle Actions

Source: https://context7.com/finsys/dockhand/llms.txt

Perform lifecycle actions such as start, stop, restart, pause, or unpause on a specific container using its ID.

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/start?env=1"
```

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/stop?env=1"
```

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/restart?env=1"
```

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/pause?env=1"
```

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/unpause?env=1"
```

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

### Get Host System Information

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieve detailed information about the host system where Docker is running, including Docker version, OS, CPU count, and total memory. Requires authentication.

```bash
curl -b cookies.txt "http://localhost:3000/api/system?env=1"
# → {"DockerVersion": "27.3.1", "OperatingSystem": "Ubuntu 22.04", "NCPU": 8, "MemTotal": 16000000000, ...}
```

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

### Manage stack lifecycle (start, stop, restart, down)

Source: https://context7.com/finsys/dockhand/llms.txt

Control the lifecycle of a Compose stack. You can stop, restart, or bring down a stack. The `down` command accepts an optional JSON payload to control volume removal.

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/stacks/myapp/stop?env=1"
# → {"success": true}
```

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/stacks/myapp/down?env=1" \
  -H "Content-Type: application/json" \
  -d '{"removeVolumes": false}'
# → {"success": true}
```

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

### Get Current Session User Information

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieves details about the currently authenticated user, including their ID, username, and administrative status.

```bash
curl -b cookies.txt http://localhost:3000/api/auth/session
```

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

### Stack lifecycle management

Source: https://context7.com/finsys/dockhand/llms.txt

Controls the lifecycle of a Compose stack (start, stop, restart, down).

```APIDOC
## POST /api/stacks/[name]/start|stop|restart|down — Stack lifecycle

### Description
Controls the lifecycle of a Compose stack (start, stop, restart, down).

### Method
POST

### Endpoint
/api/stacks/[name]/start
/api/stacks/[name]/stop
/api/stacks/[name]/restart
/api/stacks/[name]/down

#### Query Parameters
- **env** (string) - Required - Environment identifier.

#### Request Body (for /down)
- **removeVolumes** (boolean) - Optional - Whether to remove associated volumes when stopping the stack.
```

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

### GET /api/schedules

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieves a list of all configured schedules, including those for container auto-updates, git stack synchronization, environment checks, image pruning, and system cleanups.

```APIDOC
## GET /api/schedules

### Description
Lists all configured schedules for various automated tasks.

### Method
GET

### Endpoint
/api/schedules

### Response
#### Success Response (200)
- **schedules** (array) - A list of schedule objects.
  - **id** (integer) - The unique identifier for the schedule.
  - **type** (string) - The type of schedule (e.g., "container_update", "git_stack_sync").
  - **name** (string) - A descriptive name for the schedule.
  - **entityName** (string) - The name of the entity the schedule applies to (if applicable).
  - **enabled** (boolean) - Indicates if the schedule is currently active.
  - **cronExpression** (string) - The cron expression defining the schedule's timing.
  - **nextRun** (string) - The timestamp for the next scheduled execution.
  - **lastExecution** (object) - Details about the last execution.
    - **status** (string) - The status of the last execution (e.g., "success").
    - **completedAt** (string) - The timestamp when the last execution completed.
  - **isSystem** (boolean) - Indicates if this is a system-managed schedule.

### Response Example
```json
{
  "schedules": [
    {
      "id": 1,
      "type": "container_update",
      "name": "Update container: myapp-web-1",
      "entityName": "myapp-web-1",
      "enabled": true,
      "cronExpression": "0 3 * * *",
      "nextRun": "2025-08-15T03:00:00.000Z",
      "lastExecution": {"status": "success", "completedAt": "2025-08-14T03:01:32.000Z"},
      "isSystem": false
    }
  ]
}
```
```

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

### List notification channels

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieve a list of configured notification channels, including their names, types (e.g., SMTP, Apprise), and enabled status. This endpoint supports both GET and POST requests for listing.

```bash
# List notification settings
curl -b cookies.txt http://localhost:3000/api/notifications
```

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

### Prune Specific Docker Resource Type

Source: https://context7.com/finsys/dockhand/llms.txt

This endpoint allows pruning of a specific resource type (containers, images, volumes, or networks). The example shows pruning images, which returns deleted images and reclaimed space.

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/prune/images?env=1"
# → {"success": true, "result": {"ImagesDeleted": [...], "SpaceReclaimed": 234000000}}
```

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

### GET /api/auth/session - Get the current session user

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieves information about the currently authenticated user session. Requires a valid session cookie or API token.

```APIDOC
## GET /api/auth/session

### Description
Retrieves the current session user information.

### Method
GET

### Endpoint
/api/auth/session

### Response
#### Success Response (200)
- **isAuthenticated** (boolean) - Indicates if the user is authenticated.
- **user** (object) - User details if authenticated.
```

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

### Create Git Stack and Deploy

Source: https://context7.com/finsys/dockhand/llms.txt

Use this endpoint to create a new git stack, linking a repository to an environment, and optionally trigger an immediate deployment. Configure auto-update schedules and webhook notifications.

```bash
curl -b cookies.txt -X POST http://localhost:3000/api/git/stacks \
  -H "Content-Type: application/json" \
  -d '{
    "stackName": "myapp-git",
    "environmentId": 1,
    "url": "https://github.com/myorg/myapp.git",
    "branch": "main",
    "composePath": "docker/compose.yaml",
    "autoUpdate": true,
    "autoUpdateSchedule": "custom",
    "autoUpdateCron": "0 2 * * *",
    "webhookEnabled": true,
    "deployNow": true
  }'
```

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

### List or create a Git-backed stack

Source: https://context7.com/finsys/dockhand/llms.txt

This endpoint allows listing existing Git-backed stacks or creating a new one. When listing, it provides details such as auto-update status and cron schedule.

```bash
# List git stacks
curl -b cookies.txt "http://localhost:3000/api/git/stacks?env=1"
# → [{"id": 1, "stackName": "myapp", "autoUpdate": true, "autoUpdateCron": "0 3 * * *", ...}]
```

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

### List and Create Docker Volumes

Source: https://context7.com/finsys/dockhand/llms.txt

This endpoint allows listing existing Docker volumes in an environment or creating new named volumes. When creating, specify the volume name, driver, and optional labels.

```bash
# List volumes
curl -b cookies.txt "http://localhost:3000/api/volumes?env=1"
```

```bash
# Create a named volume
curl -b cookies.txt -X POST "http://localhost:3000/api/volumes?env=1" \
  -H "Content-Type: application/json" \
  -d '{"name": "app-data", "driver": "local", "labels": {"project": "myapp"}}'
```

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

### List and Create Docker Networks

Source: https://context7.com/finsys/dockhand/llms.txt

This endpoint allows listing existing Docker networks in an environment or creating new networks. When creating, specify the network name, driver, and IPAM configuration.

```bash
# List networks
curl -b cookies.txt "http://localhost:3000/api/networks?env=1"
```

```bash
# Create a bridge network
curl -b cookies.txt -X POST "http://localhost:3000/api/networks?env=1" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

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

### Get image history

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieves the layer history of a specified image within a given environment. This provides details about how the image was constructed.

```APIDOC
## GET /api/images/[id]/history

### Description
Retrieves the layer history of a specified image within a given environment. This information details the commands used to build each layer of the image.

### Method
GET

### Endpoint
/api/images/[id]/history

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID (e.g., sha256 hash) of the image.
#### Query Parameters
- **env** (integer) - Required - The environment ID to query.

### Response
#### Success Response (200)
- **Id** (string) - The ID of the layer.
- **CreatedBy** (string) - The command used to create the layer.
- **Size** (integer) - The size of the layer.
```

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

### Create git stack

Source: https://context7.com/finsys/dockhand/llms.txt

Creates a new git stack, which involves initializing a new repository and performing an immediate deployment. This operation uses Server-Sent Events (SSE) for progress updates.

```APIDOC
## POST /api/git/stacks

### Description
Creates a new git stack, initializing a new repository and performing an immediate deployment. Progress is reported via Server-Sent Events (SSE).

### Method
POST

### Endpoint
/api/git/stacks

### Parameters
#### Request Body
- **stackName** (string) - Required - The name of the stack.
- **environmentId** (integer) - Required - The ID of the environment.
- **url** (string) - Required - The URL of the git repository.
- **branch** (string) - Optional - The branch to use (defaults to main).
- **composePath** (string) - Optional - The path to the docker-compose file (defaults to docker/compose.yaml).
- **autoUpdate** (boolean) - Optional - Whether to enable automatic updates.
- **autoUpdateSchedule** (string) - Optional - The schedule for auto-updates (e.g., "custom").
- **autoUpdateCron** (string) - Optional - The cron expression for auto-updates.
- **webhookEnabled** (boolean) - Optional - Whether to enable webhooks.
- **deployNow** (boolean) - Optional - Whether to deploy immediately after creation.

### Request Example
```json
{
  "stackName": "myapp-git",
  "environmentId": 1,
  "url": "https://github.com/myorg/myapp.git",
  "branch": "main",
  "composePath": "docker/compose.yaml",
  "autoUpdate": true,
  "autoUpdateSchedule": "custom",
  "autoUpdateCron": "0 2 * * *",
  "webhookEnabled": true,
  "deployNow": true
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the created stack.
- **stackName** (string) - The name of the stack.
- **deployResult** (object) - The result of the deployment.
  - **success** (boolean) - Indicates if the deployment was successful.
  - **output** (string) - The output from the deployment process.
```

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

### Download a file from a container

Source: https://context7.com/finsys/dockhand/llms.txt

Download a file from a container to your local machine. Use the `-o` flag to specify the output file name.

```bash
curl -b cookies.txt \
  "http://localhost:3000/api/containers/abc123/files/download?env=1&path=/var/log/app.log" \
  -o app.log
```

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

### Get git stack webhook URL

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieves the webhook URL for a specific git stack. This URL can be used to receive notifications or trigger actions.

```APIDOC
## GET /api/git/stacks/[id]/webhook

### Description
Retrieves the webhook URL for a specific git stack. This URL can be used for external services to interact with the stack.

### Method
GET

### Endpoint
/api/git/stacks/[id]/webhook

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the git stack.

### Response
#### Success Response (200)
- **url** (string) - The webhook URL for the git stack.
- **enabled** (boolean) - Indicates if webhooks are enabled for the stack.
```

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

### List container filesystem entries

Source: https://context7.com/finsys/dockhand/llms.txt

Use this endpoint to list files and directories within a container's filesystem. Specify the path to browse.

```bash
# List directory
curl -b cookies.txt "http://localhost:3000/api/containers/abc123/files?env=1&path=/etc/nginx"
# → {"entries": [{"name": "nginx.conf", "type": "file", "size": 2048, ...}]}
```

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

### Get Docker Image History

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieve the layer history of a Docker image. This provides details about how the image was built, including commands executed at each layer.

```bash
curl -b cookies.txt "http://localhost:3000/api/images/sha256:abc123/history?env=1"
```

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

### List or create networks

Source: https://context7.com/finsys/dockhand/llms.txt

Allows listing existing networks or creating new ones within a specified environment. Supports defining network properties like name, driver, and IPAM configuration.

```APIDOC
## GET|POST /api/networks

### Description
Lists existing networks in a specified environment or creates a new network. Supports defining network name, driver, and IPAM configuration during creation.

### Method
GET, POST

### Endpoint
/api/networks

### Parameters
#### Query Parameters
- **env** (integer) - Required - The environment ID to list or create networks in.

#### Request Body (for POST)
- **name** (string) - Required - The name of the network to create.
- **driver** (string) - Optional - The network driver to use (e.g., "bridge").
- **internal** (boolean) - Optional - Whether the network is internal.
- **enableIPv6** (boolean) - Optional - Whether IPv6 is enabled.
- **ipam** (object) - Optional - IP Address Management configuration.
  - **driver** (string) - Optional - The IPAM driver.
  - **config** (array) - Optional - IPAM configuration options.
    - **Subnet** (string) - The subnet for the IPAM configuration.
    - **Gateway** (string) - The gateway for the IPAM configuration.

### Response
#### Success Response (200 - GET)
- **Id** (string) - The unique identifier of the network.
- **Name** (string) - The name of the network.
- **Driver** (string) - The driver used by the network.

#### Success Response (200 - POST)
- **success** (boolean) - Indicates if the network creation was successful.
- **id** (string) - The ID of the created network.
```

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

### Fetch Container Logs (Snapshot)

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieve a snapshot of container logs. The `tail` parameter can be used to specify the number of lines to fetch from the end of the logs.

```bash
curl -b cookies.txt "http://localhost:3000/api/containers/abc123/logs?env=1&tail=200"
```

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

### Get Git Stack Webhook URL

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieve the webhook URL for a specific git stack. This URL can be used by external services to trigger actions on the stack, such as deployments or updates.

```bash
curl -b cookies.txt http://localhost:3000/api/git/stacks/1/webhook
```

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

### Manage a Single Docker Environment

Source: https://context7.com/finsys/dockhand/llms.txt

Use `PUT` to update an existing environment by ID, and `DELETE` to remove it. A `POST` request to `/test` can verify connectivity.

```bash
curl -b cookies.txt -X PUT http://localhost:3000/api/environments/2 \
  -H "Content-Type: application/json" \
  -d '{"name": "prod-server-v2", "collectActivity": true}'
```

```bash
curl -b cookies.txt -X DELETE http://localhost:3000/api/environments/2
```

```bash
curl -b cookies.txt -X POST http://localhost:3000/api/environments/2/test
```

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

### Get Aggregated Dashboard Statistics

Source: https://context7.com/finsys/dockhand/llms.txt

Fetch aggregated statistics for the dashboard, including counts of running and stopped containers, images, volumes, and current CPU and memory usage. Requires authentication.

```bash
curl -b cookies.txt "http://localhost:3000/api/dashboard/stats?env=1"
# → {"running": 12, "stopped": 3, "images": 25, "volumes": 8, "cpu": 14.3, "memory": 42.7}
```

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

### List or create a Git-backed stack

Source: https://context7.com/finsys/dockhand/llms.txt

Lists existing Git-backed stacks or creates a new one from a Git repository.

```APIDOC
## GET|POST /api/git/stacks — List or create a Git-backed stack

### Description
Lists existing Git-backed stacks or creates a new one from a Git repository.

### Method
GET, POST

### Endpoint
/api/git/stacks

#### Query Parameters
- **env** (string) - Required - Environment identifier.

#### Request Body (for POST - not explicitly detailed, but implied by context)
- Requires parameters to specify the Git repository and stack configuration.

### Response
#### Success Response (200)
- **GET**: An array of Git stack objects, each with properties like `id`, `stackName`, `autoUpdate`, `autoUpdateCron`.
```

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

### Manage stack environment variables

Source: https://context7.com/finsys/dockhand/llms.txt

Get the environment variables for a stack, with secrets masked. You can also set or update environment variables, including secrets, using a JSON array payload.

```bash
# Get env vars (secrets masked)
curl -b cookies.txt "http://localhost:3000/api/stacks/myapp/env?env=1"
# → [{"key": "DB_HOST", "value": "db", "isSecret": false}, {"key": "DB_PASS", "value": "***", "isSecret": true}]
```

```bash
# Set env vars
curl -b cookies.txt -X POST "http://localhost:3000/api/stacks/myapp/env?env=1" \
  -H "Content-Type: application/json" \
  -d '[
    {"key": "DB_HOST", "value": "postgres", "isSecret": false},
    {"key": "DB_PASS", "value": "supersecret", "isSecret": true}
  ]'
# → {"success": true}
```

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

### List or create Docker environments

Source: https://context7.com/finsys/dockhand/llms.txt

Environments represent Docker hosts. Connection types include `socket`, `direct`, `hawser-standard`, and `hawser-edge`.

```APIDOC
## GET|POST /api/environments

### Description
Lists existing Docker environments or creates a new one.

### Method
GET, POST

### Endpoint
/api/environments

### Request Example (List)
```bash
curl -b cookies.txt http://localhost:3000/api/environments
```

### Request Example (Create Socket Environment)
```bash
curl -b cookies.txt -X POST http://localhost:3000/api/environments \
  -H "Content-Type: application/json" \
  -d '{"name": "local", "connectionType": "socket", "socketPath": "/var/run/docker.sock"}'
```

### Request Example (Create Direct TLS Environment)
```bash
curl -b cookies.txt -X POST http://localhost:3000/api/environments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-server",
    "connectionType": "direct",
    "host": "docker.prod.example.com",
    "port": 2376,
    "protocol": "https",
    "tlsCa": "-----BEGIN CERTIFICATE-----\n...",
    "tlsCert": "-----BEGIN CERTIFICATE-----\n...",
    "tlsKey": "-----BEGIN RSA PRIVATE KEY-----\n..."
  }'
```

### Response Example (List)
```json
[{"id": 1, "name": "local", "connectionType": "socket", "socketPath": "/var/run/docker.sock", ...}]
```

### Response Example (Create)
```json
{"id": 2, "name": "prod-server", ...}
```
```

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

### Create OIDC Provider Configuration

Source: https://context7.com/finsys/dockhand/llms.txt

Adds a new OIDC provider for Single Sign-On. Requires detailed configuration including issuer URL, client ID, client secret, and claims mapping for user roles.

```bash
curl -b cookies.txt -X POST http://localhost:3000/api/auth/oidc \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Keycloak",
    "enabled": true,
    "issuerUrl": "https://sso.example.com/realms/myrealm",
    "clientId": "dockhand",
    "clientSecret": "mysecret",
    "redirectUri": "https://dockhand.example.com/api/auth/oidc/callback",
    "scopes": "openid profile email",
    "usernameClaim": "preferred_username",
    "adminClaim": "groups",
    "adminValue": "docker-admins"
  }'
```

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

### List or create a Compose stack

Source: https://context7.com/finsys/dockhand/llms.txt

Lists existing Compose stacks or creates a new one based on provided configuration.

```APIDOC
## GET|POST /api/stacks — List or create a Compose stack

### Description
Lists existing Compose stacks or creates a new one based on provided configuration.

### Method
GET, POST

### Endpoint
/api/stacks

#### Query Parameters
- **env** (string) - Required - Environment identifier.

#### Request Body (for POST)
- **name** (string) - Required - The name of the stack.
- **compose** (string) - Optional - The Docker Compose content for the stack.
- **start** (boolean) - Optional - Whether to start the stack after creation. Defaults to true.
- **envVars** (array) - Optional - An array of environment variables for the stack.
  - **key** (string) - The environment variable key.
  - **value** (string) - The environment variable value.
  - **isSecret** (boolean) - Whether the variable is a secret.
- **rawEnvContent** (string) - Optional - Raw content for environment variables.

### Response
#### Success Response (200)
- **GET**: An array of stack objects, each with properties like `name`, `containers`, `status`, `sourceType`.
- **POST**: 
  - **success** (boolean) - Indicates if the stack creation was successful.
  - **started** (boolean) - Indicates if the stack was started.
```

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

### Create Apprise notification channel

Source: https://context7.com/finsys/dockhand/llms.txt

Set up a new notification channel using the Apprise library, which supports numerous services like Slack, Discord, and Telegram. Provide a list of Apprise URLs for configuration.

```bash
curl -b cookies.txt -X POST http://localhost:3000/api/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "apprise",
    "name": "SlackOps",
    "enabled": true,
    "config": {
      "urls": ["slack://TokenA/TokenB/TokenC/#ops-alerts"]
    },
    "eventTypes": ["container_stop", "update_available"]
  }'
```

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

### List or create volumes

Source: https://context7.com/finsys/dockhand/llms.txt

This endpoint allows for listing existing volumes or creating new ones within a specified environment. It supports filtering by environment and defining volume properties during creation.

```APIDOC
## GET|POST /api/volumes

### Description
Lists existing volumes in a specified environment or creates a new volume. Supports defining volume name, driver, and labels during creation.

### Method
GET, POST

### Endpoint
/api/volumes

### Parameters
#### Query Parameters
- **env** (integer) - Required - The environment ID to list or create volumes in.

#### Request Body (for POST)
- **name** (string) - Required - The name of the volume to create.
- **driver** (string) - Optional - The volume driver to use (defaults to "local").
- **labels** (object) - Optional - Labels to associate with the volume.

### Response
#### Success Response (200 - GET)
- **Name** (string) - The name of the volume.
- **Driver** (string) - The driver used by the volume.
- **Mountpoint** (string) - The path where the volume is mounted.

#### Success Response (200 - POST)
- **success** (boolean) - Indicates if the volume creation was successful.
- **name** (string) - The name of the created volume.
```

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

### Create Docker Container

Source: https://context7.com/finsys/dockhand/llms.txt

Create a new container within a specified environment. If the image is not found, it will be automatically pulled. Configuration options include port bindings and restart policies.

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers?env=1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-nginx",
    "image": "nginx:latest",
    "startAfterCreate": true,
    "ExposedPorts": {"80/tcp": {}},
    "HostConfig": {
      "PortBindings": {"80/tcp": [{"HostPort": "8080"}]},
      "RestartPolicy": {"Name": "unless-stopped"}
    },
    "Env": ["NGINX_HOST=example.com"]
  }'
```

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

### List all schedules

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieve a list of all configured schedules, including auto-update, git sync, and system cleanup tasks. The response details schedule properties like ID, type, name, cron expression, and next run time.

```bash
curl -b cookies.txt http://localhost:3000/api/schedules
```

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

### Use API Token for Authentication

Source: https://context7.com/finsys/dockhand/llms.txt

Demonstrates how to use a generated Bearer token for authentication in subsequent API requests. This bypasses the need for session cookies.

```bash
curl -H "Authorization: Bearer dh_abc123..." http://localhost:3000/api/containers?env=1
```

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

### Authenticate User with Local Credentials

Source: https://context7.com/finsys/dockhand/llms.txt

Use this endpoint to authenticate with local user credentials. It returns a session cookie on success and is rate-limited per IP and username.

```bash
curl -c cookies.txt -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "secret", "provider": "local"}'
```

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

### Browse container filesystem

Source: https://context7.com/finsys/dockhand/llms.txt

Lists the files and directories within a specified path in a container.

```APIDOC
## GET /api/containers/[id]/files — Browse container filesystem

### Description
Lists the files and directories within a specified path in a container.

### Method
GET

### Endpoint
/api/containers/[id]/files

#### Query Parameters
- **env** (string) - Required - Environment identifier.
- **path** (string) - Required - The path within the container to list.

### Response
#### Success Response (200)
- **entries** (array) - An array of objects, each representing a file or directory.
  - **name** (string) - The name of the file or directory.
  - **type** (string) - The type of the entry (e.g., 'file', 'directory').
  - **size** (integer) - The size of the file in bytes.
```

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

### Upload a file into a container

Source: https://context7.com/finsys/dockhand/llms.txt

Upload a local file to a specified path within a container. Use the `-F` flag for file uploads and specify the destination path.

```bash
curl -b cookies.txt -X POST "http://localhost:3000/api/containers/abc123/files/upload?env=1" \
  -F "file=@./nginx.conf" \
  -F "path=/etc/nginx/nginx.conf"
# → {"success": true}
```

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

### List Docker Containers

Source: https://context7.com/finsys/dockhand/llms.txt

List containers associated with a specific environment. Use the `all` query parameter to include stopped containers. Defaults to only running containers.

```bash
curl -b cookies.txt "http://localhost:3000/api/containers?env=1&all=true"
```

```bash
curl -b cookies.txt "http://localhost:3000/api/containers?env=1&all=false"
```

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

### Add a private registry

Source: https://context7.com/finsys/dockhand/llms.txt

Add a new private registry to the configuration. This includes providing the registry name, URL, and authentication credentials if required.

```bash
# Add a private registry
curl -b cookies.txt -X POST http://localhost:3000/api/registries \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyRegistry",
    "url": "https://registry.example.com",
    "username": "deployer",
    "password": "registrypass",
    "isDefault": false
  }'
```

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

### GET|POST /api/auth/tokens - List or create API tokens

Source: https://context7.com/finsys/dockhand/llms.txt

Allows listing existing API tokens or creating new ones. API tokens can be used for authentication instead of session cookies.

```APIDOC
## GET|POST /api/auth/tokens

### Description
Lists existing API tokens or creates new ones. API tokens can be used in place of session cookies via `Authorization: Bearer <token>`. Token creation requires a session login and password confirmation for local users.

### Method
GET, POST

### Endpoint
/api/auth/tokens

### Parameters (POST)
#### Request Body
- **name** (string) - Required - The name for the new API token.
- **password** (string) - Required - The user's password for confirmation (for local users).
- **expiresAt** (string) - Optional - The expiration date and time for the token in ISO 8601 format.

### Request Example (POST)
```json
{
  "name": "ci-deploy",
  "password": "mypassword",
  "expiresAt": "2025-12-31T23:59:59Z"
}
```

### Response (GET)
#### Success Response (200)
- **id** (integer) - The unique identifier of the token.
- **name** (string) - The name of the token.
- **tokenPrefix** (string) - The prefix of the generated token.
- **createdAt** (string) - The timestamp when the token was created.

### Response (POST)
#### Success Response (200)
- **id** (integer) - The unique identifier of the newly created token.
- **token** (string) - The full API token.
- **tokenPrefix** (string) - The prefix of the generated token.
```

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

### List Docker Images

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieve a list of Docker images available in the specified environment. Filtering by environment ID is supported.

```bash
curl -b cookies.txt "http://localhost:3000/api/images?env=1"
```

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

### Create API Token With Expiry

Source: https://context7.com/finsys/dockhand/llms.txt

Creates a new API token that will automatically expire at the specified `expiresAt` timestamp. This is useful for temporary access.

```bash
curl -b cookies.txt -X POST http://localhost:3000/api/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{"name": "temp-token", "expiresAt": "2025-12-31T23:59:59Z", "password": "mypassword"}'
```

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

### Clone Dockhand Repository

Source: https://github.com/finsys/dockhand/blob/main/CONTRIBUTING.md

Clone the Dockhand repository to your local machine. Ensure you are in the correct directory before proceeding.

```bash
git clone https://github.com/your-username/dockhand.git
cd dockhand
```

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

### Create SMTP notification channel

Source: https://context7.com/finsys/dockhand/llms.txt

Configure and create a new SMTP notification channel. Requires detailed configuration including host, port, sender/recipient emails, and authentication credentials.

```bash
curl -b cookies.txt -X POST http://localhost:3000/api/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "smtp",
    "name": "OpsEmail",
    "enabled": true,
    "config": {
      "host": "smtp.example.com",
      "port": 587,
      "from_email": "dockhand@example.com",
      "to_emails": ["ops@example.com"],
      "username": "dockhand@example.com",
      "password": "smtppass",
      "secure": false
    },
    "eventTypes": ["container_stop", "container_crash", "update_available", "stack_deploy_fail"]
  }'
```

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

### Host System Information

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieves information about the host system where Docker is running. An environment ID is required.

```APIDOC
## GET /api/system — Host system information

### Description
Retrieves detailed information about the host system's Docker environment.

### Method
GET

### Endpoint
/api/system

### Query Parameters
- **env** (string) - Required - The ID of the environment to get system information from.

### Response
#### Success Response (200)
- **DockerVersion** (string) - The version of Docker installed.
- **OperatingSystem** (string) - The operating system of the host.
- **NCPU** (integer) - The number of available CPUs.
- **MemTotal** (integer) - The total amount of memory in bytes.

### Request Example
```bash
curl -b cookies.txt "http://localhost:3000/api/system?env=1"
```

### Response Example
```json
{
  "DockerVersion": "27.3.1",
  "OperatingSystem": "Ubuntu 22.04",
  "NCPU": 8,
  "MemTotal": 16000000000
}
```
```

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

### List Existing API Tokens

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieves a list of all API tokens associated with the current session. Each token includes its ID, name, and a prefix for identification.

```bash
curl -b cookies.txt http://localhost:3000/api/auth/tokens
```

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

### List containers

Source: https://context7.com/finsys/dockhand/llms.txt

Lists containers within a specified environment, with an option to include all containers (not just running ones).

```APIDOC
## GET /api/containers

### Description
Lists containers in a specified environment. Can filter to show only running containers or all containers.

### Method
GET

### Endpoint
/api/containers

### Parameters
#### Query Parameters
- **env** (integer) - Required - The ID of the environment to list containers from.
- **all** (boolean) - Optional - If true, lists all containers; if false or omitted, lists only running containers.

### Request Example (All Containers)
```bash
curl -b cookies.txt "http://localhost:3000/api/containers?env=1&all=true"
```

### Request Example (Running Containers)
```bash
curl -b cookies.txt "http://localhost:3000/api/containers?env=1&all=false"
```

### Response Example
```json
[{"Id": "abc123", "Names": ["/myapp"], "Image": "nginx:latest", "State": "running", ...}]
```
```

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

### Container Resource Statistics

Source: https://context7.com/finsys/dockhand/llms.txt

Fetch container resource statistics including CPU, memory, and network I/O. These statistics are calculated similarly to the Docker CLI and are compatible with cgroup v1 and v2.

```bash
curl -b cookies.txt "http://localhost:3000/api/containers/abc123/stats?env=1"
```

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

### Browse volume contents

Source: https://context7.com/finsys/dockhand/llms.txt

Allows browsing the contents of a specific volume at a given path within a specified environment. Returns a list of files and directories.

```APIDOC
## GET /api/volumes/[name]/browse

### Description
Browses the contents of a specific volume at a given path within a specified environment. Returns a list of entries (files and directories) within the specified path.

### Method
GET

### Endpoint
/api/volumes/[name]/browse

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the volume to browse.
#### Query Parameters
- **env** (integer) - Required - The environment ID.
- **path** (string) - Required - The path within the volume to browse (e.g., "/").

### Response
#### Success Response (200)
- **entries** (array) - A list of entries within the specified path.
  - **name** (string) - The name of the file or directory.
  - **type** (string) - The type of the entry ("file" or "directory").
  - **size** (integer) - The size of the entry in bytes.
```

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

### Download a file from a container

Source: https://context7.com/finsys/dockhand/llms.txt

Downloads a file from a specified path within a container to the local system.

```APIDOC
## GET /api/containers/[id]/files/download — Download a file from a container

### Description
Downloads a file from a specified path within a container to the local system.

### Method
GET

### Endpoint
/api/containers/[id]/files/download

#### Query Parameters
- **env** (string) - Required - Environment identifier.
- **path** (string) - Required - The path to the file within the container.

### Response
#### Success Response (200)
- The response body will contain the content of the downloaded file.
```

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

### Fetch container logs (snapshot)

Source: https://context7.com/finsys/dockhand/llms.txt

Retrieves a snapshot of the logs for a specific container. Supports fetching a specific number of recent log lines.

```APIDOC
## GET /api/containers/[id]/logs

### Description
Fetches a snapshot of the logs for a given container. Allows specifying the number of lines to retrieve from the end of the logs.

### Method
GET

### Endpoint
/api/containers/[id]/logs

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the container.

#### Query Parameters
- **env** (integer) - Required - The ID of the environment the container belongs to.
- **tail** (integer) - Optional - The number of lines to return from the end of the logs.

### Request Example
```bash
curl -b cookies.txt "http://localhost:3000/api/containers/abc123/logs?env=1&tail=200"
```

### Response Example
```json
{"logs": "2024-01-15T10:00:00Z nginx started\n..."}
```
```

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

### Test environment connectivity

Source: https://context7.com/finsys/dockhand/llms.txt

Tests the connectivity to a specific Docker environment.

```APIDOC
## POST /api/environments/[id]/test

### Description
Tests the connectivity to a specified Docker environment.

### Method
POST

### Endpoint
/api/environments/[id]/test

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the environment to test.

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:3000/api/environments/2/test
```

### Response Example
```json
{"success": true, "version": "27.3.1"}
```
```