adachsoft/ai-docker-tool

AI Docker Tool

adachsoft/ai-docker-tool is a small PHP 8.3+ library that exposes a safe, high-level Docker management tool as an AI tool-call (SPI) implementation.

It provides a single tool, docker_tool, that can be called from higher-level AI orchestration code to perform basic container management operations in a controlled way.

Features

• Docker actions: start, stop, restart, list for containers, and compose_up, compose_down for Docker Compose services. compose_up always runs in detached mode.
• Configurable base path sandbox: prevents using working directories or compose files outside the allowed base path.
• Timeout limits: default and maximum timeout configuration for Docker commands.
• Output processing: truncation and base-path sanitisation of stdout/stderr for safe logging and AI responses.
• SPI integration: ready to plug into adachsoft/ai-tool-call as a tool implementation.

Requirements

• PHP 8.3 or higher.
• Docker CLI available on the system (docker binary on PATH, or a custom path in config).

Installation

Install via Composer:

composer require adachsoft/ai-docker-tool

For development tooling (code style, static analysis, refactoring):

composer require --dev adachsoft/php-code-style friendsofphp/php-cs-fixer phpstan/phpstan rector/rector phpunit/phpunit

Basic usage

The library is designed to be used through the adachsoft/ai-tool-call SPI. A typical setup is:

<?php

declare(strict_types=1);

use AdachSoft\AiDockerTool\Tool\DockerToolFactory;
use AdachSoft\AiToolCall\PublicApi\Builder\AiToolCallFacadeBuilder;
use AdachSoft\AiToolCall\PublicApi\Dto\ToolCallRequestDto;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;

$facade = AiToolCallFacadeBuilder::new()
    ->withSpiFactories([
        new DockerToolFactory(),
    ])
    ->withToolConfigs([
        'docker_tool' => new ConfigMap([
            'base_path' => __DIR__,
        ]),
    ])
    ->build();

$request = new ToolCallRequestDto(
    'docker_tool',
    [
        'action' => 'list',
    ],
);

$result = $facade->callTool($request);

$stdout = $result->result['stdout'];
$stderr = $result->result['stderr'];
$exitCode = $result->result['exit_code'];
$success = $result->result['success'];

Supported actions

The docker_tool currently supports the following actions:

• list – list containers.
• start – start a container (requires container parameter).
• stop – stop a container (requires container parameter).
• restart – restart a container (requires container parameter).
• compose_up – bring up services via Docker Compose in detached mode. Wymaga parametru compose_file.
• compose_down – bring down services via Docker Compose. Wymaga parametru compose_file.

Note: compose_up and compose_down do not accept the container parameter.

Configuration

The tool is configured via DockerToolConfig and the DockerToolFactory:

• base_path (required in ConfigMap): base directory for allowed working directories and compose files.
• docker_path (optional): path to the docker binary (defaults to docker).
• default_timeout (optional): default timeout for commands in seconds.
• max_timeout (optional): maximum allowed timeout for commands in seconds.
• max_output_length (optional): maximum length of captured stdout/stderr.

Sandbox and paths

• base_path is a required key in the tool configuration (ConfigMap) and is used to create a sandbox.
• All input paths (working_directory, compose_file) MUST be relative paths to the base_path.
• Example: if base_path is /var/app, and you want to use /var/app/project/docker-compose.yml, you should pass project/docker-compose.yml as compose_file.

Versioning

This library is versioned via Git tags, starting from 0.1.0 as the initial public release.

License

This project is licensed under the MIT License. See the LICENSE file for details.