---
title: Configuration
description: Options and defaults for the Shield engine and Forge extension.
---

## Engine configuration

`shield.Config` holds global defaults for the safety engine:

```go
type Config struct {
    DefaultProfile     string        // safety profile to use when none specified
    ShutdownTimeout    time.Duration // graceful shutdown timeout (default: 30s)
    ScanConcurrency    int           // max parallel scans (default: 10)
    EnableShortCircuit bool          // skip deeper layers on block (default: true)
}
```

### Defaults

```go
shield.DefaultConfig() // returns:
// Config{
//     ShutdownTimeout:    30 * time.Second,
//     ScanConcurrency:    10,
//     EnableShortCircuit: true,
// }
```

### Overriding defaults

Pass a custom config via engine options:

```go
eng, err := engine.New(
    engine.WithConfig(shield.Config{
        DefaultProfile:     "strict",
        ScanConcurrency:    20,
        EnableShortCircuit: true,
    }),
    engine.WithStore(pgStore),
)
```

## Engine options

| Option | Description |
|--------|-------------|
| `engine.WithStore(s)` | Sets the composite store |
| `engine.WithConfig(cfg)` | Sets the engine configuration |
| `engine.WithPlugin(p)` | Registers a lifecycle plugin |
| `engine.WithLogger(l)` | Sets the structured logger |

## Top-level Shield options

The root `shield` package provides options for composing safety primitives inline:

```go
type Options struct {
    Config     Config
    Profile    string     // default safety profile name
    Instincts  []string   // inline instinct names
    Awareness  []string   // inline awareness detector names
    Values     []string   // inline value names
    Boundaries []string   // inline boundary names
    Judgments  []string   // inline judgment names
    Reflexes   []string   // inline reflex names
}
```

| Option | Description |
|--------|-------------|
| `shield.WithConfig(cfg)` | Sets the Shield configuration |
| `shield.WithProfile(name)` | Sets the default safety profile |
| `shield.WithInstincts(names...)` | Adds inline instinct names |
| `shield.WithAwareness(names...)` | Adds inline awareness detector names |
| `shield.WithValues(names...)` | Adds inline value names |
| `shield.WithBoundaries(names...)` | Adds inline boundary names |
| `shield.WithJudgments(names...)` | Adds inline judgment names |
| `shield.WithReflexes(names...)` | Adds inline reflex names |

## Forge extension options

The `extension.New` function accepts its own set of options:

```go
ext := extension.New(
    extension.WithStore(pgStore),
    extension.WithPlugin(metricsPlugin),
    extension.WithDisableRoutes(),
    extension.WithDisableMigrate(),
    extension.WithBasePath("/shield"),
    extension.WithGroveDatabase(""),
)
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `WithStore(s)` | `store.Store` | -- | Composite store (auto-resolved from grove if not set). |
| `WithPlugin(p)` | `plugin.Plugin` | -- | Lifecycle plugin (repeatable). |
| `WithEngineOption(opt)` | `engine.Option` | -- | Pass-through engine option. |
| `WithConfig(cfg)` | `Config` | defaults | Full config struct. |
| `WithDisableRoutes()` | -- | `false` | Skip HTTP route registration. |
| `WithDisableMigrate()` | -- | `false` | Skip migrations on Start. |
| `WithBasePath(path)` | `string` | `""` | URL prefix for shield routes. |
| `WithGroveDatabase(name)` | `string` | `""` | Named grove.DB to resolve from DI. |
| `WithRequireConfig(b)` | `bool` | `false` | Require config in YAML files. |

## File-based configuration (YAML)

When running as a Forge extension, Shield automatically loads configuration from YAML config files. The extension looks for config under the following keys (in order):

1. `extensions.shield` -- standard Forge extension config namespace
2. `shield` -- top-level shorthand

### Example

```yaml
# forge.yaml
extensions:
  shield:
    disable_routes: false
    disable_migrate: false
    base_path: "/shield"
    default_profile: ""
    shutdown_timeout: "30s"
    scan_concurrency: 10
    enable_short_circuit: true
    grove_database: ""
```

### Config fields

| YAML Key | Type | Default | Description |
|----------|------|---------|-------------|
| `disable_routes` | `bool` | `false` | Skip HTTP route registration |
| `disable_migrate` | `bool` | `false` | Skip migrations on Start |
| `base_path` | `string` | `""` | URL prefix for all routes |
| `default_profile` | `string` | `""` | Safety profile when none specified |
| `shutdown_timeout` | `duration` | `"30s"` | Max graceful shutdown wait |
| `scan_concurrency` | `int` | `10` | Max parallel scan operations |
| `enable_short_circuit` | `bool` | `true` | Skip deeper layers on block decision |
| `grove_database` | `string` | `""` | Named grove.DB from DI |

### Merge behaviour

File-based configuration is merged with programmatic options. Programmatic boolean flags (`DisableRoutes`, `DisableMigrate`) always win when set to `true`. For other fields, YAML values take precedence, then programmatic values, then defaults.