# Getting Started

Deploy your first governed AI agent with Mandrel.

Source: https://mandrel-web-363efb.gitlab.io/docs/guides/getting-started/

---


Governing an agent with Mandrel takes four steps: author a Mandrel Spec, validate it with the CLI, run the agent behind a Collet sidecar locally, then deploy the same spec to Kubernetes. This guide works through all four.

## Prerequisites

- [Mandrel CLI](https://mandrel-web-363efb.gitlab.io/docs/reference/cli.md) installed:
  ```bash
  go install gitlab.com/the-mandrel-project/mandrel-cli/cmd/mandrel-cli@latest
  ```
- Container engine: Podman (recommended) or Docker, with Compose support.
- 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`:

```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: "urn:ietf:params:oauth:poi:tier:session-pop"
  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:

```bash
mandrel-cli validate agent-spec.yaml
```

## 3. Local Deployment (Podman / Docker Compose)

The Mandrel architecture uses a **Sidecar Pattern**. The [Mandrel Collet](https://mandrel-web-363efb.gitlab.io/docs/reference/collet.md) intercepts all traffic to your agent to enforce the spec.

Create a `docker-compose.yml` (or `compose.yaml`):

```yaml
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 locally:

```bash
# Using Podman
podman compose up

# Or using Docker
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:

```yaml
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

- Explore the [Core Schema](https://mandrel-web-363efb.gitlab.io/docs/spec/core-schema.md) to define advanced governance rules.
- Learn about [Compound Identity](https://mandrel-web-363efb.gitlab.io/docs/spec/identity.md) to secure your Agent-to-Agent communication.