Aleph Configuration Guide

Aleph Configuration Guide

All configuration options for Aleph: environment variables, CLI flags, and programmatic configuration.

Quick Reference

Sub-Query Configuration

The sub_query tool spawns independent sub-agents for recursive reasoning. It can use an API backend (OpenAI-compatible) or a local CLI backend (Claude, Codex, Gemini). Auto mode prioritizes CLI backends, then falls back to API.

Environment Variables

Backend Priority (auto mode)

When ALEPH_SUB_QUERY_BACKEND is not set or set to auto:

1. codex CLI -- if installed (uses OpenAI subscription)
2. gemini CLI -- if installed (uses Google Gemini subscription)
3. claude CLI -- if installed (deprioritized in MCP/sandbox contexts)
4. API -- if any API credentials are available (fallback)

Force a Specific Backend

export ALEPH_SUB_QUERY_BACKEND=api      # Force API backend
export ALEPH_SUB_QUERY_BACKEND=claude   # Force Claude CLI
export ALEPH_SUB_QUERY_BACKEND=codex    # Force Codex CLI
export ALEPH_SUB_QUERY_BACKEND=gemini   # Force Gemini CLI
export ALEPH_SUB_QUERY_BACKEND=auto     # Return to auto selection

CLI Flags (sub-query)

These flags set environment variables before the MCP server starts:

aleph --sub-query-backend claude
aleph --sub-query-timeout 90
aleph --sub-query-share-session true

# Combined
aleph --sub-query-backend codex --sub-query-timeout 120 --sub-query-share-session false

Runtime Configuration

MCP tool:

mcp__aleph__configure(sub_query_backend="claude")
mcp__aleph__configure(sub_query_timeout=90, sub_query_share_session=True)

REPL helpers:

set_backend("gemini")
get_config()

Runtime Switching (No Restart)

Users can ask the LLM to switch backends naturally:

• "Use the Claude backend for sub-queries"
• "Switch to Gemini"
• "aleph sub-query codex"

The LLM calls set_backend("claude") or configure(sub_query_backend="claude") -- takes effect immediately.

Backend Comparison

API Backend Configuration

The API backend supports any OpenAI-compatible endpoint:

Precedence: ALEPH_SUB_QUERY_URL overrides OPENAI_BASE_URL. If neither is set, Aleph uses https://api.openai.com/v1.

Examples:

# OpenAI
export ALEPH_SUB_QUERY_API_KEY=sk-...
export ALEPH_SUB_QUERY_MODEL=your-model-name

# Groq (fast inference)
export ALEPH_SUB_QUERY_API_KEY=gsk_...
export ALEPH_SUB_QUERY_URL=https://api.groq.com/openai/v1
export ALEPH_SUB_QUERY_MODEL=llama-3.3-70b-versatile

# Together AI
export ALEPH_SUB_QUERY_API_KEY=...
export ALEPH_SUB_QUERY_URL=https://api.together.xyz/v1
export ALEPH_SUB_QUERY_MODEL=meta-llama/Llama-3-70b-chat-hf

# DeepSeek
export ALEPH_SUB_QUERY_API_KEY=...
export ALEPH_SUB_QUERY_URL=https://api.deepseek.com/v1
export ALEPH_SUB_QUERY_MODEL=deepseek-chat

# Ollama (local) -- make sure the server is running
export ALEPH_SUB_QUERY_API_KEY=ollama   # any non-empty value
export ALEPH_SUB_QUERY_URL=http://localhost:11434/v1
export ALEPH_SUB_QUERY_MODEL=llama3.2

# LM Studio (local) -- make sure the server is running
export ALEPH_SUB_QUERY_API_KEY=lm-studio   # any non-empty value
export ALEPH_SUB_QUERY_URL=http://localhost:1234/v1
export ALEPH_SUB_QUERY_MODEL=local-model

Using OPENAI_ fallbacks:*

If you already have OPENAI_API_KEY and OPENAI_BASE_URL set, you only need the model:

export ALEPH_SUB_QUERY_MODEL=your-model-name

CLI Backend Notes

Sub-Aleph (Nested Recursion)

The sub_aleph tool runs a full Aleph loop inside another Aleph run. Control recursion depth with:

• ALEPH_MAX_DEPTH (default 2) for how many nested levels are allowed
  • Example: set ALEPH_MAX_DEPTH=3 to allow one extra nested layer

sub_aleph uses the standard Aleph provider/model settings: ALEPH_PROVIDER, ALEPH_MODEL, ALEPH_SUB_MODEL, ALEPH_API_KEY.

MCP Server Configuration

CLI Flags

# Basic usage
aleph

# With action tools enabled (file/command access)
aleph --enable-actions --tool-docs concise

# Custom timeout and output limits
aleph --timeout 60 --max-output 100000

# Sub-query backend configuration
aleph --sub-query-backend claude --sub-query-timeout 90 --sub-query-share-session true

# Custom file size limits (read/write)
aleph --enable-actions --max-file-size 2000000000 --max-write-bytes 200000000

# Require confirmation for action tools
aleph --enable-actions --tool-docs concise --require-confirmation

# Custom workspace root
aleph --enable-actions --tool-docs concise --workspace-root /path/to/project

# Allow any git repo (use absolute paths in tool calls)
aleph --enable-actions --tool-docs concise --workspace-mode git

# Full tool docs (larger MCP tool list payload)
aleph --tool-docs full

Workspace auto-detection: if --workspace-root is not set, Aleph will:

1. Use ALEPH_WORKSPACE_ROOT if provided
2. Prefer PWD (falls back to INIT_CWD) when present
3. Fall back to os.getcwd() and walk up to the nearest .git root

Power Features (Default When Actions Enabled)

MCP Client Configuration

