view release on metacpan or search on metacpan
misc/agent-context/.claude/skills/api-docker-type-model/references/dsl.md
misc/agent-context/.claude/skills/api-docker-type-model/references/types.md
misc/agent-context/.claude/skills/docker-engine-api/SKILL.md
misc/agent-context/.claude/skills/docker-engine-api/examples/python/README.md
misc/agent-context/.claude/skills/docker-engine-api/examples/python/engine_helpers.py
misc/agent-context/.claude/skills/docker-engine-api/examples/python/readonly_probe.py
misc/agent-context/.claude/skills/docker-engine-api/examples/python/tests/test_engine_helpers.py
misc/agent-context/.claude/skills/docker-engine-api/references/INDEX.md
misc/agent-context/.claude/skills/docker-engine-api/references/SOURCES.md
misc/agent-context/.claude/skills/docker-engine-api/references/clients/podman-and-other-engines.md
misc/agent-context/.claude/skills/docker-engine-api/references/clients/sdk-selection-and-language-notes.md
misc/agent-context/.claude/skills/docker-engine-api/references/clients/security-and-untrusted-input.md
misc/agent-context/.claude/skills/docker-engine-api/references/compatibility-policy.md
misc/agent-context/.claude/skills/docker-engine-api/references/containers/create-and-resource-policy.md
misc/agent-context/.claude/skills/docker-engine-api/references/containers/lifecycle-and-ownership.md
misc/agent-context/.claude/skills/docker-engine-api/references/http/request-shapes-and-encoding.md
misc/agent-context/.claude/skills/docker-engine-api/references/http/status-errors-and-retries.md
misc/agent-context/.claude/skills/docker-engine-api/references/images/build-context-and-buildkit-boundary.md
misc/agent-context/.claude/skills/docker-engine-api/references/images/pull-push-and-registry-auth.md
misc/agent-context/.claude/skills/docker-engine-api/references/observability/events-and-reconciliation.md
misc/agent-context/.claude/skills/docker-engine-api/references/observability/stats-and-accounting.md
lib/API/Docker/Role/HTTP.pm view on Meta::CPAN
die $err unless $ok;
return $sock;
}
# Whether the connect that has just failed failed because the bound fired.
# Asked with nothing in between, because $@ and $! are the whole of the
# evidence and both are global.
#
# $@ rather than errno: IO::Socket writes 'connect: timeout' there, and only
# there, when its own select() ran out -- measured, against a host that drops
# SYNs, where $! is ETIMEDOUT, which the kernel also produces on its own after
# two minutes with no Timeout set at all.
#
# EAGAIN is the second shape and belongs to unix:// alone. Measured against a
# listener whose backlog is full: with no Timeout the connect blocks
# indefinitely (still blocked after 8s), and with one it fails at once with
# EAGAIN, because IO::Socket does the timed connect non-blocking and an
# AF_UNIX connect has no in-progress state to wait on. So on that transport
# the option does not wait, it refuses -- but a connect that failed with
# EAGAIN is still one the bound ended, and reporting it as anything else would
lib/API/Docker/Role/HTTP.pm view on Meta::CPAN
sub _read_timeout_value {
my ($self, $timeout) = @_;
return $self->_timeout_value('read_timeout', $timeout);
}
sub _connect_timeout_value {
my ($self, $timeout) = @_;
return $self->_timeout_value('connect_timeout', $timeout);
}
# Why SO_RCVTIMEO and not select(): a bound that reads the socket cannot see
# what is already buffered above it, and would fire while the data it was
# waiting for was in hand. That was true of PerlIO's read-ahead when this was
# written (measured: after one readline of a socket holding
# "one\ntwo\nthree\n", two whole lines sit in the PerlIO buffer and select()
# says the handle is not ready), and it is true of _read_buffer now. A
# select-based bound would have to be asked only when that buffer is empty,
# which is one more invariant to keep for no gain: SO_RCVTIMEO bounds the one
# syscall in _pull for one setsockopt, and gets idle-since-the-last-byte
# semantics for free, which is the semantics these endpoints need (karr k52:
# the buffered frames arrive, and *then* the socket stalls -- a
# time-to-first-byte bound would never fire).
sub _apply_read_timeout {
my ($self, $sock, $timeout) = @_;
return unless $timeout;
lib/API/Docker/Role/HTTP.pm view on Meta::CPAN
# application/vnd.docker.raw-stream -- the reader asks for $READ_SIZE, so
# read() delivered nothing to an on_frame/on_chunk callback until 64K had
# piled up or the daemon hung up. On a stream that never ends it would deliver
# nothing at all. The POD promised those callbacks the bytes as they arrive,
# and that promise was not kept.
#
# Why it could not be fixed at the one site that had the bug: _read_head read
# the status line and the headers with <$sock>, and PerlIO reads ahead. The
# bytes past the header block were sitting in a buffer this code cannot reach
# -- there is no supported way to take them back out; ungetc is layer-
# dependent, seek does not work on a socket, and select/MSG_PEEK see the
# kernel's buffer rather than PerlIO's. So switching only the body reads to
# sysread would have silently dropped the start of every body. Either all read
# sites move together or none do.
#
# The buffer lives on the handle rather than on the client or in the context:
# it is the unconsumed bytes of *that* handle, its lifetime is the handle's,
# and a client that opens a socket per request therefore has nothing to reset.
# ${*$sock}{...} is the IO::Socket idiom for exactly this and was measured to
# work on a real socket, a lexical filehandle, a bareword glob and a tied
# handle alike.
lib/API/Docker/Type/HostConfig.pm view on Meta::CPAN
Gives the container full access to the host.
=head2 publish_all_ports
Allocates an ephemeral host port for all of a container's exposed ports.
Ports are de-allocated when the container stops and allocated when the
container starts. The allocated port might be changed when restarting the
container.
The port is selected from the ephemeral port range that depends on the
kernel. For example, on Linux the range is defined by
C</proc/sys/net/ipv4/ip_local_port_range>.
=head2 readonly_rootfs
Mount the container's root filesystem as read only.
=head2 security_opt
A list of string values to customize labels for MLS systems, such as
lib/API/Docker/Type/SwarmSpec/TaskDefaults/LogDriver.pm view on Meta::CPAN
Updating this value only affects new tasks. Existing tasks continue to use
their previously configured log driver until recreated.
=head2 name
The log driver to use as a default for new tasks.
=head2 options
Driver-specific options for the selected log driver, specified as key/value
pairs. B<The keys are the caller's data> and are never translated.
=head1 SUPPORT
=head2 Issues
Please report bugs and feature requests at
L<https://github.com/Getty/p5-api-docker/issues>.
=head1 CONTRIBUTING
misc/agent-context/.claude/skilletor.lock.json view on Meta::CPAN
"files": {
"skills/docker-engine-api/.gitignore": "sha256:fc8e72cc019d4536c45df00567078e36003f1d7183747e03283549741c3424c9",
"skills/docker-engine-api/SKILL.md": "sha256:266297caba595e31e957fbf479e0bd8eb27200b1c406828a78c9911aa1f36dba",
"skills/docker-engine-api/examples/python/README.md": "sha256:9e4feccfd95477ef7fd86b27152791200b856c288c3b5609a4d35ca4b636856d",
"skills/docker-engine-api/examples/python/engine_helpers.py": "sha256:84c9f81babfafcaee2f7fea0ee4db9acab0dc9230f224c3a9c4e35852cf3ad67",
"skills/docker-engine-api/examples/python/readonly_probe.py": "sha256:2c6aef18d5e43a115d191ba58ab4599938ceee9e1110244b0596737982ad7e56",
"skills/docker-engine-api/examples/python/tests/test_engine_helpers.py": "sha256:8bfbcd21970853cff0bae692c761cd02ea9f008a6aa014420d55ad923c691ecc",
"skills/docker-engine-api/references/INDEX.md": "sha256:cf702e746ce47d3657c14d1dc73564e71bc6d52f0541c4d9c8af34a2daa90a60",
"skills/docker-engine-api/references/SOURCES.md": "sha256:7b142db37983d16fce9af4df86fe440fb62ab4050ff035cee049a1333a75416b",
"skills/docker-engine-api/references/clients/podman-and-other-engines.md": "sha256:4c03c1c481e28c31efd4d80c2985a98b3feb13ca18a6c6ed66582431acc6a0e7",
"skills/docker-engine-api/references/clients/sdk-selection-and-language-notes.md": "sha256:33c3c0db4f8755d3d7344eb228c80a415630c1e637d64c59dd766da6feed8663",
"skills/docker-engine-api/references/clients/security-and-untrusted-input.md": "sha256:c88eb071c945d243bd35bcdba1bf61634498f94598a2f74453562ae2c182700a",
"skills/docker-engine-api/references/compatibility-policy.md": "sha256:88a241bbbe7eb76671a729f5691ea482df41bf4e8bf4a08dfc623ecc05269008",
"skills/docker-engine-api/references/containers/create-and-resource-policy.md": "sha256:8ffb08dfa3ea6bc3f6bb4df8c081fed6772b9bffa666395b9b4200c403b406b0",
"skills/docker-engine-api/references/containers/lifecycle-and-ownership.md": "sha256:3688cfb09680d5f360a6f0f872a589e044a5d481084b738f23e9efc0429ba613",
"skills/docker-engine-api/references/http/request-shapes-and-encoding.md": "sha256:9abe18e891eb77865bd115521a29590029064bc25d0ba56c63a466fdb4eed2c3",
"skills/docker-engine-api/references/http/status-errors-and-retries.md": "sha256:1c98ce38d09b0e8d80e73dcbceb0efb3ade2130dd9e264ef885c15aa174d01c0",
"skills/docker-engine-api/references/images/build-context-and-buildkit-boundary.md": "sha256:d49552b3590a6e92da271ba7cdd1628b15674e0f658430f14277ea5d94630350",
"skills/docker-engine-api/references/images/pull-push-and-registry-auth.md": "sha256:b3e12a457276122624a003d34612db9973c636aada964a6fca066ff3120eb5cf",
"skills/docker-engine-api/references/observability/events-and-reconciliation.md": "sha256:1e0b27e94787a0bcddcd78b61e5572cedf9e29e8fe7d5155fa93c3a33228eab8",
"skills/docker-engine-api/references/observability/stats-and-accounting.md": "sha256:7ad297084ba210c03891cf60d54b12974985454a23c895409c31f040e47f995f",
misc/agent-context/.claude/skills/docker-engine-api/SKILL.md view on Meta::CPAN
---
name: docker-engine-api
description: "Use when implementing, testing, or debugging a Docker Engine HTTP API client: socket/remote transport, API negotiation, container lifecycle, attach/exec/log framing, progress streams, image auth, events/stats, resource policy, archives,...
---
# Docker Engine HTTP API
Use this skill when software speaks directly to the Engine API instead of delegating the operation to Docker CLI/Compose. Documentation review: **2026-10-09**. This is a protocol and client-engineering guide, not an exhaustive endpoint dump or a repl...
## Acquire the contract first
Read the [compatibility policy](references/compatibility-policy.md) and [version negotiation](references/transport/version-negotiation.md). Record target implementation, endpoint/transport, server API range, the client's implemented API range, and re...
Pinned Moby **28.5.2 / API 1.51** sources support reproducible wire-format examples. They are not a latest-version claim. For additional endpoints or fields, fetch the exact target release's official schema and gate the implementation explicitly.
## Load by task
| Task or symptom | Required reference | Related reference |
|---|---|---|
| Wrong daemon, socket, TLS, or remote discovery | [Transport and discovery](references/transport/discovery-and-connections.md) | [Security](references/clients/security-and-untrusted-input.md) |
| Query encoding, filters, paths, or JSON body types | [Request shapes](references/http/request-shapes-and-encoding.md) | [Status and retries](references/http/status-errors-and-retries.md) |
| Create/start/stop/delete automation | [Lifecycle and ownership](references/containers/lifecycle-and-ownership.md) | [Create/resource policy](references/containers/create-and-resource-policy.md) |
| Garbage bytes in logs or truncated output | [Multiplexed output](references/streams/multiplexed-output.md) | [Hijack/attach/exec](references/streams/hijack-attach-and-exec.md) |
| Interactive execution or lost exit status | [Hijack/attach/exec](references/streams/hijack-attach-and-exec.md) | [Lifecycle](references/containers/lifecycle-and-ownership.md) |
| Pull/push/build reports false success | [Progress/completion](references/streams/json-progress-and-completion.md) | [Registry auth](references/images/pull-push-and-registry-auth.md) |
| Reimplementing a Docker build | [Build context/BuildKit boundary](references/images/build-context-and-buildkit-boundary.md) | [SDK selection](references/clients/sdk-selection-and-language-notes.md) |
| Dashboard, watcher, or resource accounting | [Events/reconciliation](references/observability/events-and-reconciliation.md) | [Stats](references/observability/stats-and-accounting.md) |
| Network, volume, or cleanup API | [Resources and prune](references/resources/networks-volumes-and-prune.md) | [Ownership](references/containers/lifecycle-and-ownership.md) |
| File copy into/out of containers | [Archives](references/resources/archives-and-copy.md) | [Input security](references/clients/security-and-untrusted-input.md) |
| Compose or Swarm through HTTP | [Control-plane boundaries](references/resources/swarm-and-compose-boundaries.md) | [SDK selection](references/clients/sdk-selection-and-language-notes.md) |
| Podman or another compatible engine | [Compatibility testing](references/clients/podman-and-other-engines.md) | [Conformance](references/testing-and-conformance.md) |
## Client invariants
Treat the Docker socket as a privileged control plane. Keep endpoint selection explicit; do not silently fall back to another daemon. Do not expose raw Engine access to untrusted callers. A policy must inspect mutation payloads, mounts, privileges, r...
Separate HTTP transport errors, endpoint statuses, streamed operation errors, and application exit status. Handle empty successful bodies without JSON decoding. Drain and validate finite operation streams before reporting completion. Reconcile after ...
For non-TTY streams, parse binary headers across arbitrary network boundaries; for TTY streams, preserve raw combined output. Put bounds on frames, JSON records, queues, and timeouts. Keep long-lived stream connections separate from ordinary requests...
Validate endpoint-specific filters and version-gated request fields. Malformed filters are not a safe deletion guard. Inspect actual created resource settings where policy enforcement matters. Never log credentials, registry auth headers, full contai...
## Implement and prove
Read [testing and conformance](references/testing-and-conformance.md) before claiming support. The [Python helper package](examples/python/README.md) supplies numeric version-range negotiation, padded registry auth encoding, bounded multiplex/NDJSON ...
misc/agent-context/.claude/skills/docker-engine-api/examples/python/engine_helpers.py view on Meta::CPAN
if minimum is None:
minimum = legacy_server_min
if minimum is None:
raise CompatibilityError('Server omitted MinAPIVersion; an explicit legacy policy is required')
smin = parse_version(minimum)
if cmin > cmax or smin > smax:
raise CompatibilityError('Invalid supported version range')
low, high = max(cmin, smin), min(cmax, smax)
if low > high:
raise CompatibilityError('Client and daemon API ranges do not intersect')
selected = parse_version(pin) if pin is not None else high
if not low <= selected <= high:
raise CompatibilityError('Pinned API version lies outside the shared supported range')
return f'{selected[0]}.{selected[1]}'
def encode_registry_auth(auth: Mapping[str, str]) -> str:
"""Padded URL-safe base64 JSON; output is a secret, not safe logging data."""
if not isinstance(auth, Mapping) or any(not isinstance(k, str) or not isinstance(v, str)
for k, v in auth.items()):
raise TypeError('Auth must map strings to strings')
raw = json.dumps(dict(auth), ensure_ascii=False, separators=(',', ':')).encode('utf-8')
return base64.urlsafe_b64encode(raw).decode('ascii')
misc/agent-context/.claude/skills/docker-engine-api/examples/python/readonly_probe.py view on Meta::CPAN
parser.error('--socket must identify an accessible Unix-domain socket')
try:
server = get_json(args.socket, '/version', args.timeout)
if not isinstance(server, dict):
raise ValueError('Version response must be an object')
version = negotiate_version(server, client_min=args.client_min, client_max=args.client_max,
pin=args.api_version, legacy_server_min=args.legacy_server_min)
rows = get_json(args.socket, f'/v{version}/containers/json?all=true', args.timeout)
if not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows):
raise ValueError('Container list response has an unexpected shape')
print(json.dumps({'socket': args.socket, 'selected_api': version,
'server_version': server.get('Version'),
'server_os': server.get('Os'),
'containers': [{key: row.get(key) for key in
('Id', 'Names', 'Image', 'State', 'Status')} for row in rows]}, indent=2))
return 0
except (OSError, ValueError, RuntimeError, http.client.HTTPException) as exc:
print(f'Probe failed: {exc}', file=sys.stderr)
return 1
misc/agent-context/.claude/skills/docker-engine-api/references/INDEX.md view on Meta::CPAN
# docker-engine-api: reference index
Read [the skill entrypoint](../SKILL.md) first. Follow only the links needed for the task. These are on-demand reference files, not instructions to load the whole directory.
## Clients
| Reference | Read when |
|---|---|
| [Podman compatibility and other Engine-like implementations](clients/podman-and-other-engines.md) | running a Docker API client against a non-Docker endpoint. |
| [SDK choice, language boundaries, and implementation scope](clients/sdk-selection-and-language-notes.md) | selecting Go/Python/Perl/C++ tooling or planning a minimal client. |
| [API-client security and delegated agent policy](clients/security-and-untrusted-input.md) | an agent, web service, CI runner, or plugin will call the daemon. |
## Start Here
| Reference | Read when |
|---|---|
| [Compatibility policy and contract acquisition](compatibility-policy.md) | starting a client or adding an API-dependent feature. |
| [Client conformance and failure-injection plan](testing-and-conformance.md) | claiming a supported client release or modifying a decoder. |
## Containers
misc/agent-context/.claude/skills/docker-engine-api/references/clients/sdk-selection-and-language-notes.md view on Meta::CPAN
# SDK choice, language boundaries, and implementation scope
> Read when: selecting Go/Python/Perl/C++ tooling or planning a minimal client.
Prefer a maintained SDK when it already handles transport, API negotiation, framing, and cancellation for your target. Read its actual version documentation; âDocker SDKâ does not imply every SDK has the same context discovery, timeout, async, or...
The official Go and Python guidance is the starting point. Pin dependencies, enable the documented negotiation mechanism, and test the supported daemon matrix. For Python, distinguish high-level object wrappers from the low-level API client, and clos...
## Implementing a smaller client
Separate endpoint transport, version selection, typed request construction, finite JSON responses, streaming decoders, and orchestration policy. This allows Perl, C, C++, Rust, or another implementation to reuse the same test vectors without sharing ...
Raw byte streams remain bytes until explicitly decoded. Languages with implicit string coercion must preserve JSON booleans, integer width, null/absent distinction, and URL-safe base64 padding. Nanosecond timestamps and large counters can exceed Java...
## What the included code is
`examples/python/engine_helpers.py` contains original, dependency-free framing, NDJSON, auth, and version helpers. `readonly_probe.py` demonstrates finite read-only HTTP over an explicit Unix socket. Neither is a full production Docker SDK; no SSH/np...
Use the helpers as tested building blocks or executable protocol fixtures. Production suitability additionally requires integration tests, endpoint-specific behavior, authentication management, telemetry/redaction, and the threat model in the securit...
## Primary sources
misc/agent-context/.claude/skills/docker-engine-api/references/clients/security-and-untrusted-input.md view on Meta::CPAN
A Docker API endpoint is a control plane, not a harmless data source. Decide whether the caller is a host administrator or a constrained user. A constrained-user service must enforce its own policy on resource identity, request bodies, data access, a...
## Minimum broker controls
Bind every request to an authenticated caller and allowed daemon/project. Authorize full resource IDs, not names supplied by a client. Enforce create-time allowlists for images, commands where needed, host paths, users, privileges, devices, namespace...
Read endpoints can expose environment values, paths, labels, logs, and archives containing secrets. âGET onlyâ is not equivalent to safe public read access. Redact at the field/content boundary and cap response sizes. A read-only socket mount doe...
## Streaming and routing defenses
Bound frames, records, body size, read duration, and concurrent streams. Avoid automatic redirects to arbitrary authorities for daemon requests. Do not allow user-selected socket paths or remote endpoints without SSRF/host-control policy. Treat daemo...
Keep auth headers and request bodies with credentials out of traces. Design structured audit records with operation identity, caller, target, policy decision, final observed state, and uncertainty. Avoid recording raw build contexts or archive conten...
## Operational approvals
Deletion, forced stop, arbitrary exec in production, host mounts, daemon config changes, and registry credential use require task-specific authorization. Separate approval from a later automatic retry so it cannot silently expand the target set. Reco...
## Primary sources
- [Protect Docker daemon access](https://docs.docker.com/engine/security/protect-access/)
misc/agent-context/.claude/skills/docker-engine-api/references/compatibility-policy.md view on Meta::CPAN
# Compatibility policy and contract acquisition
> Read when: starting a client or adding an API-dependent feature.
Declare supported client API range, Engine families/versions, operating systems, transports, and optional feature gates. Do not publish âDocker compatibleâ based on a successful ping. API version, implementation, operating mode, and feature avail...
The upstream version matrix is the current starting point. This package uses **Moby 28.5.2 / API 1.51** source snapshots to make framing/auth/filter observations reproducible. That is an implementation reference, not a claim that 1.51 is the latest A...
## Contract evidence order
Use the target release's API schema and official change history first. Use pinned implementation source when the schema omits a wire detail. Use an integration test against the supported engine for observable behavior. Record discrepancies rather tha...
The schema is open to additional fields, so tolerate unknown response fields while validating the fields necessary for your operation. Unknown or unsupported request fields may be ignored; a successful status is not proof that a requested security re...
## Capability record
Store daemon identity, detected implementation, negotiated version, OS/architecture, rootless status where exposed, and outcomes of safe feature probes. Cache these per endpoint/connection generation, not globally across all daemons. Re-evaluate afte...
misc/agent-context/.claude/skills/docker-engine-api/references/containers/lifecycle-and-ownership.md view on Meta::CPAN
Assign a unique operation label and retain the full returned container ID. Treat a preexisting name as a conflict to investigate, not permission to adopt or remove it. Ownership checks should include the expected labels and configuration, not just a ...
## Lost-response handling
A network error during create/start can leave a real container behind. Reconcile using operation identity before retrying. A response received by the server but not the client is an **unknown outcome**, not an automatic failure with no side effects.
To capture short-lived process output, establish an appropriate attach/log strategy before start. Avoid `AutoRemove` when the client must inspect exit state, collect archives, or reconcile after disconnection. Automatic deletion can erase precisely t...
## State and exit
Wait returns the workload's exit result according to the endpoint's selected condition; the HTTP status alone is not the workload exit code. Inspect the container for OOM/error/health evidence. A stopped container, an unhealthy running container, and...
On timeout, decide explicitly whether the workload should keep running, receive a graceful stop, or be forcibly terminated. Canceling a client request does not universally cancel the container's work. Apply cleanup in a finally/defer path only after ...
For stateful or production containers, prefer an explicit operator-controlled lifecycle. Do not reuse the disposable-job cleanup pattern for long-lived services with volumes. Compose ownership labels belong to Compose; an API client should not impers...
## Primary sources
- [Pinned Moby 28.5.2 API 1.51 schema (compatibility evidence, not latest)](https://raw.githubusercontent.com/moby/moby/v28.5.2/docs/api/v1.51.yaml)
- [Engine SDK/API examples](https://docs.docker.com/reference/api/engine/sdk/examples/)
- [Container wait](https://docs.docker.com/reference/cli/docker/container/wait/)
misc/agent-context/.claude/skills/docker-engine-api/references/http/request-shapes-and-encoding.md view on Meta::CPAN
# Request shapes, filters, identifiers, and URL encoding
> Read when: building API requests without an official SDK.
Use the selected schema for each query/body/header location. JSON body booleans are actual booleans. Query values are encoded strings. Numeric units vary by field: bytes, nanoseconds, CPU quota/period, and counts are not interchangeable. Preserve abs...
## Filters
The documented array form is a JSON object such as `{"label":["owner=example"],"status":["running"]}`, then URL-encoded as **one** query parameter. Pinned Moby source also supports its map-of-boolean-sets representation. This does not mean arbitrary ...
Malformed filters can produce errors. Never promise they always yield an empty or unfiltered result. Validate inputs locally, check endpoint-specific allowed keys, and test negative cases. Filter semantics are endpoint-specific; do not generalize eve...
```python
from urllib.parse import urlencode
import json
misc/agent-context/.claude/skills/docker-engine-api/references/http/status-errors-and-retries.md view on Meta::CPAN
Progress-stream operations can fail after an initial successful HTTP status. Consume build/pull/push messages to their intended completion and check in-band error fields. Early authentication/validation errors can still be ordinary non-2xx responses;...
## Retry classes
Retry safe reads with bounded exponential backoff and jitter where appropriate. Reconcile state after an ambiguous mutation. If a create request timed out, the daemon may have created the container. Find the intended object using a unique name/owners...
Starting an already running owned container may be an acceptable idempotent outcome. Exec creation/start is not a business-operation idempotency mechanism: retrying a payment, migration, or job command can duplicate effects. The application needs its...
## Result contract
Return operation ID, daemon identity, selected API version, affected full resource ID, final observed state, and uncertainty where completion is unknown. A client-side timeout is not proof that the server rolled back or stopped working. Avoid âsucc...
## Primary sources
- [Pinned Moby 28.5.2 API 1.51 schema (compatibility evidence, not latest)](https://raw.githubusercontent.com/moby/moby/v28.5.2/docs/api/v1.51.yaml)
- [Engine SDK/API examples](https://docs.docker.com/reference/api/engine/sdk/examples/)
- [Engine API overview and version matrix](https://docs.docker.com/reference/api/engine/)
misc/agent-context/.claude/skills/docker-engine-api/references/images/pull-push-and-registry-auth.md view on Meta::CPAN
Encode the JSON auth object using **padded URL-safe base64**, matching Moby's encoder. An explicit empty object encodes as `e30=`. Keep padding; do not substitute standard base64 or an unpadded variant merely because a particular value appears to wor...
```python
import base64, json
header = base64.urlsafe_b64encode(
json.dumps({"username": "user", "password": "secret", "serveraddress": "registry.example.com"},
separators=(",", ":")).encode("utf-8")
).decode("ascii")
```
Do not put real credentials in source or logs. The example explains encoding only. Prefer credential-helper integration and short-lived scoped credentials. Treat `identitytoken` and `registrytoken` according to the selected endpoint/auth flow rather ...
## Correct the anonymous-push assumption
The pinned Moby decoder accepts an empty/missing auth value as an empty configuration. Consequently, âevery anonymous push always requires this headerâ is not a universal daemon rule. Supply the documented format when credentials are needed or wh...
Pull/push progress still needs in-band error handling. An HTTP 200 does not prove the registry accepted all content. Verify the intended digest and platform set. A tag accepted by the daemon can refer to a different local image than the release you i...
For registry token challenges, repository scopes, cross-host redirects, and OCI distribution requests made **directly** to a registry, switch to the `docker-registry` skill.
## Primary sources
misc/agent-context/.claude/skills/docker-engine-api/references/observability/events-and-reconciliation.md view on Meta::CPAN
# Events and reconciliation loops
> Read when: building a dashboard, controller, or long-running watcher.
Use events as change notifications, not a durable database. Engine event history is bounded; the CLI documents only the last 256 retained events. A long disconnect can lose history even if the client supplies `since`.
## Controller pattern
Establish an event stream and buffer a bounded overlap while obtaining a current snapshot. Reconcile by full resource ID and daemon identity. Apply buffered events, then continue streaming. Periodically reconcile authoritative list/inspect state agai...
There is no globally reliable monotonically increasing event ID you can treat as a Kafka offset. A composite deduplication key can include daemon, resource, action, timestamp, and selected attributes, but collisions/repeats still require idempotent s...
Keep filters narrow enough for workload and resource ownership, but do not filter out the lifecycle transitions needed to detect removals. Events from one Engine do not provide cluster-wide truth for unrelated daemons. Swarm event scope also differs ...
## Failure behavior
Separate stream health from workload health. A quiet connection may be normal, while a frozen proxy can look identical without a heartbeat/reconciliation policy. Do not restart workloads merely because the watcher lost connectivity. Bound reconnect b...
Store meaningful operational audit outside the daemon with redaction and retention. Test a burst larger than the retention window, a daemon restart, observer downtime, duplicate delivery, removal between list and inspect, and unknown event attributes...
## Primary sources
misc/agent-context/.claude/skills/docker-engine-api/references/resources/networks-volumes-and-prune.md view on Meta::CPAN
> Read when: automating resource creation or cleanup.
Use typed requests and full identifiers for network/volume operations. Distinguish the logical resource from a container attachment. A disconnected volume can still hold valuable data; an unused network can still be reserved for a deployment. Absence...
## Ownership model
Create resources with an application-specific owner label and operation identity. Maintain an inventory of expected names/IDs, configurations, consumers, and retention state. Before reuse, inspect existing resources and check compatibility rather tha...
## Deletion protocol
Require a concrete target set, ownership verification, reason, expected effect, backup/recovery status for stateful data, and approval. Prefer deleting explicit owned IDs to a broad prune request. If prune is used, validate its filter syntax and endp...
Do not promise every prune endpoint offers a dry run. A preceding list is an approximation that can race, not an atomic transaction. Keep a conservative allowlist and refuse deletion when ownership or state is uncertain. Avoid `force` as the default.
## Recovery and error handling
When a container references a resource being removed, distinguish a conflict from permission or backend failure. A network disconnection can interrupt active requests. Volume deletion is not reversible by recreating a volume with the same name. If de...
For Kubernetes-owned runtime storage or networks, do not bypass the owning control plane casually. Engine API is not a general containerd administration surface, even if Docker internally uses containerd.
## Primary sources
misc/agent-context/.claude/skills/docker-engine-api/references/resources/swarm-and-compose-boundaries.md view on Meta::CPAN
# Swarm objects, Compose orchestration, and concurrency control
> Read when: a client encounters services/tasks/secrets or wants to reproduce Compose.
Engine container operations and Swarm service operations describe different abstractions. A Swarm service is a desired specification whose tasks are scheduled by the orchestrator. Updating a service is not equivalent to changing one container. Nodes,...
For versioned Swarm updates, read the current object/version and use the documented optimistic-concurrency field. On conflict, reread and reconcile desired changes against current state. Do not blindly retry a stale full object and overwrite someone ...
## Secrets/configs
Swarm-managed secrets are not local Compose file-backed secrets. Do not use the existence of Engine secret endpoints to claim a standalone Compose deployment has the same encryption/distribution semantics. Local Compose maps its project model to seve...
Official Compose documentation now describes a Go SDK in Compose v5. For embedding full Compose behavior, evaluate that documented surface and its supported version rather than implementing a partial YAML-to-container translator and calling it compat...
## Scope statement
A small client can intentionally support standalone container lifecycle and leave Swarm/Compose out of scope. Make that an explicit capability error. If service management is required, test manager versus worker behavior, concurrent updates, rollback...
misc/agent-context/.claude/skills/docker-engine-api/references/streams/hijack-attach-and-exec.md view on Meta::CPAN
# Hijacked connections, attach, exec, and terminal behavior
> Read when: implementing interactive commands or bidirectional streaming.
Exec has an instance-creation step and a start step. Obtain the final exit code from exec inspection after completion; start success does not mean the command exited successfully. Detached start also needs later observation. Container attach is a dif...
Some interactive endpoints upgrade/hijack HTTP into a bidirectional connection. Handle the selected endpoint's documented 101/200 behavior using a compatible transport. A normal HTTP response-body reader is not automatically a correct bidirectional a...
## Direction matters
Docker's multiplex header describes daemon output. Do not prepend those headers to stdin indiscriminately; the attach input direction uses the endpoint's raw stream contract. Preserve half-close semantics where supported so EOF on stdin does not prem...
TTY mode combines stdout/stderr and carries terminal control sequences. Use it only when terminal semantics are needed. For machine-readable output and separate error handling, prefer non-TTY mode. An interactive session must restore the user's termi...
## Transport acceptance tests
Run a command that writes distinct stdout and stderr, a command that waits for stdin EOF, a command that emits final output during shutdown, and a command whose result is nonzero. Repeat through the actual SSH/TLS/proxy path. Verify no output is lost...
misc/agent-context/.claude/skills/docker-engine-api/references/streams/json-progress-and-completion.md view on Meta::CPAN
Handle both ordinary non-2xx failures and successful headers followed by an operation error in the body stream. Messages can contain status/progress, textual build output, auxiliary results, `error`, or `errorDetail`. Preserve structured error contex...
For documented newline-delimited JSON endpoints, buffer across network chunks, parse complete objects, enforce a per-record limit, and process a final record even if it lacks a trailing newline. Do not assume every HTTP chunk is one JSON message. A b...
```text
HTTP status -> validate endpoint status class
body chunks -> bounded record parser -> progress/error handler
stream end -> transport complete? operation error seen? result evidence present?
```
Honor the actual `Content-Type` and selected endpoint contract. A different format, such as RFC 7464 JSON sequences, must not be treated as NDJSON merely because both contain JSON. Unknown media types require a deliberate compatibility path, not blin...
## Completion policy
Do not declare success after the first progress record. At a minimum, finish the documented stream and reject in-band errors. For important operations, verify the expected artifact/container state afterward. Transport closure may be ambiguous; whethe...
Keep progress reporting backpressured and bounded. A slow user interface should not cause unbounded memory growth. Handle caller cancellation by closing resources and reporting whether final server state is known. Store enough operation identity to r...
The included parser covers fragmented reads, CRLF, blank lines, trailing records, malformed JSON, size limits, and in-band errors. It is deliberately scoped to NDJSON. Do not reuse it for raw TTY streams, binary frames, or arbitrary concatenated JSON...
## Primary sources
misc/agent-context/.claude/skills/docker-engine-api/references/testing-and-conformance.md view on Meta::CPAN
|---|---|
| Version | Oldest supported, newest supported, newer-than-client, disjoint range |
| Transport | Every supported Unix/TLS/SSH/npipe path; actual reverse proxy if any |
| Engine | Docker rootful/rootless; Podman only when advertised |
| Platform | Linux/Windows and architectures actually supported |
| Streams | TTY/non-TTY, slow consumer, partial write/read, abrupt disconnect |
| Lifecycle | Fast exit, nonzero exit, timeout, lost create response, auto-remove race |
| Security | Rejected unsafe mounts/privileges; effective-state verification |
| Storage | Archive traversal, permissions, volume retention, scoped cleanup |
Use a dedicated disposable daemon/project, never a shared production target. Give fixtures unique labels and clean up only their IDs. Test no-op/status behavior and compare with the selected schema. Introduce an in-band pull/build failure after succe...
## Evidence report
Record versions, daemon identity, feature scope, tested transports, test results, known limitations, and unresolved discrepancies. Distinguish syntax/unit validation from a live daemon test. The delivery's validation report states which checks were a...
Before extending support, add a failing regression fixture that represents the new behavior. Do not broaden advertised compatibility merely because an API prefix is accepted or a server returns extra fields without error.
## Primary sources
- [Engine API overview and version matrix](https://docs.docker.com/reference/api/engine/)
misc/agent-context/.claude/skills/docker-engine-api/references/transport/discovery-and-connections.md view on Meta::CPAN
# Endpoint discovery and connection management
> Read when: opening a Unix socket, SSH transport, named pipe, or TLS endpoint.
Make endpoint selection explicit and observable. Linux rootful Docker commonly uses `/var/run/docker.sock`; rootless Docker uses a user-specific endpoint; Desktop and native Windows have different contexts/transports. A hardcoded Unix socket is a val...
For library clients, use documented environment/context integration. Do not assume every SDK honors `DOCKER_HOST`, `DOCKER_CONTEXT`, or CLI context metadata in the same way. `DOCKER_HOST` is a common convention, not an obligation binding every librar...
## Connection classes
Keep ordinary finite HTTP requests separate from long-lived events/stats/log streams and hijacked interactive sessions. A stuck stream must not consume every connection needed for stop/inspect requests. Use explicit dial/TLS/header deadlines, operati...
A Unix socket carries HTTP without a network TCP endpoint. The URL host used by a Unix-socket HTTP client can be a routing placeholder; the filesystem socket selects the daemon. SSH transports need a compatible SDK dialer or a controlled tunnel, not ...
## Identity and trust
Authenticate remote access with SSH or mutual TLS. Verify server identity and protect client keys. A local TCP endpoint is not automatically safe from other local users or browser-origin attacks. Do not enable unauthenticated TCP as a convenience fal...
On failed connection, report selected endpoint, transport phase, timeout, and sanitized error. Do not print certificate private keys, full Docker config, or credential headers. A retry to another daemon is not transparent failover unless that daemon ...
## Primary sources
- [Protect Docker daemon access](https://docs.docker.com/engine/security/protect-access/)
- [Docker contexts](https://docs.docker.com/engine/manage-resources/contexts/)
- [Rootless Docker](https://docs.docker.com/engine/security/rootless/)
- [Docker SDK for Python client](https://docker-py.readthedocs.io/en/stable/client.html)
- [Podman system service and Docker compatibility layer](https://docs.podman.io/en/latest/markdown/podman-system-service.1.html)
misc/agent-context/.claude/skills/docker-engine-api/references/transport/version-negotiation.md view on Meta::CPAN
> Read when: choosing request prefixes or handling new/old daemon combinations.
Discover server `ApiVersion` and `MinAPIVersion` using the supported unversioned discovery endpoint. Treat versions as integer pairs, never floats or lexical strings: `1.9` must compare lower than `1.10`.
Let the client understand `[client_min, client_max]` and the daemon accept `[server_min, server_max]`. Then:
```text
lower = max(client_min, server_min)
upper = min(client_max, server_max)
if lower > upper: fail with an explicit compatibility error
selected = upper
```
Do **not** simply adopt the server maximum: the client may not understand it. Prefix subsequent versioned operations with the selected version. Feature requirements must fit that version, and platform/implementation support must still be verified.
## Overrides and missing discovery fields
An explicit API version setting is a pin, not negotiation. Check that the chosen version lies within both supported ranges. Official CLI/SDK `DOCKER_API_VERSION` behavior can disable negotiation; make that visible in diagnostics.
For old or compatible implementations that omit a minimum version, choose and document a legacy compatibility policy. The included helper fails closed unless a caller supplies a deliberate fallback. Do not invent a server minimum silently. An unavail...
## Upgrade test cases
Test older server, newer server, disjoint ranges, explicit pin outside range, missing/malformed fields, and numeric ordering. Test a supported field and a field introduced later than the selected version. A server that ignores unknown fields can othe...
The included Python helper implements range intersection and pin validation with unit tests. Its configured client range belongs to the caller; its existence does not prove that the caller actually implements every endpoint in that range.
## Primary sources
- [Engine API overview and version matrix](https://docs.docker.com/reference/api/engine/)
- [Engine API version history](https://docs.docker.com/reference/api/engine/version-history/)
- [Pinned Moby 28.5.2 API 1.51 schema (compatibility evidence, not latest)](https://raw.githubusercontent.com/moby/moby/v28.5.2/docs/api/v1.51.yaml)
misc/agent-context/.claude/skills/kanban-issues-karr-coordination/SKILL.md view on Meta::CPAN
bodies) a card is `k12`, never `#12` â the forge resolves `#12` against its
own issue 12. Commands take `k12` as well as `12`.
## Name yourself once
```bash
export KARR_CLAIM=$(karr agent-name) # the checkout's directory name, e.g. "karr"
```
Claims are matched by name: `--claim` stamps it, `handoff` checks it,
`list --claimed-by` selects on it. Export `KARR_CLAIM` once per session and
leave `--claim` off: `pick`, `handoff` and `list --claimed-by` default to it,
and `move` and `edit` know a card you hold by it. `create`, `move` and `edit`
write it onto a card only when the card ends up in a `require_claim` column:
filing a card, promoting it to `todo` or adding a note leaves it free.
`archive` and `delete` ignore it â a card you hold needs `--claim NAME` there.
An explicit `--claim NAME` still wins. Agents in separate worktrees already
differ by name; several agents in the **same** directory take
`karr agent-name --unique` (`karr-8fa`).
## The board is the exchange â keep it pushed
misc/agent-context/.claude/skills/kanban-issues-karr-coordination/references/claims.md view on Meta::CPAN
# Claims: pick, handoff, unlock, several agents on one board
## The claim name
Claims are matched by name: `--claim` stamps it, `handoff` and `pick` check
it, `list --claimed-by` and `log --agent` select on it. Every command taking
`--claim` (`create`, `move`, `edit`, `pick`, `handoff`, `delete`, `archive`)
and `list --claimed-by` defaults to `KARR_CLAIM`; an explicit `--claim NAME`
wins over it. `create`, `move` and `edit` are narrower: they take `KARR_CLAIM`
only when the card ends up in a `require_claim` column, so a card filed,
promoted to `todo` or annotated for others stays unclaimed. `edit --release`
never claims. `backlog` holds no claim at all: an explicit `--claim` onto a
backlog card is refused (exit 1, naming `karr move ID todo --claim NAME`), and
moving a card into backlog releases the claim it carried.
karr writes the name nowhere â it is per process, so concurrent agents never
see each other's.
misc/agent-context/.claude/skills/kanban-issues-karr-coordination/references/cross-board.md view on Meta::CPAN
a directory from `--board NAME=PATH` or from the fleet config, matching the
repository's directory basename.
`--resolve` settles a link whose far card has reached one of the **far**
board's own terminal statuses, and lifts `blocked` when a card's last link
settles, printing the reason it lifted. A far card that does not exist settles
nothing. A board this machine cannot place is reported, not fatal.
Like `depends_on`, a cross-board link blocks nothing by itself: `pick` hands
the card over and says what it waits on. The `blocked` flag is what keeps the
card out of `pick` and out of karr-foundation's selection â the link is the
fact, `blocked` is the decision.
## How it is stored
The links ride in `tags` (`needs:BOARD#ID`, `escalated-from:BOARD#ID`), not
in a frontmatter field of their own: kanban-md marshals a card from its own
struct and would drop an unmodelled key the first time it writes, while `tags`
is modelled on both sides.
t/connect_timeout.t view on Meta::CPAN
'and the read timeout still names itself';
};
# ---------------------------------------------------------------------------
# What counts as the bound firing, and what does not. This is the whole of the
# discrimination: a refused connection and a missing socket path are diagnoses
# the caller can act on, and reporting them as a timeout would replace one with
# a cause that is not true.
subtest '_connect_expired: only the bound firing counts as a timeout' => sub {
{
# IO::Socket's own marker for its select() running out, measured against a
# host that drops SYNs.
local $@ = 'IO::Socket::INET: connect: timeout';
local $! = Errno::ETIMEDOUT();
ok $client->_connect_expired(2), q{'connect: timeout' is the bound};
ok !$client->_connect_expired(undef),
'but not with no connect_timeout in force -- the kernel produces '
. 'ETIMEDOUT on its own after two minutes';
}
{
t/tls_read.t view on Meta::CPAN
#!/usr/bin/env perl
use strict;
use warnings;
use Test::More;
use Config;
use Path::Tiny;
use Time::HiRes qw( time sleep );
use API::Docker;
use API::Docker::Error::Timeout;
# karr k65. t/tls.t covers option assembly, certificate selection and the
# handshake; nothing in the suite ever reads a byte over TLS. This file is
# that read path, pinned against the three measurements taken by hand
# during the transport rebuild (karr k60), before and after, identical both
# times:
#
# three writes 0.15s apart -> 3 on_chunk calls, spaced apart
# 100000 bytes over many records -> every byte arrives, none lost
# delivered, then silent, read_timeout 1 -> Error::Timeout after ~1s,
# phase 'read', summary delivered=1, the bytes already with the callback
#