---
sidebar_label: Scope configurations
toc_max_heading_level: 3
doc_id: a1c3e8f4-6b2d-4a91-9e57-3d8f0c7b5a12
description: >-
  Configure agent-backed scopes from the UI using providers, with support for
  inheritance, per-environment settings, and a clear resolution hierarchy.
keywords:
  - scope configurations
  - providers
  - agent-backed scopes
  - kubernetes
  - configuration
  - values.yaml
---

# Scope configurations

Scope configurations let you **define settings like Kubernetes namespace**, **domain**, **deployment strategy**, and **security options** directly from the nullplatform UI, using the same provider you already use for cloud credentials and integrations. 

Apply them at any level (organization, account, namespace, or individual scope). Set a base domain for the whole organization and override just the namespace per account, without duplicating configuration or managing multiple agents.

## How configuration is resolved

When the agent processes an action (like creating or deploying a scope), it resolves each configuration value using this priority order:

```mermaid
flowchart TD
    A[Provider configuration] -->|found?| B{Yes}
    B --> C[Use provider value]
    A -->|not found| D[Environment variable]
    D -->|found?| E{Yes}
    E --> F[Use env var value]
    D -->|not found| G[Default value]
    G --> H[Use default]

    style A fill:#2d6a4f,stroke:#40916c,color:#fff
    style D fill:#1b4965,stroke:#5fa8d3,color:#fff
    style G fill:#495057,stroke:#adb5bd,color:#fff
```

1. **Provider configuration** (highest priority) — values set through **Platform settings > Scopes > Configurations** in the UI
2. **Environment variables** — values set on the agent server, in the notification channel, or in `values.yaml`
3. **Default values** — built-in fallback values defined in the scope

Every variable always resolves to a value. If you don't configure it explicitly, the scope uses its default.

:::tip
This feature is fully optional and backward-compatible. Existing setups that rely on environment variables or `values.yaml` continue to work exactly as before.
:::

## Prerequisites

- **Role**: [Ops](/docs/authorization/roles)
- A registered agent-backed scope (for example, the [Containers scope](/docs/agent-backed-scopes/containers))

## Create a scope configuration

1. Go to **Platform settings > Scopes > Configurations**, and click **+ New configuration**.
2. Select **Static files** as the scope provider.
3. Under **Where will this configuration apply?**, choose the target resource. This can be the entire organization, a specific account, a namespace, or an individual scope.
4. Optionally select an **environment** and **dimension values** (like country) to narrow when this configuration applies.
5. Fill in the settings you want to configure across the available tabs.
6. Click **Create configuration**.

The configuration appears in the **Scope configurations** list view. It takes effect immediately for any matching scope actions processed by the agent.


<img alt="Scope configuration" src="/img/scope-configuration.png" width="100%" className="helper-image" />

## Inheritance across levels

To apply different settings at different levels, create multiple configurations. Configurations follow the nullplatform resource hierarchy. A configuration set at a higher level applies to everything below it, unless a more specific one exists:

```mermaid
flowchart TD
    O["Organization<br/><b>domain: example.com</b>"] --> A1["Account A<br/><b>namespace: team-a</b>"]
    O --> A2["Account B<br/>inherits organization config"]
    A1 --> N1["Namespace 1<br/>inherits Account A config"]
    A1 --> N2["Namespace 2<br/><b>namespace: team-a-staging</b>"]

    style O fill:#2d6a4f,stroke:#40916c,color:#fff
    style A1 fill:#1b4965,stroke:#5fa8d3,color:#fff
    style A2 fill:#495057,stroke:#adb5bd,color:#fff
    style N1 fill:#495057,stroke:#adb5bd,color:#fff
    style N2 fill:#1b4965,stroke:#5fa8d3,color:#fff
```

In this example, Account B and Namespace 1 inherit the domain from the organization level. Account A overrides the namespace, and Namespace 2 overrides it again with its own value. For more details on how inheritance works across the resource tree, see the [provider inheritance model](/docs/providers/overview#inheritance-and-overrides).

## Configuration reference

The available variables are organized into categories that match the tabs in the UI: Cluster, Networking, Deployment, Security, and Advanced. Each scope type defines its own set of variables.

For the full list of variables, default values, and descriptions, see the [Kubernetes scope README](https://github.com/nullplatform/scopes/blob/main/k8s/README.md).

## Next steps

- [Configuration-based overrides](/docs/agent-backed-scopes/overrides/configuration): override scope defaults using `values.yaml` in an override repo
- [Providers overview](/docs/providers/overview): learn how provider inheritance and overrides work across the resource hierarchy
- [Containers scope](/docs/agent-backed-scopes/containers): set up the default Kubernetes scope type