Getting Started

Deploy your first governed AI agent with Mandrel.

This guide will walk you through creating, validating, and deploying a Mandrel-governed agent.

Prerequisites

  • Mandrel CLI installed:
    go install gitlab.com/the-mandrel-project/mandrel-cli/cmd/mandrel-cli@latest
  • Docker and Docker Compose.
  • A Kubernetes cluster (optional, for Tier 2+ deployment).

1. Create a Mandrel Spec

Every agent in the Mandrel mesh requires a declarative contract. Create a file named agent-spec.yaml:

apiVersion: mandrelproject.ai/v1
kind: MandrelSpec
metadata:
  name: my-specialist-agent
  namespace: default
spec:
  governance:
    risk-profile: "safety-first"
    enforcement-matrices:
      - type: "threshold"
        attribute: "transaction.value"
        tiers:
          - limit: 100.00
            action: "challenge"
            required-acr: "L1"
  runtime:
    max-hops-allowed: 2
    timeout-seconds: 30

2. Validate the Spec

Use the mandrel-cli to ensure your spec is syntactically and semantically correct:

mandrel-cli validate agent-spec.yaml

3. Local Deployment (Docker Compose)

The Mandrel architecture uses a Sidecar Pattern. The Mandrel Collet intercepts all traffic to your agent to enforce the spec.

Create a docker-compose.yml:

services:
  # The Specialist Agent (Your Application)
  agent:
    image: my-company/specialist-agent:latest
    ports:
      - "50051" # Internal gRPC port

  # The Mandrel Collet (Enforcement Sidecar)
  collet:
    image: gitlab.com/the-mandrel-project/mandrel-collet:v1
    volumes:
      - ./agent-spec.yaml:/etc/mandrel/agent-spec.yaml
    ports:
      - "50052:50052" # Public entry point for the agent
    command: 
      - "--spec"
      - "/etc/mandrel/agent-spec.yaml"
      - "--port"
      - "50052"
      - "--target"
      - "agent:50051"
    depends_on:
      - agent

Run the stack:

docker-compose up

4. Production Deployment (Kubernetes)

In Kubernetes, the Collet and Agent run in the same Pod. The mandrel-cli generate command can help produce these manifests, but here is a manual example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: specialist-agent
spec:
  replicas: 1
  template:
    spec:
      containers:
      # The Application Container
      - name: agent
        image: my-company/specialist-agent:latest
        ports:
        - containerPort: 50051

      # The Mandrel Collet Sidecar
      - name: collet
        image: gitlab.com/the-mandrel-project/mandrel-collet:v1
        ports:
        - containerPort: 50052
        args:
        - "--spec"
        - "/etc/mandrel/agent-spec.yaml"
        - "--port"
        - "50052"
        - "--target"
        - "localhost:50051"
        volumeMounts:
        - name: spec-volume
          mountPath: /etc/mandrel
      volumes:
      - name: spec-volume
        configMap:
          name: agent-spec-config

Next Steps