STATEK Configuration

STATEK configuration is normal Python settings plus environment variables.

Configuration tells STATEK where to find model credentials, prompt files, logs, examples, documents, and execution limits. Your application still controls which agents, jobs, tools, and Python objects are created.

The most common setup is:

STATEK_PROMPT_FILES_DIR=./prompts
STATEK_LOG_LEVEL=INFO
STATEK_LOGS_PATH=./statek-logs
 
OPENROUTER_API_URL=https://openrouter.ai/api/v1
OPENROUTER_API_KEY=...

Prompt files and provider keys are configuration. The durable application objects, job creation logic, and tool permissions are application code.

Settings Sources

StatekSettings reads configuration from several places:

• values passed directly in Python
• configured settings sources
• .env
• process environment variables

The module helpers get_statek_settings() and get_provider_settings() are cached. That is usually what you want in a long-running worker. In tests or dynamic configuration scenarios, clear those caches before expecting new environment values to be visible.

from statek.settings import StatekSettings
 
settings = StatekSettings(
    default_llm_api_provider="OPENAI",
    prompt_files_dir="./prompts",
    logs_path="./statek-logs",
)

Use constructor values when your application already has a config object. Use environment variables for local development, containers, and deployment systems.

Provider Credentials

STATEK detects provider credentials from environment variables with this pattern:

{PROVIDER}_API_URL=...
{PROVIDER}_API_KEY=...

For example:

OPENAI_API_URL=https://api.openai.com/v1
OPENAI_API_KEY=...
 
OPENROUTER_API_URL=https://openrouter.ai/api/v1
OPENROUTER_API_KEY=...

Any provider name can be detected when both {PROVIDER}_API_URL and {PROVIDER}_API_KEY are present. Provider-specific behavior and support details belong on the Model Providers page; this page only describes how credentials are loaded.

For providers that are not built in, register the provider name or a custom implementation with add_provider(...); see Custom Providers.

Optional provider fields follow the same prefix:

OPENAI_RESPONSE_FORMAT_FILE=./response-format.json
ANTHROPIC_USE_PROMPT_CACHING=true

Default Provider and Models

default_llm_api_provider defaults to OPENROUTER.

You can set it in Python:

settings = StatekSettings(default_llm_api_provider="OPENAI")

or configure the process environment through your settings system.

The default provider is not the whole model configuration. Agents and job definitions still need model metadata. In typical applications, that metadata lives in prompt definition files:

# MODEL: openai/gpt-5-mini
# CHAT_STYLE: DIRECT
 
# System Prompt
You help users by writing Python against the objects in context.

Prompt Files

Most real STATEK applications keep prompts and agent metadata in .md files.

Set the prompt directory with:

STATEK_PROMPT_FILES_DIR=./prompts

Prompt definitions are loaded by name, typically matching an agent role. The file carries metadata comments and a # System Prompt section.

# MODEL: openai/gpt-5-mini
# LLM_TOOLS_SCOPE: APPLICATION
 
# System Prompt
ROLE: Calendar assistant.
 
Available variables: {shared_var_names}
Available tools:
{brief_tools}

The earlier documentation pages use inline prompt examples to make the mechanics visible. In normal applications, .md definitions are usually easier to review, version, and update. See Prompt Definitions for the full prompt file format, supported metadata, section syntax, difficulty handling, placeholders, and chat styles.

Common STATEK Variables

These environment variables configure common STATEK behavior:

STATEK_PROMPT_FILES_DIR=./prompts
STATEK_LOGS_PATH=./statek-logs
STATEK_LOG_LEVEL=INFO
 
STATEK_EXAMPLES_DIR=./examples
STATEK_DOCUMENTS_DIR=./documents
STATEK_MODEL_INFO_DIR=./model-info
 
STATEK_PYTHON_SANDBOX_MODE=restricted
STATEK_PYTHON_SANDBOX_MAX_SOURCE_BYTES=200000
STATEK_PYTHON_SANDBOX_MAX_AST_NODES=20000
 
STATEK_CHAT_STYLE=DIRECT
STATEK_EXAMPLES_STYLE=MARKDOWN
 
