Epistemic Kernel - Customer Onboarding Guide

2026-08-03

Epistemic Kernel — Customer Onboarding Guide

Your step-by-step journey from sign-up to production

🎉 Welcome to Epistemic Kernel!

Thank you for choosing the Epistemic Kernel to bring trust-aware computing to your multi-agent systems. This guide will walk you through everything you need to get up and running successfully.

Estimated time to production: 1-2 hours (Developer/Professional) | 2-4 weeks (Enterprise)

🗺️ Onboarding Overview

Phase 1: Getting Started (0-30 minutes)

Welcome email received
Account setup complete
License activation verified
First agent deployed

Phase 2: Initial Configuration (30-60 minutes)

Broker configured for your environment
Attestors set up (filesystem, HTTP, database)
Agents integrated with your LLMs
Provenance testing verified

Phase 3: Production Readiness (60-120 minutes)

Rate limiting configured
Persistence tested
Monitoring in place
Backup procedure established

Phase 4: Go-Live (Enterprise: 2-4 weeks)

Custom features deployed (Enterprise)
Team training completed (Enterprise)
SLA verification (Enterprise)
Production deployment

🚀 Phase 1: Getting Started

Step 1: Complete Your Account Setup

After signing up, you should have received a welcome email with:

Your license key
Account portal link
Getting started resources

If you didn’t receive it:

Check your spam folder
Contact [email protected]
Verify the email address used for sign-up

Step 2: Log In to Customer Portal

Visit: https://portal.badlucksbane.com

First login:

Use the “Forgot password” link if you need to set a password
Accept the Terms of Service
Set up 2FA (recommended for security)

Portal features to explore:

Dashboard (subscription overview)
License keys (manage and regenerate)
Downloads (access your software)
Documentation (quick links)
Support (create tickets)

Step 3: Download the Software

For all tiers:

# Clone the open source repository (base for all tiers)
git clone http://localhost:3000/benbrown/epistemic-kernel.git
cd epistemic-kernel

For paid tiers:

Visit Downloads in the portal
Download the version matching your tier:
- Developer: epistemic-kernel-developer-v1.0.0.tar.gz
- Professional: epistemic-kernel-professional-v1.0.0.tar.gz
Extract the archive

Contents:

epistemic-kernel/
├── bin/
│   ├── ek-broker          # Broker daemon
│   └── ek-demo            # Demo agents
├── lib/
│   ├── ek-provenance.so    # Rust crate
│   ├── ek-sdk.so          # Client SDK
│   └── ek-attestors.so     # Attestor implementations
├── config/
│   ├── ek-broker.toml      # Configuration template
│   └── agents/            # Agent configs
├── docs/
│   └── integration.md      # Integration guide
├── examples/
│   └── rust/              # Rust examples
└── LICENSE                # Tier-specific license

Step 4: Activate Your License

Method 1: Environment Variable (Recommended)

export EK_LICENSE_KEY="your-license-key-here"
./bin/ek-broker

Method 2: Configuration File Edit config/ek-broker.toml:

[license]
key = "your-license-key-here"

Method 3: Command Line

./bin/ek-broker --license-key your-license-key-here

Verify activation:

./bin/ek-broker --version
# Output: epistemic-kernel v1.0.0 (Developer/Professional/Enterprise)
# License: ACTIVE (expires: 2027-08-08)

Step 5: Run the Demo

Start the broker:

./bin/ek-broker --config config/ek-broker.toml

In a new terminal, run the demo:

./bin/ek-demo

Expected output:

[ek-demo] Starting demo with 3 agents...
[ek-demo] Agent Alice: Attesting file /tmp/test.txt...
[ek-demo] Agent Bob: Creating belief based on Alice's attestation...
[ek-demo] Agent Charlie: Forwarding Bob's belief...
[ek-demo] ✅ All tests passed!
[ek-demo] Broker successfully rejected forged attestation
[ek-demo] ✅ Belief chains properly nested
[ek-demo] ✅ Expired beliefs forced re-derivation
[ek-demo] ✅ Audit trail complete

Success! Your Epistemic Kernel is working correctly.

⚙️ Phase 2: Initial Configuration

Step 6: Configure the Broker

Edit config/ek-broker.toml:

Basic configuration:

[broker]
# Socket path (Unix domain socket)
socket_path = "/tmp/ek.socket"

# HTTP API endpoint (Developer+)
http_address = "127.0.0.1:8080"

# Belief store configuration
[storage]
type = "persistent"  # "memory" for Open Source, "persistent" for paid
path = "/var/lib/epistemic-kernel/beliefs.db"

