NOCFoundry Docs

Local Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Local Quickstart

This quickstart gets a local NOCFoundry instance running with the validation demo and UI.

Prerequisites

Go 1.25 or later
Docker if you want the local Keycloak flow
a shell with access to this repository

Optional: start the local SR Linux topology

If you want to test against a realistic network fabric instead of static examples, use the containerlab topology in examples/containerlab/.

Install containerlab only when you need it:

MCP Client Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

MCP Client Quickstart

NOCFoundry exposes the Model Context Protocol at:

http://127.0.0.1:5000/mcp

With the protected validation example, /mcp is protected by OIDC endpoint auth.

What clients need

the MCP endpoint URL
an access token whose aud matches the configured /mcp audience
support for bearer tokens on HTTP-based MCP transports

The protected resource metadata is served from:

/.well-known/oauth-protected-resource/mcp

Minimal connection model

Start NOCFoundry with examples/tools-configs/keycloak-protected-validation.yaml and examples/server-configs/protected-api-mcp-ui.yaml.
Obtain an access token from Keycloak.
Configure your MCP client to connect to http://127.0.0.1:5000/mcp.
Supply Authorization: Bearer <token> on every HTTP request.

Audience reminder

The access token must match the /mcp audience configured in:

Tool Catalogs

Mon, 01 Jan 0001 00:00:00 +0000

Tool Catalogs

Tool catalogs define the operational resources NOCFoundry loads at startup.

Supported catalog flags

--tools-file
--tools-files
--tools-folder
--prebuilt

These are mutually exclusive where appropriate:

--tools-file, --tools-files, and --tools-folder cannot be combined
--prebuilt can be combined with custom tool catalogs when you want bundled capabilities plus your own configs

What a catalog can contain

Tool catalogs can define:

sources
device groups
auth services
tools
toolsets
prompts
promptsets
embedding models

Prebuilt catalogs

--prebuilt takes a bundled catalog name, not an individual tool name.

Server Config

Mon, 01 Jan 0001 00:00:00 +0000

Server Config

--server-config carries server-wide runtime policy that should not be owned by individual tool catalog files.

Current focus

Today, the most important server config capabilities are:

endpoint auth for /api
endpoint auth for /mcp
browser UI auth configuration for PKCE login

Example

