setup-guide

name	setup-guide
description	> Use when this capability is needed.

Setup Guide

LLM Provider

Ollama (default):

export ZEPH_LLM_PROVIDER=ollama
export ZEPH_LLM_BASE_URL=http://localhost:11434
export ZEPH_LLM_MODEL=mistral:7b

Claude:

export ZEPH_LLM_PROVIDER=claude
export ZEPH_CLAUDE_API_KEY=sk-ant-...

Cloud model settings in config/default.toml:

• llm.cloud.model (default: claude-sonnet-4-5-20250929)
• llm.cloud.max_tokens (default: 4096)

OpenAI (or any OpenAI-compatible API):

export ZEPH_LLM_PROVIDER=openai
export ZEPH_OPENAI_API_KEY=sk-...

Config in config/default.toml:

[llm.openai]
base_url = "https://api.openai.com/v1"
model = "gpt-5.2"
max_tokens = 4096
embedding_model = "text-embedding-3-small"
reasoning_effort = "medium"  # low, medium, high (for reasoning models)

• llm.openai.base_url: API endpoint (change for Together, Groq, Fireworks, etc.)
• llm.openai.model: chat model name
• llm.openai.max_tokens: max response tokens (default: 4096)
• llm.openai.embedding_model: optional, enables embeddings support
• llm.openai.reasoning_effort: optional, low/medium/high for reasoning models (o3, etc.)

Embeddings

export ZEPH_LLM_EMBEDDING_MODEL=qwen3-embedding

Used for skill matching and semantic memory. Pull model first:

ollama pull qwen3-embedding

Memory

SQLite storage:

export ZEPH_SQLITE_PATH=.zeph/data/zeph.db

Config: memory.history_limit (default: 50) — recent messages loaded into context.

Semantic Memory (Qdrant)

export ZEPH_MEMORY_SEMANTIC_ENABLED=true
export ZEPH_QDRANT_URL=http://localhost:6334
export ZEPH_MEMORY_RECALL_LIMIT=5

Start Qdrant:

docker compose up -d qdrant

When semantic memory is enabled and Qdrant is reachable, skill embeddings are persisted in a zeph_skills collection. On startup, only changed skills are re-embedded (BLAKE3 content hash comparison). The Qdrant HNSW index is used for skill matching instead of in-memory cosine similarity. If Qdrant is unavailable, the agent falls back to in-memory matching.

Summarization

export ZEPH_MEMORY_SUMMARIZATION_THRESHOLD=100
export ZEPH_MEMORY_CONTEXT_BUDGET_TOKENS=0

Threshold: message count before triggering summarization (0 = disabled). Budget: total token limit for context (0 = unlimited). Split: 15% summaries, 25% recall, 60% recent.

Telegram Mode

export ZEPH_TELEGRAM_TOKEN=123456:ABC-DEF...

Config: telegram.token (prefer env var for security). Access control via telegram.allowed_users in config.

A2A Server

export ZEPH_A2A_ENABLED=true
export ZEPH_A2A_HOST=0.0.0.0
export ZEPH_A2A_PORT=8080
export ZEPH_A2A_PUBLIC_URL=https://my-agent.example.com
export ZEPH_A2A_AUTH_TOKEN=secret-token
export ZEPH_A2A_RATE_LIMIT=60
export ZEPH_A2A_MAX_BODY_SIZE=1048576

Rate limit: requests per minute per IP (0 = unlimited). TLS enforcement and SSRF protection for outbound A2A connections are configured under [a2a_client] below, not here — this server section has no security-policy fields of its own.

A2A Client (--connect)

export ZEPH_A2A_CLIENT_REQUIRE_TLS=true
export ZEPH_A2A_CLIENT_SSRF_PROTECTION=true
export ZEPH_A2A_CARD_TRUST_POLICY=ignore