# Logging
[logging]
level = "info"  # debug, info, warn, error
file = "/var/log/ek-broker.log"

Developer+ features:

[features]
# Enable multi-process agent support
multi_process = true

# Enable rate limiting
rate_limit = true
max_requests_per_minute = 1000

# Enable HTTP attestor
[attestors.http]
enabled = true

Professional+ features:

[features]
# Enable distributed mode
distributed = true
node_id = "node-1"
peer_addresses = ["10.0.0.2:8081", "10.0.0.3:8081"]

# Database attestor (PostgreSQL)
[attestors.postgres]
enabled = true
connection_string = "postgresql://user:pass@localhost/db"

Step 7: Set Up Attestors

Filesystem Attestor (All tiers):

[attestors.filesystem]
enabled = true
# Allow reading from these directories
allowed_paths = ["/data", "/tmp"]
# Block these directories
blocked_paths = ["/etc", "/root"]

HTTP Attestor (Developer+):

[attestors.http]
enabled = true
# Timeout for HTTP requests
timeout_seconds = 10
# User agent string
user_agent = "EpistemicKernel/1.0"
# Allowed domains (optional)
allowed_domains = ["api.example.com", "trusted-source.org"]

Database Attestor (Professional+):

[attestors.postgres]
enabled = true
connection_string = "postgresql://user:pass@localhost:5432/mydb"
# Table to query for attestation
attestation_table = "facts"
# Column containing the fact data
fact_column = "content"
# Column containing the fact identifier
id_column = "id"

Step 8: Create Your First Agent

Python example (using socket protocol):

import socket
import json
import uuid

class EpistemicAgent:
    def __init__(self, socket_path="/tmp/ek.socket"):
        self.socket_path = socket_path
        
    def attest_file(self, file_path):
        """Attest a file's content through the broker"""
        request = {
            "request_id": str(uuid.uuid4()),
            "type": "attest",
            "attestor": "filesystem",
            "path": file_path,
            "options": {}
        }
        response = self._send_request(request)
        return response["provenance"]
    
    def create_belief(self, base_provenance, inference):
        """Create a belief based on existing provenance"""
        request = {
            "request_id": str(uuid.uuid4()),
            "type": "infer",
            "base_provenance": base_provenance,
            "inference": inference,
            "ttl_seconds": 3600  # 1 hour
        }
        response = self._send_request(request)
        return response["provenance"]
    
    def read_attested(self, provenance):
        """Read the value from an attested provenance"""
        request = {
            "request_id": str(uuid.uuid4()),
            "type": "read",
            "provenance": provenance
        }
        response = self._send_request(request)
        return response["value"]
    
    def _send_request(self, request):
        """Send request to broker via Unix socket"""
        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
            s.connect(self.socket_path)
            s.sendall(json.dumps(request).encode())
            response = s.recv(4096)
        return json.loads(response)

# Usage example
agent = EpistemicAgent()

# Attest a file
file_prov = agent.attest_file("/data/important.txt")
print(f"Attested: {file_prov}")

# Create a belief based on it
content = agent.read_attested(file_prov)
summary_prov = agent.create_belief(file_prov, f"Summary: {content[:100]}")
print(f"Belief: {summary_prov}")

Rust example (using SDK):

use ek_sdk::Client;
use ek_provenance::{Provenance, Tagged};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to broker
    let client = Client::connect("/tmp/ek.socket").await?;
    
    // Attest a file
    let file_prov = client.attest_filesystem("/data/important.txt").await?;
    println!("Attested: {:?}", file_prov);
    
    // Read the attested content
    let content: Tagged<String, Attested> = client.read_attested(&file_prov).await?;
    println!("Content: {}", *content);
    
    // Create a belief
    let belief = client.infer_from(&content, |text| {
        format!("Summary: {}", &text[..100.min(text.len())])
    }).await?;
    println!("Belief provenance: {:?}", belief.provenance());
    
    Ok(())
}

Step 9: Configure Rate Limiting

Per-agent limits:

[rate_limiting]
enabled = true

# Global limits
max_requests_per_second = 1000
max_requests_per_minute = 60000

# Per-agent limits
[rate_limiting.per_agent]
max_requests_per_second = 100
max_requests_per_minute = 6000

Tenant-level limits (Professional+):

[rate_limiting.tenants]
"tenant-a" = { max_rps = 200, max_rpm = 12000 }
"tenant-b" = { max_rps = 500, max_rpm = 30000 }

🏭 Phase 3: Production Readiness

Step 10: Set Up Monitoring

Prometheus metrics (Developer+):