auth:
 endpointAuth:
 api:
 enabled: true
 authServices: ["noc-keycloak"]
 audience: ${NOCFOUNDRY_BASE_URL:http://127.0.0.1:5000}/api
 mcp:
 enabled: true
 authServices: ["noc-keycloak"]
 audience: ${NOCFOUNDRY_BASE_URL:http://127.0.0.1:5000}/mcp
 ui:
 enabled: true
 authService: noc-keycloak
 clientId: ${KEYCLOAK_UI_CLIENT_ID:noc-foundry-ui}
 scopes: ["openid", "profile", "email"]
 redirectPath: /ui/auth/callback

Rules to remember

endpoint auth policy is global to the server, not per tool catalog
auth services are still defined in tool catalogs and referenced here by name
UI login depends on API endpoint auth being enabled

Start command

./nocfoundry \
 --tools-file examples/tools-configs/keycloak-protected-validation.yaml \
 --server-config examples/server-configs/protected-api-mcp-ui.yaml \
 --validation-config examples/validation-runtime-configs/durable-validation-sqlite.yaml \
 --ui

Validation Runtime

Mon, 01 Jan 0001 00:00:00 +0000

Validation Runtime

--validation-config controls how validation runs are executed and stored.

Key runtime settings

executionBackend
storeBackend
sqlitePath
durableTaskSQLitePath
maxConcurrentRuns
maxConcurrentSteps
resultRetention
eventRetention

Example

executionBackend: durabletask
storeBackend: sqlite
sqlitePath: /var/lib/nocfoundry/noc-foundry-validation-runs.sqlite
durableTaskSQLitePath: /var/lib/nocfoundry/noc-foundry-validation-taskhub.sqlite
maxConcurrentRuns: 4
maxConcurrentSteps: 4
resultRetention: 24h
eventRetention: 24h

Backend choices

local is simpler and good for lightweight execution
durabletask is better for long-running validations that should survive interruption

Store choices

memory is ephemeral
sqlite provides persistence for status, results, and events

Recommended local lab setup

For the protected validation example, use:

OIDC Endpoint Auth

Mon, 01 Jan 0001 00:00:00 +0000

OIDC Endpoint Auth

NOCFoundry can protect the HTTP surfaces themselves, not just individual tool calls.

Protected surfaces

/api
/mcp

These surfaces are configured separately in --server-config and can require different audiences.

Auth service model

OIDC providers are defined as authServices in tool catalog files
the server config references those services by name
only auth services selected by server policy can satisfy a protected surface

Metadata and RFC 9728

NOCFoundry serves protected resource metadata for:

UI Login with Keycloak

Mon, 01 Jan 0001 00:00:00 +0000

NOCFoundry’s browser UI acts as an OIDC public client and uses Authorization Code + PKCE to access the protected /api surface.

Local demo flow

Start Keycloak:

docker compose -f examples/keycloak/docker-compose.keycloak.yaml up -d

Bootstrap the demo realm and clients:

./examples/keycloak/keycloak-setup.sh

Start NOCFoundry with:

Important client details

The setup script creates:

noc-foundry for the resource-side auth service
noc-foundry-ui for the browser PKCE client

The UI client must:

Validation Runs

Mon, 01 Jan 0001 00:00:00 +0000

Validation Runs

Validation runs provide a long-running execution model for multi-step network validation workflows.

Typical lifecycle:

start a run
poll status
fetch final result
cancel if needed

Use the protected validation example tools for this workflow:

start_validation_run
validation_run_status
validation_run_result
cancel_validation_run

Skills

Mon, 01 Jan 0001 00:00:00 +0000

Skills

NOCFoundry can generate agent-facing workflow bundles with skills-generate.

The current model emphasizes:

one skill per explicit toolset
workflow-oriented docs
optional prompt guidance
direct nocfoundry invoke ... examples instead of generated runtime wrappers

SSH Source

Mon, 01 Jan 0001 00:00:00 +0000

SSH Source

Use the SSH source for CLI-oriented collection and command execution. In NOCFoundry, SSH timeouts are normalized as full operation timeouts per attempt.

NETCONF Source

Mon, 01 Jan 0001 00:00:00 +0000

NETCONF Source

Use the NETCONF source for structured operational retrieval and config reads, with operation-scoped timeout behavior and retry-aware collection.

gNMI Source

Mon, 01 Jan 0001 00:00:00 +0000

gNMI Source

Use the gNMI source for structured operational state retrieval with source-level timeout control and audience-safe tool workflows.

HTTP Source

Mon, 01 Jan 0001 00:00:00 +0000

HTTP Source

Use the HTTP source for adjacent operational systems and service APIs that need to participate in workflows alongside device-facing tools.

Nokia Validate

Mon, 01 Jan 0001 00:00:00 +0000

`nokia-validate`

nokia-validate is a read-only validation tool for Nokia devices and blast-radius checks. It collects evidence from one or more devices, evaluates configured assertions, and returns structured pass/fail results for a selected phase such as pre, during, or post.

This tool is intentionally not a change engine. Agents and operators should use it as a deterministic validation primitive inside a larger maintenance workflow.

What it is good for

pre-change readiness validation
post-change verification
blast-radius checks across multiple devices
structured result collection for async validation runs

Key behavior

supports either a single source or a fleet-oriented sourceSelector
runs ordered phases made up of collect and assert steps
uses protocol-aware transport selection for network retrieval
returns structured evidence, step status, and overall validation outcomes
integrates with durable validation runs through the validation_run_* lifecycle tools

Runtime parameters

phase: required when more than one phase is defined
device: optional when sourceSelector is used and you want to narrow execution

Example operator flow

run the pre phase before maintenance
perform the network change outside the tool
run the post phase
compare results and decide whether rollback is required

Example configuration

kind: tools
name: maintenance_validation
type: nokia-validate
authRequired:
 - noc-keycloak
sourceSelector:
 matchLabels:
 validation_demo: "true"
phases:
 - name: pre
 steps:
 - name: collect_control_version
 collect:
 into: control_versions
 targets: ["control_plane"]
 operation: get_system_version
 - name: assert_versions
 assert:
 name: expected_version
 from: ["control_versions"]
 scope: per_record
 expr: '.payload.software_version == "23.10.R1"'

CLI Reference

Mon, 01 Jan 0001 00:00:00 +0000

CLI Reference

The root command is:

nocfoundry

Core entry points include:

nocfoundry invoke
nocfoundry skills-generate
nocfoundry --ui

Prebuilt catalogs

The --prebuilt flag loads a bundled tool catalog by name.

Current bundled prebuilt:

validation-runs

Example:

./nocfoundry --prebuilt validation-runs

--prebuilt is not a boolean flag, and it does not take an individual tool name. This is invalid:

./nocfoundry --prebuilt start_validation_run

because start_validation_run is a tool inside the validation-runs catalog, not the catalog name itself.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

FAQ

Does NOCFoundry execute prompts itself?

No. Prompt resources are exposed for clients and agents to consume. NOCFoundry does not execute prompts against an LLM.

Why is `/api` returning 401?

If endpoint auth is enabled, callers must present a bearer token that matches the configured /api audience.

The UI shell can remain public while its backing /api calls are protected. When UI auth is enabled, the browser signs in through OIDC + PKCE.

Local Lab with Keycloak

Mon, 01 Jan 0001 00:00:00 +0000

Local Lab with Keycloak

Use this protected local lab stack when you want to test:

Keycloak-backed OIDC auth services
endpoint auth on /api and /mcp
browser PKCE login for the UI
durable validation runs

Main files:

For contributors who want a realistic local network instead of static sample targets, pair this protected stack with the SR Linux containerlab fabric.

install containerlab on demand with ./examples/containerlab/install-containerlab.sh
deploy the lab with sudo containerlab deploy -t examples/containerlab/noc-foundry-lab.clab.yaml
destroy it with sudo containerlab destroy -t examples/containerlab/noc-foundry-lab.clab.yaml

Start Keycloak

Start the local Keycloak example:

Containerlab SR Linux Lab

Mon, 01 Jan 0001 00:00:00 +0000

Containerlab SR Linux Lab

Use this example when you want a realistic local network topology for NOCFoundry development and validation testing.

Main files:

Topology

This lab deploys:

2 SR Linux spines: srl-b, srl-c
3 SR Linux leaves: srl-a, srl-d, srl-e

Each node is configured with:

ISIS on the underlay links
a loopback address on system0
NETCONF enabled on the management plane
native SR Linux gNMI enabled on the management plane

The lab also uses a dedicated management network:

NOCFoundry Docs

Local Quickstart

Local Quickstart

Prerequisites

Optional: start the local SR Linux topology

MCP Client Quickstart

MCP Client Quickstart

What clients need

Minimal connection model

Audience reminder

Tool Catalogs

Tool Catalogs

Supported catalog flags

What a catalog can contain

Prebuilt catalogs

Server Config

Server Config

Current focus

Example

Rules to remember

Start command

Validation Runtime

Validation Runtime

Key runtime settings

Example

Backend choices

Store choices

Recommended local lab setup

OIDC Endpoint Auth

OIDC Endpoint Auth

Protected surfaces

Auth service model

Metadata and RFC 9728

UI Login with Keycloak

UI Login with Keycloak

Local demo flow

Important client details

Validation Runs

Validation Runs

Skills

Skills

SSH Source

SSH Source

NETCONF Source

NETCONF Source

gNMI Source

gNMI Source

HTTP Source

HTTP Source

Nokia Validate

nokia-validate

What it is good for

Key behavior

Runtime parameters

Example operator flow

Example configuration

Related examples

CLI Reference

CLI Reference

Prebuilt catalogs

FAQ

FAQ

Does NOCFoundry execute prompts itself?

Why is /api returning 401?

Does the UI require login?

Local Lab with Keycloak

Local Lab with Keycloak

Start Keycloak

Containerlab SR Linux Lab

Containerlab SR Linux Lab

Topology

`nokia-validate`

Why is `/api` returning 401?