Configuration Guide¶

Use this page for hand-written configuration examples and operational notes. For exact model fields, see Configuration Reference.

Nomad expands environment placeholders in string config values before schema validation. Use ${VAR} to read an environment variable and ${VAR:DEFAULT} to supply a fallback value when it is unset. This is the same mechanism used by examples such as Bearer ${NOMAD_API_KEY}. Implementation: src/nomad/common/env.py.

Nomad server config¶

nomad serve reads a YAML or JSON file into nomad.config.ServerConfig.

tool_manager:
  enabled: true
  idle_seconds: 120
  gc_idle_seconds: 300
  disk_idle_seconds: 600
  max_pending_per_tool: 50000
search_tool:
  expose: true
telemetry:
  enabled: true
  service_name: nomad
  otlp_endpoint: http://127.0.0.1:4317
tools:
  - my_package.tools.health_check
fmod_models:
  - model_class: my_package.models.MyTorchTool
    name_or_path: my-org/my-model
    tool_name: my-model
    batch_size: 16

Use tools for regular Python callables and fmod_models for nomad.fm_base_tool.TorchModuleTool implementations. name_or_path can point at several model source types:

Name	Example
Local directory URI	`file:models/my-model`
Hugging Face URI	`hf://my-org/my-model`
ORAS artifact	`oras://registry.example.org/my-org/my-model:v1`
Git/Git LFS HTTPS URI	`git+https://example.org/my-org/models.git@main`
Git/Git LFS SSH URI	`git+ssh://git@example.org/my-org/models.git@main`
Local path[1]	`models/my-model`
Hugging Face repo ID[1]	`my-org/my-model`
Plain HTTPS Git URL[2]	`https://example.org/my-org/models.git@main`
SCP-style Git URL[2]	`git@example.org:my-org/models.git@main`

Add #path/to/dir to any source when the model files live in a subdirectory, for example hf://my-org/my-model#weights or git+https://example.org/my-org/models.git@main#weights.

nomad serve emits OpenTelemetry metrics for model-serving operations when OTel export is enabled. See OpenTelemetry for telemetry setup and metric reference tables.

Code-mode gateway config¶

nomad code-mode and nomad code-mode-exec read YAML, TOML, or JSON into nomad.gateway.config.GatewayConfig.

servers:
  nomad:
    transport: streamable_http
    url: http://127.0.0.1:8181/mcp
defaults:
  timeout_seconds: 60
  stdout_limit: 65536
  stderr_limit: 65536
  result_limit: 65536
telemetry:
  enabled: true
  service_name: nomad-gateway
  otlp_endpoint: http://127.0.0.1:4317

transport is stdio or streamable_http in gateway config files. The workspace_root default controls where sandboxed scripts run. If that workspace contains .venv/bin/python or .venv/Scripts/python.exe, the gateway uses it for sandbox execution.

The gateway emits OpenTelemetry metrics and spans for MCP tool entrypoints, sandbox runs, and upstream MCP tool calls. See OpenTelemetry for the full metric reference.

Nomad configures OTLP/gRPC trace and metric exporters when telemetry.enabled is true, NOMAD_OTEL_ENABLED=true, or standard OTel environment variables such as OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, OTEL_TRACES_EXPORTER, or OTEL_METRICS_EXPORTER are set. Set OTEL_SDK_DISABLED=true to disable SDK setup. Install nomad[otel] to include the optional OTel SDK and OTLP exporter dependencies. See OpenTelemetry for links to OTel exporter documentation.

Middleware¶

Gateway middleware is configured with the middleware list on nomad.gateway.config.GatewayConfig.

middleware:
  - kind: allowlist
    allow:
      - nomad:*
    deny:
      - nomad:dangerous_*
  - kind: redaction
    mode: basic
  - kind: logging
    level: info

Allowlist patterns match server:tool. Redaction currently supports basic and none.