Mastering Docker AI Governance: A Step-by-Step Guide to Safe Agent Autonomy

By • min read

Overview

The rise of AI agents has transformed how developers work—agents now read entire codebases, refactor across services, and ship products end-to-end. But with great power comes great exposure. Agents running on laptops with developer credentials can access private repos, production APIs, and the open internet, creating a blind spot for enterprise security. Docker AI Governance provides centralized control over agent execution: what they can reach on the network, which credentials they can use, and which MCP tools they can call. This guide walks you through setting up, customizing, and auditing governance policies so every developer in your company can run agents safely.

Mastering Docker AI Governance: A Step-by-Step Guide to Safe Agent Autonomy — Source: www.docker.com

Prerequisites

Docker Desktop (version 4.30 or later) installed on your development machine
Administrator access to enable Docker AI Governance features
Basic familiarity with Docker CLI and YAML syntax
A sample AI agent (e.g., a Python-based agent using the OpenAI SDK) to test governance
Understanding of MCP (Model Context Protocol)—tools your agent calls externally

Step-by-Step Instructions

1. Install the Docker AI Governance Extension

Docker AI Governance is available as a Desktop extension. Open Docker Desktop, go to the Extensions marketplace, and search for “AI Governance”. Click Install. Once installed, you’ll see a new “Governance” tab in the sidebar.

# Alternatively, install via CLI:
docker extension install docker/ai-governance

2. Define a Governance Policy

Create a YAML file (e.g., governance-policy.yaml) that specifies the rules for your agent. Below is a minimal example that restricts network access, credential usage, and MCP tool calls.

# governance-policy.yaml
apiVersion: ai.docker.com/v1
kind: GovernancePolicy
metadata:
  name: agent-policy-001
spec:
  network:
    allowedDomains:
      - "*.github.com"
      - "api.openai.com"
    denyLocalNetwork: true
  credentials:
    allowedKeys:
      - "GITHUB_TOKEN"
      - "OPENAI_API_KEY"
    maxExpirationHours: 24
  mcp:
    allowedTools:
      - "read_file"
      - "write_file"
      - "git_push"
    deniedTools:
      - "delete_production_db"
      - "send_email"
  audit:
    enabled: true
    logLevel: info

This policy ensures the agent can only reach GitHub and OpenAI, only use GitHub and OpenAI keys (expiring in 24 hours), and only call safe MCP tools. Adjust to your environment.

3. Attach the Policy to an Agent Container

When running your agent container, add the --governance-policy flag with the path to your YAML file.

docker run --rm \
  --governance-policy ./governance-policy.yaml \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  my-agent-image

If you’re using Docker Compose, include the governance policy under the x-docker-ai-governance extension field:

# docker-compose.yml
version: '3.8'
services:
  agent:
    image: my-agent-image
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    x-docker-ai-governance:
      policy: ./governance-policy.yaml

4. Run the Agent and Verify Governance

Start the container. Docker will enforce the policy in real time. Open the Docker Desktop Governance tab to see live logs and violations.

Source: www.docker.com

Test allowed actions: Have the agent read a local file and push to GitHub. It should succeed.
Test denied actions: Try to call a denied MCP tool (e.g., send_email). The agent will receive a PolicyViolation error and the action will be blocked.
Test network restriction: Attempt to reach a domain not in allowedDomains. The connection will be dropped.

Example output from agent logs:

[2025-03-25 10:00:01] INFO: Agent requested MCP tool 'read_file' – allowed
[2025-03-25 10:00:05] INFO: Agent requested MCP tool 'send_email' – BLOCKED (PolicyViolation)

5. Audit Governance Events

Docker AI Governance logs all policy decisions. Access the audit trail via:

docker governance logs --policy agent-policy-001 --since 24h

Or view the integrated dashboard in Docker Desktop. Use these logs to refine your policy based on actual agent behavior.

Common Mistakes

Overly permissive policies: Allowing allowedDomains: ["*"] or deniedTools: [] defeats the purpose. Start restrictive and expand as needed.
Not setting credential expiration: Without maxExpirationHours, keys remain valid indefinitely. Always set a short expiration (e.g., 8–24 hours).
Forgetting to update policies: As agents evolve, revisit your policy. A policy that allowed git_push originally might need to disallow it after a code freeze.
Ignoring audit logs: Many teams set up governance but never review violations. Schedule weekly audits to catch anomalies.
Running agents without a policy: It’s easy to forget the --governance-policy flag. Make it a default in your CI/CD scripts.

Summary

Docker AI Governance gives you centralized control over agent execution, network access, credential usage, and MCP tool calls. By defining a clear policy in YAML, attaching it to your agent containers, and monitoring audit logs, you can safely unlock the productivity gains of AI agents—whether they’re running on a laptop or in production. Remember to start restrictive, set credential expirations, and review audit logs regularly. With these steps, your organization can embrace agent autonomy without compromising security.