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 container and Docker Compose operations in a controlled way.

Features

Docker actions: start, stop, restart, list for containers.
Compose actions: compose_up, compose_down, compose_run, compose_exec, compose_logs, compose_config, compose_build, compose_wait.
Secret-safe configuration: secrets must be provided via env_file; secret-looking keys in environment / build_args are rejected; compose_config output masks secret-looking values.
Execution state reporting: results include state (command_completed | service_started | timed_out) and timed_out.
Configurable base path sandbox: prevents using working directories, compose files or env 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'];
$timedOut = $result->result['timed_out'];
$state = $result->result['state'];

Supported actions

The docker_tool supports the following actions:

Action	Purpose	Required parameters
`list`	List containers	—
`start`	Start a container	`container`
`stop`	Stop a container	`container`
`restart`	Restart a container	`container`
`compose_up`	Bring up Compose services in detached mode (`-d`)	`compose_file`
`compose_down`	Bring down Compose services	`compose_file`
`compose_run`	Run a one-off command in a service (`--rm`, optional `--build`)	`compose_file`, `service`
`compose_exec`	Execute a command in a running service	`compose_file`, `service`, `command`
`compose_logs`	Fetch service logs (`--no-color`, optional `--tail`)	`compose_file`
`compose_config`	Render fully interpolated Compose config as JSON	`compose_file`
`compose_build`	Build a service image (optional `build_args`)	`compose_file`, `service`
`compose_wait`	Block until a service exits and return its exit code	`compose_file`, `service`

Notes:

compose_* actions do not accept the container parameter.
Simple container actions (start / stop / restart / list) do not accept compose_file.
compose_up only reports that the service process was started (state: service_started). To confirm the service finished with exit code 0, call compose_wait afterwards.
compose_run always runs with --rm.

Environment variables and secrets

Secret values (API keys, tokens, passwords) must never be passed via environment or build_args.

Use env_file (list of .env paths relative to base_path) — the only supported way to provide secrets to Compose.
Inline environment / build_args keys containing KEY, SECRET, TOKEN, PASSWORD or PASS (case-insensitive substring) are rejected with an error.
compose_config output masks secret-looking keys under services.*.environment and services.*.build.args as ***MASKED***.

Example — one-off run with a .env file:

$result = $facade->callTool(new ToolCallRequestDto(
    'docker_tool',
    [
        'action' => 'compose_run',
        'compose_file' => 'docker-compose.yml',
        'service' => 'app',
        'env_file' => ['.env'],
        'command' => ['npm', 'run', 'test'],
    ],
));

Example — build with non-secret build args, then up:

$facade->callTool(new ToolCallRequestDto(
    'docker_tool',
    [
        'action' => 'compose_build',
        'compose_file' => 'docker-compose.yml',
        'service' => 'app',
        'build_args' => [
            'NODE_ENV' => 'production',
        ],
    ],
));

$facade->callTool(new ToolCallRequestDto(
    'docker_tool',
    [
        'action' => 'compose_up',
        'compose_file' => 'docker-compose.yml',
        'env_file' => ['.env'],
    ],
));

HTTP verification inside containers

This tool does not expose host↔container networking directly. To verify that an HTTP endpoint inside a container actually responds, use compose_exec with a command such as ["curl", "-fsS", "http://localhost:PORT/path"] executed inside the target service container (or another service on the same Compose network). Do not rely on an independent HTTP client on the host — host localhost may reach an unrelated process.

Configuration

The tool is configured via DockerToolConfig and the DockerToolFactory:

base_path (required in ConfigMap): base directory for allowed working directories, compose files and env 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, entries in env_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.

adachsoft / ai-docker-tool

Maintainers

Package info

Statistics

Security