Enable in configuration:

[metrics]
enabled = true
address = "127.0.0.1:9090"

Key metrics exposed:

# HELP ek_broker_requests_total Total requests processed
eType ek_broker_requests_total counter

# HELP ek_broker_errors_total Total errors
eType ek_broker_errors_total counter

# HELP ek_broker_latency_seconds Request latency
eType ek_broker_latency_seconds histogram

# HELP ek_belief_store_size_bytes Belief store size
eType ek_belief_store_size_bytes gauge

# HELP ek_active_agents Active connected agents
eType ek_active_agents gauge

Grafana dashboard: Import our pre-built dashboard (JSON available in monitoring/grafana-dashboard.json)

Step 11: Configure Alerts

Critical alerts:

# Prometheus alert rules
groups:
- name: epistemic-kernel
  rules:
  - alert: HighErrorRate
    expr: rate(ek_broker_errors_total[5m]) / rate(ek_broker_requests_total[5m]) > 0.05
    for: 5m
    labels:
      severity: critical
    annotations:
      summary: "High error rate ({{ $value }}%)"
  
  - alert: BrokerDown
    expr: up{job="ek-broker"} == 0
    for: 1m
    labels:
      severity: critical
    annotations:
      summary: "Broker daemon is down"
  
  - alert: HighLatency
    expr: histogram_quantile(0.95, sum(rate(ek_broker_latency_seconds_bucket[5m])) by (le)) > 0.1
    for: 5m
    labels:
      severity: warning
    annotations:
      summary: "High latency ({{ $value }}s)"

Step 12: Set Up Backups

Database backup (Developer+):

#!/bin/bash
# Daily backup script
BACKUP_DIR="/backups/ek-broker"
DATE=$(date +%Y-%m-%d)

# Backup belief store
sqlite3 /var/lib/epistemic-kernel/beliefs.db ".backup /backups/ek-broker/beliefs-$DATE.db"

