README

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

• Simple Docker actions: start, stop, restart, list for containers.
• Configurable base path sandbox: prevents using working directories 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).

Configuration

The tool is configured via DockerToolConfig and the DockerToolFactory:

• base_path (required): base directory for allowed working directories.
• 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.

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.