Security policy for zeph --tui --connect <URL> (remote-TUI attach to another daemon's /a2a/stream). Loopback targets (127.0.0.1, ::1, localhost) always bypass both checks and connect over plain HTTP — this makes zeph --tui --connect http://127.0.0.1:8080/a2a/stream work with a fresh/default config. Non-loopback targets require HTTPS (require_tls) and are DNS-validated to reject private/loopback ranges (ssrf_protection) — RFC 1918 ranges (10.x, 172.16.x, 192.168.x), loopback, and link-local. Max body size: request payload limit in bytes (default 1 MiB).

ZEPH_A2A_CARD_TRUST_POLICY (ignore | prefer | require, default ignore) controls peer AgentCard signature + URL-origin verification during discovery (A2A 1.0.0 §8.4, #5928). require needs the crate's card-signing feature compiled in (part of the a2a feature bundle) or config validation fails at startup. Trusted verification keys are configured via [[a2a_client.trusted_agent_keys]] in config.toml (no env-var equivalent — see config/default.toml for the shape).

Tools

Config: tools.enabled (default: true) — master toggle for all tool execution.

Shell:

export ZEPH_TOOLS_TIMEOUT=30
export ZEPH_TOOLS_SHELL_ALLOWED_COMMANDS=curl,wget
export ZEPH_TOOLS_SHELL_ALLOWED_PATHS=/home/user/workspace,/tmp
export ZEPH_TOOLS_SHELL_ALLOW_NETWORK=true

Config: tools.shell.blocked_commands — additional command patterns to block. Config: tools.shell.allowed_commands — commands to remove from the default blocklist. Config: tools.shell.allowed_paths — restrict filesystem access (empty = cwd only). Config: tools.shell.allow_network — false blocks curl/wget/nc. Config: tools.shell.confirm_patterns — destructive commands requiring user confirmation.

Audit logging:

export ZEPH_TOOLS_AUDIT_ENABLED=true
export ZEPH_TOOLS_AUDIT_DESTINATION=.zeph/data/audit.jsonl

Scrape:

export ZEPH_TOOLS_SCRAPE_TIMEOUT=15
export ZEPH_TOOLS_SCRAPE_MAX_BODY=1048576

MCP (Model Context Protocol)

Build with --features mcp to enable MCP tool integration.

Config in config/default.toml:

[[mcp.servers]]
id = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
timeout = 30

[mcp.servers.env]
GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_PERSONAL_ACCESS_TOKEN}"

MCP tools are discovered at startup, embedded into Qdrant (zeph_mcp_tools collection), and matched per query alongside skills. Tool invocations use mcp fenced blocks with JSON payloads.

Candle Local Inference

Build with --features candle to enable HuggingFace direct inference via candle ML framework. Supports GGUF quantized models.

export ZEPH_LLM_PROVIDER=candle

Config in config/default.toml:

[llm.candle]
source = "huggingface"
repo_id = "TheBloke/Mistral-7B-Instruct-v0.2-GGUF"
filename = "mistral-7b-instruct-v0.2.Q4_K_M.gguf"
chat_template = "mistral"
device = "auto"
embedding_repo = "sentence-transformers/all-MiniLM-L6-v2"

[llm.candle.generation]
temperature = 0.7
max_tokens = 2048

Device selection: auto picks Metal on macOS, CUDA on Linux with GPU, CPU otherwise. Build with --features metal or --features cuda for GPU acceleration.

Chat templates: llama3, chatml, mistral, phi3, raw.

Model Orchestrator

Build with --features orchestrator to enable multi-model routing with task classification and fallback chains.

export ZEPH_LLM_PROVIDER=orchestrator

Config in config/default.toml:

[llm.orchestrator]
default = "ollama"
embed = "ollama"

[llm.orchestrator.providers.ollama]
provider_type = "ollama"

[llm.orchestrator.providers.claude]
provider_type = "claude"

[llm.orchestrator.routes]
coding = ["claude", "ollama"]
creative = ["claude", "ollama"]
general = ["ollama"]

Task types: coding, creative, analysis, translation, summarization, general. Each route is a fallback chain — if the first provider fails, the next one is tried.

Skills

export ZEPH_SKILLS_MAX_ACTIVE=5

Config: skills.paths (default: [".zeph/skills"]). Top-K skills selected per query via embedding similarity. File changes detected automatically (hot-reload).

Sub-Agents

Live transcript forwarding — stream a running sub-agent's full per-turn text/thinking to the TUI runtime detail view and/or --bare stdout as it happens, instead of only a 120-char once-per-turn snippet:

export ZEPH_AGENTS_FORWARD_TRANSCRIPT=true

Opt-in, default false (agents.forward_transcript in config). Also settable via --forward-subagent-text. No effect unless a consumer surface (--tui or --bare) is active for the session.

Delegation mode — control whether the main agent may spawn sub-agents, and who may trigger it:

export ZEPH_AGENTS_DELEGATION_MODE=explicit_request_only

One of disabled (no spawn from any code path), explicit_request_only (only direct user actions — /agent spawn, /agent resume, /subagent spawn — the main agent's own planner/ scheduler may never spawn autonomously), or proactive (default; both explicit and autonomous spawns allowed). Orthogonal to agents.enabled, which remains the outer kill switch: enabled = false always behaves as disabled regardless of this setting. Also settable via --delegation-mode. Useful to restrict in semi-trusted channels (Telegram/Discord/webhook ingestion) where prompt-injected input could otherwise trigger unsupervised delegation.

Security

Secret redaction:

export ZEPH_SECURITY_REDACT_SECRETS=true

Scans LLM responses for API keys, tokens, passwords, and private keys. Replaces detected secrets with [REDACTED].

Timeouts:

export ZEPH_TIMEOUT_LLM=120
export ZEPH_TIMEOUT_EMBEDDING=30
export ZEPH_TIMEOUT_A2A=30

Config: timeouts.llm_seconds, timeouts.embedding_seconds, timeouts.a2a_seconds.

---

Source: bug-ops/zeph — distributed by TomeVault.