Configuration

Configuration

Environment variables and settings for MAINFRAME.

---

Table of Contents

• Required Variables
• Output Configuration
• Logging Configuration
• Agent Configuration
• Performance Configuration
• Per-Library Configuration

---

Required Variables

MAINFRAME_ROOT

Required. Path to MAINFRAME installation.

export MAINFRAME_ROOT="$HOME/.mainframe"

This must be set before sourcing any MAINFRAME libraries.

---

Output Configuration

MAINFRAME_OUTPUT

Controls output format for USOP-enabled functions.

Value	Description
text (default)	Plain text output
json	Structured JSON output

# Enable JSON output
export MAINFRAME_OUTPUT=json

# Functions return structured JSON
output_success "done"
# {"ok":true,"data":"done"}

MAINFRAME_COLOR

Controls colored output.

Value	Description
auto (default)	Color if terminal supports it
always	Always use colors
never	Never use colors

# Disable colors (e.g., for log files)
export MAINFRAME_COLOR=never

MAINFRAME_QUIET

Suppress non-essential output.

export MAINFRAME_QUIET=1

---

Logging Configuration

LOG_LEVEL

Controls log verbosity.

Level	Description
debug	All messages including debug
info (default)	Informational and above
warn	Warnings and errors only
error	Errors only
silent	No logging

export LOG_LEVEL=debug  # Verbose logging
export LOG_LEVEL=error  # Errors only

LOG_FILE

Write logs to file in addition to stderr.

export LOG_FILE="/var/log/myapp.log"

LOG_JSON

Output logs as JSON.

export LOG_JSON=1

log_info "Starting server" "port=8080"
# {"level":"info","msg":"Starting server","port":"8080","timestamp":"..."}

LOG_TIMESTAMP

Include timestamps in logs.

Value	Description
1 (default)	Include timestamps
0	No timestamps
iso	ISO 8601 format
unix	Unix timestamp

export LOG_TIMESTAMP=iso

---

Agent Configuration

AGENT_ALLOWED_COMMANDS

Space-separated list of allowed commands for agent_safe_exec.

export AGENT_ALLOWED_COMMANDS="ls cat grep git npm node python"

AGENT_BLOCKED_COMMANDS

Space-separated list of explicitly blocked commands.

export AGENT_BLOCKED_COMMANDS="rm dd mkfs shutdown reboot"

AGENT_STRICT_MODE

When enabled, only whitelisted commands can run.

export AGENT_STRICT_MODE=1  # Whitelist only

AGENT_AUDIT_LOG

Path to audit log file.

export AGENT_AUDIT_LOG="/var/log/agent_audit.log"

AGENT_ID

Identifier for this agent (used in logs and coordination).

export AGENT_ID="worker-1"

AGENT_DRY_RUN

Log commands without executing.

export AGENT_DRY_RUN=1

AGENT_BASE_DIR

Base directory for agent communication files.

export AGENT_BASE_DIR="/var/lib/mainframe/agents"

AGENT_MESSAGE_TTL

Message time-to-live in seconds.

export AGENT_MESSAGE_TTL=3600  # 1 hour

AGENT_TASK_TTL

Task time-to-live in seconds.

export AGENT_TASK_TTL=86400  # 24 hours

---

Performance Configuration

MAINFRAME_LAZY

Enable lazy loading of libraries.

export MAINFRAME_LAZY=1

Libraries are loaded on first function call instead of at source time.

MAINFRAME_CACHE

Enable function result caching.

export MAINFRAME_CACHE=1

MAINFRAME_CACHE_DIR

Directory for cache files.

export MAINFRAME_CACHE_DIR="/tmp/mainframe_cache"

MAINFRAME_CACHE_TTL

Default cache time-to-live in seconds.

export MAINFRAME_CACHE_TTL=300  # 5 minutes

---

Per-Library Configuration

http.sh

# Default timeout for HTTP requests (seconds)
export HTTP_TIMEOUT=30

# User agent string
export HTTP_USER_AGENT="MAINFRAME/5.0"

# Follow redirects
export HTTP_FOLLOW_REDIRECTS=1
export HTTP_MAX_REDIRECTS=5

datetime.sh

# Default timezone
export TZ="America/New_York"

# Date format
export DATE_FORMAT="%Y-%m-%d"
export TIME_FORMAT="%H:%M:%S"

git.sh

# Default branch name
export GIT_DEFAULT_BRANCH="main"

docker.sh

# Docker compose file
export COMPOSE_FILE="docker-compose.yml"

# Docker host
export DOCKER_HOST="unix:///var/run/docker.sock"

validation.sh

# Path validation base (required for validate_path_safe)
export VALIDATION_BASE_PATH="/allowed/base"

# Email validation strictness
export EMAIL_VALIDATION_STRICT=1

---

Configuration Files

Shell Profile

Add to ~/.bashrc or ~/.zshrc:

# MAINFRAME Configuration
export MAINFRAME_ROOT="$HOME/.mainframe"
export MAINFRAME_OUTPUT=json
export LOG_LEVEL=info

# Agent Configuration
export AGENT_ID="$(hostname)-$$"
export AGENT_AUDIT_LOG="/var/log/agent.log"
export AGENT_ALLOWED_COMMANDS="ls cat grep git npm node"

# Load MAINFRAME
source "$MAINFRAME_ROOT/lib/common.sh"

Project Configuration

Create .mainframerc in project root:

# Project-specific MAINFRAME configuration
export MAINFRAME_OUTPUT=json
export LOG_LEVEL=debug
export AGENT_STRICT_MODE=1

Load in scripts:

#!/bin/bash
[[ -f .mainframerc ]] && source .mainframerc
source "$MAINFRAME_ROOT/lib/common.sh"

Environment-Specific

Use dotenv pattern:

# .env.production
MAINFRAME_OUTPUT=json
LOG_LEVEL=warn
AGENT_STRICT_MODE=1

# .env.development
MAINFRAME_OUTPUT=text
LOG_LEVEL=debug
AGENT_STRICT_MODE=0

Load with:

env_load_dotenv ".env.${ENVIRONMENT:-development}"

---

Variable Summary

Variable	Default	Description
MAINFRAME_ROOT	required	Installation path
MAINFRAME_OUTPUT	text	Output format
MAINFRAME_COLOR	auto	Color output
MAINFRAME_QUIET	0	Suppress output
MAINFRAME_LAZY	0	Lazy loading
LOG_LEVEL	info	Log verbosity
LOG_FILE	-	Log file path
LOG_JSON	0	JSON logging
AGENT_ID	default	Agent identifier
AGENT_STRICT_MODE	0	Whitelist only
AGENT_AUDIT_LOG	-	Audit log path
AGENT_DRY_RUN	0	Log without execute

---

MAINFRAME · The AI-Native Bash Runtime

Home · Installation · Library Reference