Claude Desktop / Cursor / Windsurf:

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": ["--enable-actions", "--tool-docs", "concise"],
      "env": {
        "ALEPH_SUB_QUERY_API_KEY": "${ALEPH_SUB_QUERY_API_KEY}",
        "ALEPH_SUB_QUERY_MODEL": "${ALEPH_SUB_QUERY_MODEL}"
      }
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.aleph]
command = "aleph"
args = ["--enable-actions", "--tool-docs", "concise"]

Deployment Profiles

Aleph ships two context policies that control how aggressively the server guards raw context at the MCP boundary. Choose based on your threat model.

Trusted (default)

Low friction. Auto memory-pack save/load on startup and finalize. Session export without explicit confirmation. Best for local development, personal analysis, and trusted MCP clients.

# Explicit (same as default)
export ALEPH_CONTEXT_POLICY=trusted

Isolated

Explicit-consent mode. Designed for shared-server deployments, untrusted MCP clients, or any scenario where context should not leave RAM without deliberate action.

export ALEPH_CONTEXT_POLICY=isolated

Behavioral differences in isolated mode:

When a tool is blocked in isolated mode, the response includes actionable alternatives (e.g. use exec_python + get_variable, peek_context, search_context) and a hint to switch policy via configure() if appropriate.

Switching at Runtime

configure(context_policy="isolated")   # Enables isolated guards
configure(context_policy="trusted")    # Restores defaults

The configure response confirms the new policy and explains what changed.

Output Feedback Mode

Controls how exec_python results are formatted in the core RLM loop. Aligned with the RLM paper's observation that metadata-only feedback can reduce context window consumption.

export ALEPH_OUTPUT_FEEDBACK=metadata

Or at runtime:

configure(output_feedback="metadata")

When to use metadata mode: Large-scale analysis where exec_python produces verbose output that would fill the context window. The LLM sees dimensions (e.g. "stdout_lines: 42, stdout_chars: 8301") and can request specific slices via peek_context or get_variable as needed.

When to keep full mode: Interactive exploration, debugging, and any workflow where seeing raw output is more efficient than navigating by metadata.

Context Isolation

Aleph enforces hard boundaries so raw context never leaks into MCP tool responses:

get_variable("ctx") is blocked. The MCP boundary refuses to return the raw context variable. In isolated mode the error message lists alternatives. Process data inside exec_python and retrieve only compact derived results:

exec_python(code="summary = ctx[:100]", context_id="doc")
get_variable(name="summary", context_id="doc")

Execution output is truncated. exec_python stdout, stderr, and return values are each truncated at the sandbox level, then the formatted MCP response is capped again at max_tool_response_chars.

Sandbox Configuration

The Python sandbox can be configured programmatically:

from aleph.repl.sandbox import SandboxConfig, REPLEnvironment

config = SandboxConfig(
    timeout_seconds=60.0,       # Code execution timeout
    max_output_chars=50000,     # Truncate output after this
)

repl = REPLEnvironment(
    context="your document here",
    context_var_name="ctx",
    config=config,
)

Sandbox Security

Blocked:

• File system access (open, os, pathlib)
• Network access (socket, urllib, requests)
• Process spawning (subprocess, os.system)
• Dangerous builtins (eval, exec, compile)
• Dunder attribute access (__class__, __globals__, etc.)

Allowed imports:

re, json, csv, math, statistics, collections, itertools, functools, datetime, textwrap, difflib, random, string, hashlib, base64, urllib.parse, html

Budget Configuration

Control resource usage programmatically:

from aleph.types import Budget

budget = Budget(
    max_tokens=100_000,         # Total token limit
    max_iterations=100,         # Iteration limit
    max_depth=5,                # Recursive depth (sub_aleph/sub_query)
    max_wall_time_seconds=300,  # Wall clock timeout
    max_sub_queries=50,         # Sub-query count limit
)

Environment File

Create a .env file in your project root:

# Sub-query API configuration (OpenAI-compatible)
ALEPH_SUB_QUERY_API_KEY=sk-...
ALEPH_SUB_QUERY_MODEL=your-model-name

# Optional: custom endpoint
# ALEPH_SUB_QUERY_URL=https://api.groq.com/openai/v1

# Or use CLI backend (no API key needed)
# ALEPH_SUB_QUERY_BACKEND=claude

# Optional: strict output validation + retries
# ALEPH_SUB_QUERY_VALIDATION_REGEX=^[-*]
# ALEPH_SUB_QUERY_MAX_RETRIES=2
# ALEPH_SUB_QUERY_RETRY_PROMPT=Return ONLY bullet lines starting with "- ".

# Resource limits
ALEPH_MAX_ITERATIONS=100

# MCP remote tool timeout (seconds)
ALEPH_REMOTE_TOOL_TIMEOUT=120

Load with your shell or tool of choice (e.g., source .env, dotenv, or IDE integration).

Troubleshooting

Sub-query not working

1. Check backend detection:

   # Which CLI tools are available?
   which claude codex
   
   # Are API credentials set?
   echo $ALEPH_SUB_QUERY_API_KEY $OPENAI_API_KEY
   

2. Force a specific backend to test:

   export ALEPH_SUB_QUERY_BACKEND=api
   export ALEPH_SUB_QUERY_API_KEY=sk-...
   export ALEPH_SUB_QUERY_MODEL=your-model-name
   

3. Check logs for errors in the MCP client.

Sub-query timeout

Increase the timeout and/or reduce context slice size:

export ALEPH_SUB_QUERY_TIMEOUT=120
aleph --sub-query-timeout 120

Sandbox timeout

aleph --timeout 120

Output truncated

aleph --max-output 100000

Actions disabled

aleph --enable-actions --tool-docs concise

See Also