# Backup configuration
cp -r /etc/epistemic-kernel/* "$BACKUP_DIR/config-$DATE/"

# Compress backups
find $BACKUP_DIR -name "beliefs-*.db" -mtime +30 -delete
find $BACKUP_DIR -name "config-*" -type d -mtime +30 -exec rm -rf {} \;

Distributed backup (Professional+):

Regular snapshots of broker state
Cross-node replication
Offsite backup support

Step 13: Security Hardening

Run as unprivileged user:

# Create dedicated user
sudo useradd -r -s /bin/false ek-broker

# Set permissions
sudo chown -R ek-broker:ek-broker /opt/epistemic-kernel
sudo chown ek-broker:ek-broker /tmp/ek.socket
sudo chown ek-broker:ek-broker /var/lib/epistemic-kernel

# Create systemd service
cat > /etc/systemd/system/ek-broker.service <<EOF
[Unit]
Description=Epistemic Kernel Broker
After=network.target

[Service]
User=ek-broker
Group=ek-broker
ExecStart=/opt/epistemic-kernel/bin/ek-broker --config /etc/epistemic-kernel/ek-broker.toml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable ek-broker
sudo systemctl start ek-broker

Network security:

# Firewall rules (if broker exposed via HTTP)
sudo ufw allow from 10.0.0.0/8 to any port 8080
sudo ufw allow from 172.16.0.0/12 to any port 8080
sudo ufw allow from 192.168.0.0/16 to any port 8080

🎓 Phase 4: Team Training & Go-Live (Enterprise)

Step 14: Schedule Training Sessions

Training topics:

Architecture Deep Dive (2 hours)
- Understanding the provenance model
- Broker architecture
- Attestor system
- Performance characteristics
Development Workshop (3 hours)
- Building custom agents
- Integrating with your LLMs
- Custom attestor development
- Debugging provenance chains
Operations Training (2 hours)
- Deployment patterns
- Monitoring and alerting
- Backup and recovery
- Troubleshooting
Security Training (1 hour)
- Threat model
- Hardening guidelines
- Compliance considerations
- Incident response

Step 15: Custom Development (If Applicable)

Engagement process:

Requirements gathering (1-2 weeks)
Technical design (1 week)
Development (2-4 weeks)
Testing (1-2 weeks)
Deployment (1 week)
Handoff (1 week)

Communication:

Weekly status calls
Slack channel for daily questions
Shared documentation

Step 16: SLA Verification

SLA testing:

Response time validation
Uptime monitoring setup
Incident response drill
Escalation path verification

Documentation:

Custom SLA agreement
Escalation procedures
Support contacts
Emergency protocols

Step 17: Production Deployment

Deployment checklist:

Broker configured for production
All agents deployed
Monitoring in place
Alerts configured
Backups verified
Security hardened
Documentation complete
Team trained
Rollback plan in place

Go-live sequence:

Staging deployment (1 week before)
Load testing (3 days before)
User acceptance testing (1 day before)
Production cutover (scheduled downtime)
Post-deployment verification (24 hours after)

📋 Quick Reference Commands

Broker Management

# Start broker
sudo systemctl start ek-broker

# Stop broker
sudo systemctl stop ek-broker

# Restart broker
sudo systemctl restart ek-broker

# Check status
sudo systemctl status ek-broker

# View logs
journalctl -u ek-broker -f

# Check version
/opt/epistemic-kernel/bin/ek-broker --version

Agent Development

# Test connection
/opt/epistemic-kernel/bin/ek-cli --socket /tmp/ek.socket ping

# Attest a file
/opt/epistemic-kernel/bin/ek-cli --socket /tmp/ek.socket attest filesystem /path/to/file

# List active agents
/opt/epistemic-kernel/bin/ek-cli --socket /tmp/ek.socket agents

# Check belief store stats
/opt/epistemic-kernel/bin/ek-cli --socket /tmp/ek.socket stats

Monitoring

# Health check
curl https://badlucksbane.com/health

# Metrics
curl http://localhost:9090/metrics

# Prometheus query (example)
curl -G http://localhost:9090/metrics --data-urlencode 'query=ek_broker_requests_total'

🚨 Troubleshooting Guide

Common Issues & Solutions

Broker won’t start:

# Check for port conflicts
lsof -i :8080
ss -tulnp | grep 8080

# Check for socket file conflicts
ls -la /tmp/ek.socket

# Check configuration syntax
/opt/epistemic-kernel/bin/ek-broker --config /etc/epistemic-kernel/ek-broker.toml --validate

Agents can’t connect:

# Test socket connection
nc -U /tmp/ek.socket

# Check broker logs
journalctl -u ek-broker -n 50

# Check permissions
ls -la /tmp/ek.socket

License activation failed:

# Verify license key format (example: EK-ABCD-1234-EFGH-5678)
echo "EK-ABCD-1234-EFGH-5678" | grep -E "^EK-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$"

# Check internet connectivity (for online validation)
curl https://license.badlucksbane.com/validate

# Force offline mode (for air-gapped)
/opt/epistemic-kernel/bin/ek-broker --license-key EK-ABCD-1234-EFGH-5678 --offline

Permission denied errors:

# Check user running the broker
ps aux | grep ek-broker

# Check file permissions
ls -la /var/lib/epistemic-kernel/

# Fix permissions
sudo chown -R ek-broker:ek-broker /var/lib/epistemic-kernel/
sudo chown ek-broker:ek-broker /tmp/ek.socket

Getting Help

Self-service resources:

Support channels:

Tier	Method	Response Time
Open Source	GitHub Discussions	Community
Developer	Email: [email protected]	48 hours
Professional	Email + Slack	12 hours
Enterprise	Phone + Slack	1 hour

Emergency (Enterprise only):

Phone: [Enterprise Emergency Phone] (24/7)
Escalation: TAM will coordinate

📅 Next Steps

After Go-Live

Week 1:

Monitor system health
Review logs for any issues
Test backup and restore
Verify all agents are functioning

Month 1:

Performance tuning
Capacity planning
User feedback collection
Feature request prioritization

Ongoing:

Regular updates (monthly)
Performance reviews (quarterly)
Architecture reviews (annually)

Stay Connected

Join our Discord: discord.gg/badlucksbane (Developer+)
Follow us on Twitter: @badlucksbane
Subscribe to updates: badlucksbane.com/notebook
Check for updates: Releases [source:lab/systems/github-to-gitea-mapping.md]

📚 Additional Resources

Documentation

Community

GitHub Discussions (External dependency - requires GitHub accounts)
Discord Server
Twitter

Support

Portal: https://portal.badlucksbane.com
Email: [email protected]
Phone: +1-555-0199 (24/7)

🎯 Success Checklist

Before you go live, make sure you’ve completed:

Broker installed and running
License activated successfully
At least one agent deployed
Attestors configured for your data sources
Rate limiting configured
Monitoring in place
Backup procedure tested
Security hardened
Team trained (Enterprise)
Rollback plan documented

You’re ready! Welcome to the future of trust-aware multi-agent systems.

Last updated: August 3, 2026
Questions? Contact [email protected]
For emergencies (Enterprise): +1-555-0199 (24/7)