Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
164 lines (117 loc) · 3.36 KB

GETTING_STARTED.md

File metadata and controls

164 lines (117 loc) · 3.36 KB

Getting Started with Guardian Agent

This guide will help you get Guardian Agent up and running in 5 minutes.

Prerequisites

Quick Start

1. Clone and Build

# Clone the repository
git clone https://github.com/yourusername/GuardianAgent.git
cd GuardianAgent

# Build (takes ~1 minute first time)
cargo build --release --features server

# Binary is ready: target/release/guardian (or .exe on Windows)

2. Create Configuration

Create a guardian.yaml file:

# Policy rules
policies:
  - "allow file writes to /tmp"
  - "deny file writes to /etc"

# Log configuration
log_path: "./guardian.log.jsonl"

3. Run Guardian Agent

# Run the server
./target/release/guardian

# Or with configuration
GUARDIAN_CONFIG=guardian.yaml PORT=8080 ./target/release/guardian

4. Test It

# Health check
curl http://localhost:8080/health

# Validate an action
curl -X POST http://localhost:8080/validate \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "file_write",
      "resource": "/tmp/test.txt"
    },
    "context": {
      "user_id": "test_user"
    }
  }'

Docker Quick Start

# Build Docker image
docker build -f Dockerfile.distroless -t guardian-agent:latest .

# Run container
docker run -p 8080:8080 \
  -v $(pwd)/guardian.yaml:/app/guardian.yaml:ro \
  -v guardian-logs:/var/lib/guardian \
  guardian-agent:latest

Kubernetes Quick Start

Using Helm

# Install with Helm
helm install guardian-agent ./helm/guardian-agent

# Check status
kubectl get pods -l app.kubernetes.io/name=guardian-agent

# Port forward to test
kubectl port-forward svc/guardian-agent 8080:8080

Using kubectl

# Apply Kubernetes manifests
kubectl apply -f examples/kubernetes-sidecar.yaml

# Check status
kubectl get pods -n guardian-agent

Next Steps

Troubleshooting

Server Won't Start

# Check if port is in use
netstat -an | grep 8080  # Linux/macOS
netstat -an | findstr 8080  # Windows

# Check logs
RUST_LOG=debug ./target/release/guardian

OPA Not Found

Guardian Agent works without OPA, but policies won't be evaluated. To use OPA:

# Install OPA
# See: https://www.openpolicyagent.org/docs/latest/#running-opa

# Or use OPA server mode
# In guardian.yaml:
opa_url: "http://localhost:8181"

Permission Denied

# Make binary executable (Linux/macOS)
chmod +x target/release/guardian

# Or run with appropriate permissions
sudo ./target/release/guardian

Examples

See the examples/ directory for:

  • Docker Compose setups
  • Kubernetes sidecar deployments
  • Systemd service files
  • MCP monitoring configurations

Need Help?