Tenzai Onboarding

⚡ Prerequisites

What is mise?

mise (pronounced "meez") is a polyglot tool version manager and task runner. It replaces tools like nvm, pyenv, rbenv, and make.

Install mise

# Install
brew install mise

# Add to shell (zsh)
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
source ~/.bashrc

☁️ AWS Setup

Initial SSO Configuration

The first run of mise run all or mise run agent in the tenzai repo auto-configures AWS SSO. For manual setup:

aws configure sso
# SSO start URL: https://tenzai.awsapps.com/start/#
# SSO region: eu-north-1
# Default region: eu-central-1
# Output format: json

AWS Start Page

Available Profiles

Daily Login

The easiest way to login to AWS is through mise:

# This will open browser for SSO login and decrypt secrets
cd ~/projects/tenzai
mise run secrets

Alternatively, use AWS CLI directly:

aws sso login --profile dev

Sessions expire after ~8 hours. If you get authentication errors, just run the login command again.

📦 Repository Overview

Clone All Repos

cd ~/projects
git clone git@github.com:TenzaiLtd/tenzai.git
git clone git@github.com:TenzaiLtd/evaluation.git
git clone git@github.com:TenzaiLtd/labs.git

🚀 Tenzai Platform

Location: ~/projects/tenzai

Get Started

cd ~/projects/tenzai
git checkout main && git pull

# Trust and install tools
mise trust
mise install

# Start full platform
mise run all

Directory Structure

Core Services (the main components)

Agent Toolboxes (containers used by the agent)

Infrastructure

Supportive Components

Config Files

Local Development with Tilt

What is Tilt?

Tilt is a toolkit for local Kubernetes development. It watches your source code, automatically rebuilds containers, and updates your cluster in real-time. Think of it as "hot reload for Kubernetes."

Architecture Diagram

What is LocalStack?

LocalStack emulates AWS services locally so you don't need real AWS resources during development:

• S3: File storage for reports and artifacts
• SQS: Message queues for async job processing
• SNS: Notifications and event publishing

Running the Platform

mise run all

This command:

1. Syncs Python dependencies (uv sync)
2. Decrypts SOPS secrets
3. Creates k3d cluster tenzai-local with local registry
4. Deploys all services via Helm chart
5. Sets up LocalStack for AWS emulation
6. Runs database migrations
7. Starts the UI dev server

Local Endpoints

Common mise Tasks

mise run all           # Full platform via Tilt
mise run agent         # Run agent standalone
mise run lint          # Lint codebase
mise run test          # Unit tests
mise run secrets       # Edit encrypted secrets (SOPS)
mise run local-db:psql # Open psql shell
mise run local-db:reset # Reset DB + seed
mise run jwt           # Get JWT for API testing
mise run k9s:local     # k9s for local cluster
mise run clean         # Complete cleanup

CI/CD Pipeline

The tenzai repo uses GitHub Actions for continuous integration and deployment.

CI Gates (Pull Requests)

PR Environments

Deployment Flow

📊 Evaluation System

Location: ~/projects/evaluation

What is the Evaluation System?

Get Started

cd ~/projects/evaluation
git checkout main && git pull
uv sync

Directory Structure

evaluation/
├── .github/
│   ├── actions/       # Composite actions (deploy-lab, eval, run-tenzai)
│   └── workflows/     # GitHub Actions workflows
├── cli/               # Dojo CLI
├── dojo-sdk/          # Python SDK for deployments
├── dojo-web/          # Web UI (React)
├── evaluator/         # LLM-based evaluation engine
├── experiments/       # Benchmark orchestration
└── suite-files/       # Lab suite configurations (YAML)

Dojo

Dojo is our lab deployment and management system for deploying vulnerable applications to test the agent.

What Dojo Does

• Deploys labs to GKE clusters with proper networking and secrets
• Triggers Tenzai agent runs against deployed labs
• Tracks deployment status and manages lifecycle (auto-teardown)
• Supports individual lab and batch suite deployments

Dojo CLI

# Install globally
uv tool install --from "git+https://github.com/TenzaiLtd/evaluation.git#subdirectory=cli" dojo --force

# Run
uvx dojo

Features: Browse labs, deploy with custom configs, select agent/LLM, view active deployments, destroy labs.

Dojo Web UI

Web interface at https://tenzailtd.github.io/evaluation/ — GitHub OAuth, visual lab browser, real-time deployment tracking.

GitHub Actions Workflows

Evaluator

LLM-based system that compares agent findings against ground truth:

cd evaluator
uv sync --dev
uv run pytest tests/

🧪 Labs Repository

Location: ~/projects/labs

What is the Labs Repo?

Contains the source code and infrastructure for all vulnerable applications used in evaluation — the targets that the Tenzai agent scans.

Lab Types

Get Started

cd ~/projects/labs
git checkout main && git pull

Directory Structure

labs/
├── tbench/                     # T-Bench labs (app-001 ... app-023b)
├── xben-001-24/ ... xben-104-24/  # X-Bench labs
├── cve-bench/                  # CVE reproduction labs
├── dvwp/                       # Damn Vulnerable WordPress
├── juiceshop/                  # OWASP Juice Shop
├── opencart/                   # OpenCart e-commerce
└── zabbix/                     # Zabbix monitoring

Local Development

cd labs/tbench/app-001

# Create env configuration
mkdir -p ~/.config/tbench
cat > ~/.config/tbench/.env << EOF
NAMESPACE_PREFIX=local
LOCAL_K8S_CONTEXT=docker-desktop
EOF
ln -s ~/.config/tbench/.env .env

# Deploy locally
just run

# Access at http://localhost:300XX
curl http://localhost:30010/api/health

# Stop
just stop

Remote Deployment (GKE)

# Authenticate
gcloud auth login
gcloud container clusters get-credentials lab-cluster --region=us-central1

# Deploy (commit changes first!)
just deploy

# Get endpoint info
just describe

# Destroy
just destroy

ZeroTier Network Access

Labs on GKE use internal LoadBalancers. To access from your machine:

1. Install ZeroTier: brew install zerotier-one
2. Join network: sudo zerotier-cli join <network-id> (get from 1Password web)
3. Approve your device in ZeroTier admin console
4. Lab endpoints accessible via internal IPs

🌐 Environments

Environment Overview

⚡ Quick Reference

Daily Workflow

# 1. Login to AWS (opens browser)
cd ~/projects/tenzai
mise run secrets

# 2. Start tenzai platform
git pull
mise run all

# 3. Access
open http://localhost:4200  # UI
open http://localhost:8000/docs  # API

Common Commands

Getting Help

• Slack: #engineering
• Docs: /tenzai/docs/
• API Docs: http://localhost:8000/docs

Links & References