STATEK_XML_BOX_CONSOLE=console_output
STATEK_XML_BOX_EXAMPLE=code_block
 
STATEK_DEFAULT_ACL=DENY
STATEK_DEFAULT_DIFFICULTY=M
 
STATEK_RPC_HOST=127.0.0.1
STATEK_RPC_PORT=9000

Use only the variables your application needs. Leaving a variable unset is valid for many local setups. See Examples Machinery for STATEK_EXAMPLES_DIR, Documents Machinery for STATEK_DOCUMENTS_DIR, STATEK Metering for STATEK_MODEL_INFO_DIR, Security for sandbox settings, and Chat Styles for how STATEK_CHAT_STYLE, STATEK_EXAMPLES_STYLE, and console boxing affect LLM-facing code, output, dialog, and examples.

Execution Limits

STATEK has harness settings for bounded LLM-driven execution:

STATEK_MAX_TURNS=5
STATEK_MAX_EXCEPTIONS=3
STATEK_MAX_CONSECUTIVE_EXCEPTIONS=1
STATEK_MAX_TOKEN_USAGE=10000
STATEK_LIMIT_EXTENSION_PER_COMPLETION=0

These limits help stop runaway jobs, repeated failures, and oversized interactions. See Harness Policies for practical presets, per-job counting behavior, completion-based limit extension, and failure handling.

They are not a substitute for sandboxing, permissions, provider quotas, or operational monitoring.

Logging

STATEK_LOG_LEVEL controls the STATEK logger level:

STATEK_LOG_LEVEL=INFO

Supported levels are:

• INFO
• WARNING
• ERROR
• CRITICAL

STATEK_LOGS_PATH enables file-oriented job logging where the runtime uses it:

STATEK_LOGS_PATH=./statek-logs

For development, verbose logs are useful. For production, route logs through your normal logging pipeline and avoid writing secrets or raw sensitive payloads into inspectable job history.

dbzero State

STATEK stores durable jobs and Python objects through dbzero-backed state.

That means your job objects, Python execution state, chat history, and dbzero application objects are durable according to the dbzero runtime and storage configuration your application uses.

This page does not assume a specific storage layout. Local data location, backups, replication, and dbzero-pro usage are deployment choices outside the basic STATEK settings surface.

Use dbzero-pro or other deployment-specific storage features when your application needs them. Do not assume they are required for a local development setup.

Development Setup

A local development .env can be small:

STATEK_PROMPT_FILES_DIR=./prompts
STATEK_LOG_LEVEL=INFO
STATEK_LOGS_PATH=./statek-logs
 
OPENROUTER_API_URL=https://openrouter.ai/api/v1
OPENROUTER_API_KEY=...

Then application code can create agents, jobs, and context objects:

from statek.settings import get_statek_settings
 
settings = get_statek_settings()

Keep local prompts and tools narrow. It is easy to give an agent broad Python access during development; be deliberate about what objects and credentials are placed in context.

Production Setup

Production configuration should be stricter:

• store provider keys in a managed secret system
• keep STATEK_DEFAULT_ACL=DENY unless you have a specific reason not to
• use explicit data paths, backups, and retention policies for durable state
• keep job limits bounded
• keep tool lists and context objects minimal
• audit side-effecting tools
• separate user input, secrets, and privileged adapters
• route logs to your operational logging system
• monitor model usage, exceptions, and queue depth

Configuration alone does not make Python execution safe.

Quick Checklist

For a new local project:

• choose a default provider and set {PROVIDER}_API_URL plus {PROVIDER}_API_KEY
• create a prompt directory and set STATEK_PROMPT_FILES_DIR
• set STATEK_LOG_LEVEL=INFO while developing
• keep execution limits low until workflows are understood
• pass only the Python objects each job actually needs
• keep side-effecting tools explicit and permissioned

That is enough configuration for the STATEK mental model to work: agents execute Python, jobs persist state, and dbzero-backed objects remain ordinary durable Python application objects.

Where to go next

Read Model Providers for provider-specific settings, Custom Providers for add_provider(...), Security for secrets and sandboxing, and API Reference for StatekSettings.