Skip to content

PostgreSQL backup tool with Point-In-Time-Recovery and restore verification

FIX (verification): Run restore containers without a CPU limit on hosts lacking CFS quota, so verification works on NAS kernels that reject NanoCPUs

Rostislav Dugin82071fdc5712
diff --git a/agent/verification/internal/features/container/dockerengine.go b/agent/verification/internal/features/container/dockerengine.go
index c5354957..5cc2274e 100644
--- a/agent/verification/internal/features/container/dockerengine.go
+++ b/agent/verification/internal/features/container/dockerengine.go
@@ -9,12 +9,14 @@ import (
"fmt"
"io"
"net/netip"
+ "slices"
"strconv"
"strings"
"github.com/moby/moby/api/pkg/stdcopy"
"github.com/moby/moby/api/types/container"
"github.com/moby/moby/api/types/network"
+ "github.com/moby/moby/api/types/system"
"github.com/moby/moby/client"
"databasus-verification-agent/internal/features/restore"
@@ -64,19 +66,26 @@ func (e *dockerEngine) Ping(ctx context.Context) error {
return err
}
-func (e *dockerEngine) UserNSRemapEnabled(ctx context.Context) (bool, error) {
- info, err := e.cli.Info(ctx, client.InfoOptions{})
+func (e *dockerEngine) GetHostCapabilities(ctx context.Context) (HostCapabilities, error) {
+ result, err := e.cli.Info(ctx, client.InfoOptions{})
if err != nil {
- return false, err
+ return HostCapabilities{}, err
}
- for _, opt := range info.Info.SecurityOptions {
- if strings.Contains(opt, "name=userns") {
- return true, nil
- }
- }
+ return toHostCapabilities(result.Info), nil
+}
- return false, nil
+// toHostCapabilities requires both CFS flags because that is the daemon's own
+// condition for accepting NanoCPUs; older daemons track them separately.
+func toHostCapabilities(info system.Info) HostCapabilities {
+ isUserNSRemapEnabled := slices.ContainsFunc(info.SecurityOptions, func(opt string) bool {
+ return strings.Contains(opt, "name=userns")
+ })
+
+ return HostCapabilities{
+ IsUserNSRemapEnabled: isUserNSRemapEnabled,
+ IsCpuLimitSupported: info.CPUCfsPeriod && info.CPUCfsQuota,
+ }
}
func (e *dockerEngine) EnsureImage(ctx context.Context, ref string) error {
diff --git a/agent/verification/internal/features/container/dockerengine_test.go b/agent/verification/internal/features/container/dockerengine_test.go
new file mode 100644
index 00000000..7e2b5421
--- /dev/null
+++ b/agent/verification/internal/features/container/dockerengine_test.go
@@ -0,0 +1,65 @@
+package container
+
+import (
+ "testing"
+
+ "github.com/moby/moby/api/types/system"
+ "github.com/stretchr/testify/assert"
+)
+
+func Test_ToHostCapabilities_ReadsCpuLimitSupportFromBothCfsFlags(t *testing.T) {
+ testCases := []struct {
+ name string
+ cpuCfsPeriod bool
+ cpuCfsQuota bool
+ isCpuLimitSupportedOnHost bool
+ }{
+ {name: "both flags set", cpuCfsPeriod: true, cpuCfsQuota: true, isCpuLimitSupportedOnHost: true},
+ {name: "period missing", cpuCfsPeriod: false, cpuCfsQuota: true, isCpuLimitSupportedOnHost: false},
+ {name: "quota missing", cpuCfsPeriod: true, cpuCfsQuota: false, isCpuLimitSupportedOnHost: false},
+ {name: "both flags missing", cpuCfsPeriod: false, cpuCfsQuota: false, isCpuLimitSupportedOnHost: false},
+ }
+
+ for _, testCase := range testCases {
+ t.Run(testCase.name, func(t *testing.T) {
+ capabilities := toHostCapabilities(system.Info{
+ CPUCfsPeriod: testCase.cpuCfsPeriod,
+ CPUCfsQuota: testCase.cpuCfsQuota,
+ })
+
+ assert.Equal(t, testCase.isCpuLimitSupportedOnHost, capabilities.IsCpuLimitSupported)
+ })
+ }
+}
+
+func Test_ToHostCapabilities_ReadsUserNSRemapFromSecurityOptions(t *testing.T) {
+ testCases := []struct {
+ name string
+ securityOptions []string
+ isUserNSRemapEnabledOnHost bool
+ }{
+ {
+ name: "userns option present",
+ securityOptions: []string{"name=seccomp,profile=builtin", "name=userns"},
+ isUserNSRemapEnabledOnHost: true,
+ },
+ {
+ name: "userns option absent",
+ securityOptions: []string{"name=seccomp,profile=builtin"},
+ isUserNSRemapEnabledOnHost: false,
+ },
+ {
+ name: "no security options",
+ securityOptions: nil,
+ isUserNSRemapEnabledOnHost: false,
+ },
+ }
+
+ for _, testCase := range testCases {
+ t.Run(testCase.name, func(t *testing.T) {
+ capabilities := toHostCapabilities(system.Info{SecurityOptions: testCase.securityOptions})
+
+ assert.Equal(t, testCase.isUserNSRemapEnabledOnHost, capabilities.IsUserNSRemapEnabled)
+ })
+ }
+}
diff --git a/agent/verification/internal/features/container/hostcapabilities.go b/agent/verification/internal/features/container/hostcapabilities.go
new file mode 100644
index 00000000..167193f3
--- /dev/null
+++ b/agent/verification/internal/features/container/hostcapabilities.go
@@ -0,0 +1,8 @@
+package container
+
+// HostCapabilities is what the Docker daemon reports it can enforce, read once
+// at startup because the kernel under the daemon does not change at runtime.
+type HostCapabilities struct {
+ IsUserNSRemapEnabled bool
+ IsCpuLimitSupported bool
+}
diff --git a/agent/verification/internal/features/container/manager.go b/agent/verification/internal/features/container/manager.go
index 52f0225f..f8324f13 100644
--- a/agent/verification/internal/features/container/manager.go
+++ b/agent/verification/internal/features/container/manager.go
@@ -52,10 +52,11 @@ var restoreTunedPostgresCmd = []string{
}
type Manager struct {
- engine *dockerEngine
- agentID string
- engineImageRepo string
- log *slog.Logger
+ engine *dockerEngine
+ agentID string
+ engineImageRepo string
+ isCpuLimitSupported bool
+ log *slog.Logger
}
func NewManager(
@@ -65,10 +66,11 @@ func NewManager(
log *slog.Logger,
) *Manager {
return &Manager{
- engine: engine,
- agentID: agentID,
- engineImageRepo: engineImageRepo,
- log: log,
+ engine: engine,
+ agentID: agentID,
+ engineImageRepo: engineImageRepo,
+ isCpuLimitSupported: true,
+ log: log,
}
}
@@ -79,16 +81,28 @@ func (m *Manager) StartupSelfCheck(ctx context.Context) error {
m.log.Info("docker daemon is reachable")
- remapOn, err := m.engine.UserNSRemapEnabled(ctx)
+ capabilities, err := m.engine.GetHostCapabilities(ctx)
if err != nil {
- m.log.Warn("could not determine user-namespace remap state", "error", err)
- } else if !remapOn {
+ // The CPU limit stays on: dropping it on a transient failure would
+ // silently unlimit hosts that support it.
+ m.log.Warn("could not determine docker host capabilities", "error", err)
+ return nil
+ }
+
+ if !capabilities.IsUserNSRemapEnabled {
m.log.Warn(
"docker user-namespace remapping is OFF — the strongest control " +
"against a container escape is absent; enable userns-remap on the " +
"verification host")
}
+ m.isCpuLimitSupported = capabilities.IsCpuLimitSupported
+ if !m.isCpuLimitSupported {
+ m.log.Warn(
+ "docker host does not support CPU CFS quota — verification containers " +
+ "run without a CPU limit, so a restore can use every CPU core on the host")
+ }
+
return nil
}
@@ -194,7 +208,7 @@ func (m *Manager) buildSpec(plan spawnPlan) SpawnSpec {
Cmd: restoreTunedPostgresCmd,
Env: []string{"POSTGRES_PASSWORD=" + plan.password},
Labels: plan.labels,
- NanoCPUs: int64(plan.cpuPerJob) * 1_000_000_000,
+ NanoCPUs: m.getNanoCPUs(plan.cpuPerJob),
MemoryBytes: int64(plan.ramMbPerJob) * 1024 * 1024,
PidsLimit: containerPidsLimit,
NetworkID: plan.networkID,
@@ -212,6 +226,16 @@ func (m *Manager) buildSpec(plan spawnPlan) SpawnSpec {
}
}
+// getNanoCPUs returns 0 on hosts without CFS quota support, which Docker
+// treats as no CPU limit; any other value makes the daemon reject the container.
+func (m *Manager) getNanoCPUs(cpuPerJob int) int64 {
+ if !m.isCpuLimitSupported {
+ return 0
+ }
+
+ return int64(cpuPerJob) * 1_000_000_000
+}
+
func (m *Manager) assertSecurity(ctx context.Context, containerID string) error {
state, err := m.engine.InspectSecurity(ctx, containerID)
if err != nil {
diff --git a/agent/verification/internal/features/container/postgres_test.go b/agent/verification/internal/features/container/postgres_test.go
index ac7ea55e..64b6075f 100644
--- a/agent/verification/internal/features/container/postgres_test.go
+++ b/agent/verification/internal/features/container/postgres_test.go
@@ -13,16 +13,7 @@ func Test_BuildSpec_AppliesHardeningControls(t *testing.T) {
// nil engine: buildSpec is pure and never calls the engine.
containerManager := NewManager(nil, "agent-1", "databasus/verification-postgres", testutil.DiscardLogger())
- labels := map[string]string{LabelAgentID: "agent-1"}
- spec := containerManager.buildSpec(spawnPlan{
- verificationID: uuid.New(),
- image: "postgres@sha256:x",
- password: "pw",
- cpuPerJob: 2,
- ramMbPerJob: 1024,
- networkID: "net-id",
- labels: labels,
- })
+ spec := containerManager.buildSpec(newTestSpawnPlan())
assert.True(t, spec.NoNewPrivileges)
assert.True(t, spec.CapDropAll)
@@ -34,18 +25,24 @@ func Test_BuildSpec_AppliesHardeningControls(t *testing.T) {
assert.Equal(t, []string{"POSTGRES_PASSWORD=pw"}, spec.Env)
}
+func Test_BuildSpec_WhenCpuLimitUnsupported_OmitsCpuLimitAndKeepsOtherControls(t *testing.T) {
+ containerManager := NewManager(nil, "agent-1", "databasus/verification-postgres", testutil.DiscardLogger())
+ containerManager.isCpuLimitSupported = false
+
+ spec := containerManager.buildSpec(newTestSpawnPlan())
+
+ assert.Zero(t, spec.NanoCPUs, "Docker treats 0 as no CPU limit")
+ assert.Equal(t, int64(1024)*1024*1024, spec.MemoryBytes)
+ assert.EqualValues(t, containerPidsLimit, spec.PidsLimit)
+ assert.True(t, spec.NoNewPrivileges)
+ assert.True(t, spec.CapDropAll)
+ assert.Equal(t, minimalCaps, spec.CapAdd)
+}
+
func Test_BuildSpec_SetsRestoreTunedPostgresCmd(t *testing.T) {
containerManager := NewManager(nil, "agent-1", "databasus/verification-postgres", testutil.DiscardLogger())
- spec := containerManager.buildSpec(spawnPlan{
- verificationID: uuid.New(),
- image: "postgres@sha256:x",
- password: "pw",
- cpuPerJob: 2,
- ramMbPerJob: 1024,
- networkID: "net-id",
- labels: map[string]string{LabelAgentID: "agent-1"},
- })
+ spec := containerManager.buildSpec(newTestSpawnPlan())
assert.Equal(t, restoreTunedPostgresCmd, spec.Cmd)
assert.Equal(t, "postgres", spec.Cmd[0])
@@ -127,3 +124,15 @@ func Test_StockFallbackImage_WhenTimescaleJob_DoesNotFallBack(t *testing.T) {
assert.False(t, canFallBack,
"timescale needs its exact version-matched image; stock postgres cannot restore it")
}
+
+func newTestSpawnPlan() spawnPlan {
+ return spawnPlan{
+ verificationID: uuid.New(),
+ image: "postgres@sha256:x",
+ password: "pw",
+ cpuPerJob: 2,
+ ramMbPerJob: 1024,
+ networkID: "net-id",
+ labels: map[string]string{LabelAgentID: "agent-1"},
+ }
+}
diff --git a/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/.openspec.yaml b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/.openspec.yaml
new file mode 100644
index 00000000..53f62d70
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-10
diff --git a/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/design.md b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/design.md
new file mode 100644
index 00000000..a6b3e73e
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/design.md
@@ -0,0 +1,71 @@
+## Context
+
+See proposal.md for why. The relevant current state:
+
+- `Manager.buildSpec` always sets `NanoCPUs` to the per-job CPU budget (`agent/verification/internal/features/container/manager.go:197`), and `dockerEngine.CreateContainer` passes it to Docker unchanged (`agent/verification/internal/features/container/dockerengine.go:154-158`).
+- The per-job budget is at least 1 by validation (`agent/verification/internal/config/config.go:123`, `:136-144`). It also sizes `pg_restore` parallelism (`agent/verification/internal/features/runner/runner.go:272`), so it has to stay meaningful even when no CPU limit is applied.
+- The Docker daemon rejects any non-zero `NanoCPUs` when its `sysInfo.CPUCfs` is false (`github.com/docker/[email protected]/daemon/daemon_unix.go:495`). `docker info` reports the same value as both `CpuCfsPeriod` and `CpuCfsQuota` (`daemon/info_unix.go:40-41`). Older daemons tracked the two separately and rejected `NanoCPUs` unless both were true.
+- `Manager.StartupSelfCheck` (`manager.go:75`) already calls `docker info` once, through `dockerEngine.UserNSRemapEnabled` (`dockerengine.go:67`), to warn when user-namespace remapping is off. `start.go:76-79` calls it before the runner starts, so nothing spawns a container until the check has finished.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Decide once per agent process whether the daemon can enforce a CPU limit, and drop the limit only when it cannot.
+- Keep the decision testable without a Docker host that lacks CFS.
+
+**Non-Goals:**
+
+- Re-checking support during the process lifetime. The kernel under the daemon does not change while the agent runs.
+
+## Decisions
+
+### Detect support from the `docker info` CFS flags
+
+The agent treats the CPU limit as supported only when `docker info` reports both `CPUCfsPeriod` and `CPUCfsQuota` as true. This is the condition the daemon itself checks before rejecting `NanoCPUs`, in current and older daemon versions, so the agent and the daemon cannot disagree.
+
+Rejected alternatives:
+
+- **Retry container creation without `NanoCPUs` after this specific error.** The agent would have to match the daemon's error text, which can change between Docker versions, and every job on an affected host would fail once before succeeding.
+- **Read the cgroup filesystem from the agent process.** The agent can run in a container or talk to a remote daemon. What matters is the daemon's host, which only the daemon can report.
+- **A manual `--disable-cpu-limit` flag.** The user would learn about the problem only after verifications fail, and then has to find the flag. Detection fixes the affected hosts with no configuration.
+
+### Read host capabilities with one `docker info` call
+
+`dockerEngine.UserNSRemapEnabled` is replaced by one method that calls `docker info` once and returns both answers, user-namespace remapping and CPU limit support. The translation from the `docker info` response to those two booleans is a pure function, so a unit test covers it by feeding it info structs.
+
+Rejected alternative: a second engine method with its own `docker info` call. It leaves `UserNSRemapEnabled` untouched, but sends a duplicate request to the daemon at every startup and spreads host inspection across two methods.
+
+### Keep the CPU limit when support cannot be determined
+
+If `docker info` fails, the agent logs the existing warning and keeps applying the CPU limit. On a host that does support the limit, this preserves today's behavior. On a host that does not, container creation fails with the daemon's own error, which is what happens today.
+
+Rejected alternative: drop the limit whenever support is unknown. A transient `docker info` failure would then silently remove the CPU limit on hosts that support it.
+
+### Store the answer on the Manager
+
+The Manager holds whether the CPU limit is supported. `NewManager` sets it to true, `StartupSelfCheck` sets it from `docker info`, and `buildSpec` sets `NanoCPUs` to 0 when it is false. To Docker, 0 means no CPU limit. `SpawnSpec`, the runner and the config stay as they are.
+
+Rejected alternatives:
+
+- **Carry the flag in the agent's capacity or config.** Config is built before Docker is contacted and describes what the operator configured, not what the host supports.
+- **Ask the daemon on every spawn.** That repeats a request whose answer does not change while the agent runs.
+
+### Announce the missing limit in the startup log only
+
+When the limit is unsupported, `StartupSelfCheck` logs one warning saying that restore containers run without a CPU limit and can use every core on the host. That follows the existing user-namespace warning and `agent/verification/AGENTS.md` (Logging, Warn level: degraded but recoverable). The heartbeat and the backend are not changed. See proposal.md, Out of scope.
+
+## Module rules
+
+- `agent/verification/AGENTS.md`: Docker SDK calls stay confined to `dockerengine.go`, test names follow `Test_WhatWeDo_WhichConditions_WhatWeExpect`, and tests sit next to the code (`postgres_test.go` holds the `buildSpec` tests). Logs follow the Logging rules.
+- `AGENTS.md`: names state intent, so booleans take an `is` prefix. There is no backward-compatibility shim, so `UserNSRemapEnabled` is deleted rather than kept beside the new method.
+
+## Risks / Trade-offs
+
+- [A restore on an unsupported host can use every CPU core, starving other services on a NAS] → The startup warning makes this visible. The memory limit, the process limit and the privilege controls still apply. A relative-priority fallback is out of scope.
+- [No CI host lacks CFS, so the real Docker path is not exercised automatically] → Unit tests cover the `docker info` translation and `buildSpec`. Confirmation on an affected host has to come from the issue reporter.
+- [A daemon could report CFS support it does not have] → Container creation then fails with the daemon's error, the same as today. No new failure mode is introduced.
+
+## Migration Plan
+
+None. The agent decides at startup with no configuration, and reverting the change restores the current behavior.
diff --git a/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/proposal.md b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/proposal.md
new file mode 100644
index 00000000..014c4776
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/proposal.md
@@ -0,0 +1,36 @@
+## Why
+
+Restore verification cannot run on hosts whose kernel lacks the CPU CFS quota controller, such as older Synology NAS models and fnOS. On every job the agent asks Docker for a CPU limit, and the Docker daemon on those hosts rejects the container outright, so every verification fails before the restore starts. No flag avoids this, because `--max-cpu` must be at least 1.
+
+## What Changes
+
+- At startup the agent asks the Docker daemon whether it can enforce a CPU limit. The answer comes from the same `docker info` call the agent already makes to check user-namespace remapping.
+- If the daemon cannot enforce a CPU limit, the agent creates verification containers without one and logs a warning at startup. The warning says that a restore can then use every CPU core on the host.
+- If the daemon can enforce it, or if the agent cannot find out, containers keep the current per-job CPU limit.
+- `--max-cpu`, the per-job CPU budget, and the `pg_restore` parallelism derived from it are unchanged. The memory limit, the process limit and the other container hardening controls are unchanged.
+
+Nothing breaks. No flag, config field or API changes.
+
+## Capabilities
+
+### New Capabilities
+
+- `verification-container-resources`: the resource limits the verification agent applies to each restore container, and how the agent adapts them to what the Docker host supports.
+
+### Modified Capabilities
+
+None. `backup-verification` covers how verification runs are scheduled, not how the agent runs the restore container.
+
+## Impact
+
+- Code: `agent/verification` only. The Docker engine wrapper and the container manager in `internal/features/container`.
+- Rules this change answers to: `AGENTS.md` and `agent/verification/AGENTS.md`.
+- Backend, frontend, the agent-to-backend API and the heartbeat payload are untouched.
+
+## Out of scope
+
+- A manual flag to turn the CPU limit off on hosts that support it.
+- Reporting to the backend or showing in the UI that an agent runs without a CPU limit.
+- Using CPU shares or another relative-priority mechanism as a replacement when the hard limit is unavailable.
+- Detecting other unsupported limits, such as memory or process limits.
+- Changing how `--max-cpu` is validated or how the per-job CPU budget is computed.
diff --git a/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/specs/verification-container-resources/spec.md b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/specs/verification-container-resources/spec.md
new file mode 100644
index 00000000..8f8b9a37
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/specs/verification-container-resources/spec.md
@@ -0,0 +1,50 @@
+## Purpose
+
+Defines the resource limits the verification agent applies to each container that restores a backup, and how the agent adapts those limits to what the Docker host can enforce.
+
+## ADDED Requirements
+
+### Requirement: Restore containers are CPU-limited when the host supports it
+
+The verification agent SHALL limit each restore container to the per-job CPU budget derived from the configured CPU total and the configured number of concurrent jobs, unless the Docker host reports that it cannot enforce a CPU limit.
+
+#### Scenario: Host supports CPU limits
+
+- **WHEN** the Docker host reports at agent startup that it can enforce a CPU limit
+- **AND** the agent runs with a CPU total of 4 and 2 concurrent jobs
+- **THEN** each restore container is limited to 2 CPU cores
+
+#### Scenario: Host support cannot be determined
+
+- **WHEN** the agent cannot read the Docker host's CPU limit support at startup
+- **THEN** the agent limits each restore container to the per-job CPU budget, as on a host that supports the limit
+
+### Requirement: Verification runs on hosts that cannot enforce a CPU limit
+
+The verification agent SHALL create restore containers without a CPU limit when the Docker host reports at agent startup that it cannot enforce one. Verification on such a host SHALL proceed instead of failing at container creation.
+
+#### Scenario: Host lacks CPU limit support
+
+- **WHEN** the Docker host reports at agent startup that it cannot enforce a CPU limit
+- **AND** the agent claims a verification job
+- **THEN** the agent creates the restore container without a CPU limit
+- **AND** the restore and verification proceed to their normal terminal status
+
+#### Scenario: CPU budget still sizes the restore
+
+- **WHEN** the Docker host cannot enforce a CPU limit
+- **THEN** the agent still accepts its configured CPU total, reports it to the server, and uses the per-job CPU budget to size restore parallelism
+
+### Requirement: A missing CPU limit is announced and leaves other isolation intact
+
+A restore runs code taken from the backup with database superuser rights, so a restore container without a CPU limit can use every CPU core on the host. The verification agent SHALL log a warning at startup when it will run restore containers without a CPU limit, and SHALL keep every other container isolation control in force.
+
+#### Scenario: Startup warning on an unsupported host
+
+- **WHEN** the Docker host reports at agent startup that it cannot enforce a CPU limit
+- **THEN** the agent logs a warning that restore containers will run without a CPU limit and can use every CPU core on the host
+
+#### Scenario: Other limits remain applied
+
+- **WHEN** the agent creates a restore container without a CPU limit
+- **THEN** the container still has the per-job memory limit, the process count limit, all capabilities dropped except the minimal set, and privilege escalation disabled
diff --git a/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/tasks.md b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/tasks.md
new file mode 100644
index 00000000..24878b2c
--- /dev/null
+++ b/openspec/changes/archive/2026-10-10-skip-unsupported-cpu-limit/tasks.md
@@ -0,0 +1,14 @@
+## 1. Read host capabilities from one `docker info` call
+
+- [x] 1.1 In `agent/verification/internal/features/container`, add a pure function that translates a `docker info` response into host capabilities: whether user-namespace remapping is on, and whether the CPU limit is supported (`CPUCfsPeriod` and `CPUCfsQuota` both true). Verify with table-driven unit tests covering both CFS flags true, each one false, and the userns security option present or absent. Run them with `go test -race -count=1 -run Test_ToHostCapabilities ./internal/features/container/` in `agent/verification`.
+- [x] 1.2 Replace `dockerEngine.UserNSRemapEnabled` with one engine method that calls `docker info` once and returns those capabilities through the function from 1.1. Delete `UserNSRemapEnabled`. Verify that `grep -rnw UserNSRemapEnabled agent/verification` finds nothing and `make build` in `agent/verification` succeeds.
+
+## 2. Apply the CPU limit only when supported
+
+- [x] 2.1 Give `Manager` a boolean for CPU limit support, set to true in `NewManager`, and make `buildSpec` set `NanoCPUs` to 0 when it is false. Verify with a `buildSpec` test in `postgres_test.go` that asserts `NanoCPUs` is 0 while the memory limit, the process limit, the dropped capabilities, the minimal capability set and no-new-privileges are unchanged. Keep the existing test asserting the per-job `NanoCPUs` when support is true. Run them with `go test -race -count=1 -run Test_BuildSpec ./internal/features/container/` in `agent/verification`.
+- [x] 2.2 Update `StartupSelfCheck` to use the method from 1.2. Keep the user-namespace warning. Store CPU limit support on the Manager. When support is false, log one warning that restore containers run without a CPU limit and can use every CPU core on the host. When `docker info` fails, keep the existing warning and leave the CPU limit on. Verify that `make build` in `agent/verification` succeeds and that reading `StartupSelfCheck` shows each of the three outcomes.
+
+## 3. Lint and review
+
+- [x] 3.1 Run `make lint` in `agent/verification` and fix every finding until it passes.
+- [x] 3.2 Run the mandatory post-implementation review from `AGENTS.md` on the diff and these artifacts, and resolve every `CHANGES REQUIRED` finding.
diff --git a/openspec/specs/verification-container-resources/spec.md b/openspec/specs/verification-container-resources/spec.md
new file mode 100644
index 00000000..066cc9e6
--- /dev/null
+++ b/openspec/specs/verification-container-resources/spec.md
@@ -0,0 +1,51 @@
+# verification-container-resources Specification
+
+## Purpose
+Defines the resource limits the verification agent applies to each container that restores a backup, and how the agent adapts those limits to what the Docker host can enforce.
+
+## Requirements
+
+### Requirement: Restore containers are CPU-limited when the host supports it
+
+The verification agent SHALL limit each restore container to the per-job CPU budget derived from the configured CPU total and the configured number of concurrent jobs, unless the Docker host reports that it cannot enforce a CPU limit.
+
+#### Scenario: Host supports CPU limits
+
+- **WHEN** the Docker host reports at agent startup that it can enforce a CPU limit
+- **AND** the agent runs with a CPU total of 4 and 2 concurrent jobs
+- **THEN** each restore container is limited to 2 CPU cores
+
+#### Scenario: Host support cannot be determined
+
+- **WHEN** the agent cannot read the Docker host's CPU limit support at startup
+- **THEN** the agent limits each restore container to the per-job CPU budget, as on a host that supports the limit
+
+### Requirement: Verification runs on hosts that cannot enforce a CPU limit
+
+The verification agent SHALL create restore containers without a CPU limit when the Docker host reports at agent startup that it cannot enforce one. Verification on such a host SHALL proceed instead of failing at container creation.
+
+#### Scenario: Host lacks CPU limit support
+
+- **WHEN** the Docker host reports at agent startup that it cannot enforce a CPU limit
+- **AND** the agent claims a verification job
+- **THEN** the agent creates the restore container without a CPU limit
+- **AND** the restore and verification proceed to their normal terminal status
+
+#### Scenario: CPU budget still sizes the restore
+
+- **WHEN** the Docker host cannot enforce a CPU limit
+- **THEN** the agent still accepts its configured CPU total, reports it to the server, and uses the per-job CPU budget to size restore parallelism
+
+### Requirement: A missing CPU limit is announced and leaves other isolation intact
+
+A restore runs code taken from the backup with database superuser rights, so a restore container without a CPU limit can use every CPU core on the host. The verification agent SHALL log a warning at startup when it will run restore containers without a CPU limit, and SHALL keep every other container isolation control in force.
+
+#### Scenario: Startup warning on an unsupported host
+
+- **WHEN** the Docker host reports at agent startup that it cannot enforce a CPU limit
+- **THEN** the agent logs a warning that restore containers will run without a CPU limit and can use every CPU core on the host
+
+#### Scenario: Other limits remain applied
+
+- **WHEN** the agent creates a restore container without a CPU limit
+- **THEN** the container still has the per-job memory limit, the process count limit, all capabilities dropped except the minimal set, and privilege escalation disabled