SDK Configuration Reference

Environment variables, scope resolution, transport selection, endpoint defaults, and client options for Mubit SDKs.

All Mubit SDKs (Python, Node.js, Rust) share one configuration model: explicit arguments first, then with_options / scope context, then environment variables. The SDK never reads an environment variable at import time; everything is resolved when mubit.init() or Client() runs.

Environment variables

The console shows the first four with every new key; copy them as one block.

MUBIT_API_KEY="mbt_<instance>_<key_id>_<secret>"
MUBIT_ENDPOINT="https://api.mubit.ai"
MUBIT_PROJECT="first-project"
MUBIT_ENV="dev"

Scoping

project  →  env  →  agent  →  user  →  run  →  step
                    (thread = conversation id carried on events)

Lessons are partitioned by env (MUBIT_ENV, default dev). project and agent label lessons but do not isolate them; what another run sees is decided by the policy's overlay gate. A context() call in a different env returns zero units; the returned ContextBlock.scope shows which project/env was used.

Resolution order per scope field, first wins:

1. Explicit call argument (mubit.run(env="prod"), client.memory.recall(..., run_id=...))
2. client.with_options(scope=...) or mubit.scope(...) context
3. The active run / step context
4. The mubit.init() / Client() default scope
5. Environment (MUBIT_PROJECT, MUBIT_ENV, MUBIT_AGENT, MUBIT_USER, MUBIT_RUN_ID)

ContextBlock.scope and OutcomeReceipt echo the resolved project, env and agent, so a mismatch is visible in the return value. mubit doctor prints the same resolution as its scope: line.

Write-time visibility is one field, visibility="run" | "agent" | "project" | "global" (replaces lesson_scope and share). session_id is accepted as a deprecated alias: of run_id on memory calls and of thread on mubit.run().

Transport selection

The transport option controls how the SDK communicates with Mubit:

The loop routes (/v2/loop/*) are HTTP in every transport mode.

from mubit import Client
 
# From environment (default)
client = Client()
 
# Force gRPC
client = Client(transport="grpc")
 
# Force HTTP with an explicit key and endpoint
client = Client(
    api_key="mbt_...",
    transport="http",
    endpoint="https://custom.api.mubit.ai",
)

Endpoint defaults

Both hosted endpoints use TLS. Local endpoints are plaintext.

mubit.init() and Client() default to https://api.mubit.ai. Set MUBIT_ENDPOINT explicitly anyway: the CLI and the deprecated learn path still default to the local address in 0.14, and the SDK prints one warning when a local default is used without MUBIT_ENDPOINT. The four-line .env block from the console sets it.

Client options

Client takes keyword options only; Client(endpoint) positional is accepted until 1.0.

client.with_options(timeout=..., max_retries=..., scope=..., on_error=...) returns a client with the overrides applied. mubit.init() takes the same options plus agent, env, project, user, run_id, inject=InjectOptions(...), capture=CaptureOptions(...), instrument, console_url and defaults on_error to "warn".

Failure policy

The legacy fail_open=True / fail_open=False booleans are accepted as aliases of on_error="warn" / "raise" until 1.0.

Next steps

• See Quickstart for the two-run loop.
• See gRPC Transport Guide for gRPC-specific guidance.
• See Migration for every renamed variable and option.