# Class LittleGhost::Configuration

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Configuration.html

Configure shared services and lookup rules before agents start. A
configuration collects model profiles, persistence, paths, instrumentation,
and runtime hooks for an application.

    LittleGhost.configure do |config|
      config.default_model :customer_support
      config.service_name "support-api"
    end

    LittleGhost.configuration.default_model # => "customer_support"
    LittleGhost.configuration.service_name  # => "support-api"

Prompt and skill lookup paths default to `app/prompts` and
`app/skills` under the application root. Applications may append
shared roots or replace the arrays entirely.

Configuration is a mutable application builder until its shared Runtime is
first used. A successful #runtime call locks the builder so standalone Agents
and Assemblies keep one stable setup. Configure the application before its
first entrypoint call. Explicit Runtime construction remains an advanced way
to take an independent snapshot without selecting the shared default.

Multi-tenant applications should derive Session actor identity from state
established after authentication, not from an unverified request field.

## Inheritance

`LittleGhost::Configuration < Object`

## Class methods

<a id="method-c-new"></a>
### `.new`

```ruby
.new(values = {})
```

Starts a mutable builder with optional `values`.

Prompt paths default to `app/prompts` and skill paths to
`app/skills`. Collection settings are copied so callers can safely
reuse their input arrays after construction.

## Instance methods

<a id="method-i-5B-5D"></a>
### `#[]`

```ruby
#[](name)
```

Looks up an arbitrary setting by symbol or string-compatible name.

<a id="method-i-5B-5D-3D"></a>
### `#[]=`

```ruby
#[]=(name, value)
```

Adds or replaces an arbitrary setting.

<a id="method-i-artifacts"></a>
### `#artifacts`

```ruby
artifacts() -> Class<Runtime::Hook>
artifacts { |artifact, run:| bytes_or_artifact_or_nil } -> Class<Runtime::Hook>
```

Stores input attachments, Tool artifacts, and oversized successful Tool values
under the conventional `:artifacts` Workspace path. An optional
block receives deferred Artifacts and may load their bytes for the current
Run. It may return a String, an inline Artifact, or nil.

The block is application code. It must authorize each reference using identity
established by the application and limit any file or network read before
returning bytes. LittleGhost applies its storage limits afterward.

<a id="method-i-blocking_pool_capacity"></a>
### `#blocking_pool_capacity`

```ruby
blocking_pool_capacity() -> integer
blocking_pool_capacity(value) -> integer
```

Returns or sets the maximum number of process-wide workers available to
LittleGhost.offload_blocking, certificate generation, and Filesystem
SessionStore transactions when they run from scheduled fibers. Workers are
created lazily. The default is 2. Every Configuration reads and writes the
same process-wide value.

Configure this during process startup, before any operation can start the
pool. `value` must be a positive Integer. Raises ArgumentError for an invalid
value and ConfigurationError when changing the value after the pool has
started.

<a id="method-i-blocking_pool_capacity-3D"></a>
### `#blocking_pool_capacity=`

```ruby
#blocking_pool_capacity=(value)
```

Sets the same process-wide worker limit as `blocking_pool_capacity`.

<a id="method-i-catalog_source"></a>
### `#catalog_source`

```ruby
#catalog_source(source)
```

Adds an explicit catalog source. Sources refresh only when callers invoke
ModelResolver#refresh!.

<a id="method-i-code_mode"></a>
### `#code_mode`

```ruby
#code_mode()
```

Default code-mode declaration for enabled Agents. The Hash may select an
`:engine` and `:sandbox`, override `:limits`,
and name Tools to keep in the conversation with `:except`.

<a id="method-i-code_mode-3D"></a>
### `#code_mode=`

```ruby
#code_mode=(value)
```

Configures application defaults for code-mode Agents. The Hash may select an
`:engine` and `:sandbox`, override `:limits`,
and name ordinary Tools that remain in the conversation with
`:except`.

<a id="method-i-concurrency_backend"></a>
### `#concurrency_backend`

```ruby
concurrency_backend() -> :auto, :thread, :fiber
concurrency_backend(value) -> :auto, :thread, :fiber
```

Selects how subsequently built runtimes start independent work such as
parallel Tool calls and Workflow branches.

The default, `:auto`, uses fibers when the caller is already
running in a scheduled fiber and uses threads otherwise. `:thread`
always uses threads. `:fiber` raises ConfigurationError when the
caller is not in a scheduled fiber. The application's scheduler must support
Fiber.schedule. Any other value raises ArgumentError.

    LittleGhost.configure do |config|
      config.concurrency_backend = :thread
    end

<a id="method-i-concurrency_backend-3D"></a>
### `#concurrency_backend=`

```ruby
#concurrency_backend=(value)
```

Replaces the concurrency backend for subsequently built runtimes.

<a id="method-i-configure"></a>
### `#configure`

```ruby
#configure()
```

Yields this builder for setup and returns the same instance.

<a id="method-i-default_model"></a>
### `#default_model`

```ruby
#default_model(value = :__read__)
```

Fallback logical role for the default resolver.

<a id="method-i-default_model-3D"></a>
### `#default_model=`

```ruby
#default_model=(value)
```

Replaces the fallback logical role and normalizes it to a String.

<a id="method-i-instrument"></a>
### `#instrument`

```ruby
#instrument(subscriber)
```

Adds an Instrumentation::Subscriber to each new runtime and returns it.

<a id="method-i-invocation"></a>
### `#invocation`

```ruby
invocation() -> value
invocation(value) -> value
```

The request envelope class used to parse application payloads.

<a id="method-i-invocation-3D"></a>
### `#invocation=`

```ruby
invocation=(value) -> value
```

Replaces the request envelope class for subsequently built runtimes.

<a id="method-i-log_events_to"></a>
### `#log_events_to`

```ruby
log_events_to() -> :stdout, :stderr, nil
log_events_to(destination) -> destination
```

Sends structured framework events to `:stdout` or
`:stderr`. This setting controls the process-wide Events console
destination; the most recent setting replaces it without changing other event
listeners. By default, events have no console destination. Passing `nil`
disables console output. The console listener redacts sensitive values and
writes one JSON object per line.

<a id="method-i-log_events_to-3D"></a>
### `#log_events_to=`

```ruby
#log_events_to=(destination)
```

Replaces the console destination for structured framework events.

<a id="method-i-model_resolver"></a>
### `#model_resolver`

```ruby
#model_resolver(value = :__read__)
```

Installs a complete resolver override for subsequently built runtimes.

<a id="method-i-model_resolver-3D"></a>
### `#model_resolver=`

```ruby
model_resolver=(value) -> value
```

Replaces the model resolver declaration for subsequently built runtimes.

<a id="method-i-models"></a>
### `#models`

```ruby
#models(value = :__read__)
```

Logical model profiles for the default resolver. Role names cannot contain a
colon because that syntax identifies a canonical model target.

<a id="method-i-models-3D"></a>
### `#models=`

```ruby
#models=(value)
```

Replaces logical model profiles for subsequently built runtimes.

<a id="method-i-models_path"></a>
### `#models_path`

```ruby
#models_path(value = :__read__)
```

Model YAML path. The conventional path is optional; an explicitly set path
must exist when a runtime is built.

<a id="method-i-models_path-3D"></a>
### `#models_path=`

```ruby
#models_path=(value)
```

Replaces the model YAML path for subsequently built runtimes.

<a id="method-i-prompt_paths"></a>
### `#prompt_paths`

```ruby
#prompt_paths()
```

Prompt lookup paths in precedence order. The Array is mutable until the shared
Runtime is built.

<a id="method-i-prompt_paths-3D"></a>
### `#prompt_paths=`

```ruby
#prompt_paths=(value)
```

Replaces prompt lookup paths with `value` converted to an Array.

<a id="method-i-provider_adapter"></a>
### `#provider_adapter`

```ruby
#provider_adapter(name, callable = nil, &factory)
```

Registers a provider adapter factory under `name`.

<a id="method-i-provider_credentials"></a>
### `#provider_credentials`

```ruby
#provider_credentials(callable = nil, &resolver)
```

Installs a trusted callable that returns credential options for a named
provider connection when each executable model is constructed.

<a id="method-i-providers"></a>
### `#providers`

```ruby
#providers(value = :__read__)
```

Trusted provider connections for the default or custom resolver.

<a id="method-i-providers-3D"></a>
### `#providers=`

```ruby
#providers=(value)
```

Replaces trusted provider connections for subsequently built runtimes.

<a id="method-i-providers_path"></a>
### `#providers_path`

```ruby
#providers_path(value = :__read__)
```

Provider YAML path. The conventional path is optional; an explicitly set path
must exist when a runtime is built.

<a id="method-i-providers_path-3D"></a>
### `#providers_path=`

```ruby
#providers_path=(value)
```

Replaces the provider YAML path for subsequently built runtimes.

<a id="method-i-root"></a>
### `#root`

```ruby
root() -> Pathname
root(path) -> Pathname
```

The resolved application root, defaulting to `Dir.pwd`.

Setting or reading an invalid root raises ConfigurationError. Symlinks are
resolved so runtimes and lookup paths use the same canonical directory.

<a id="method-i-root-3D"></a>
### `#root=`

```ruby
#root=(value)
```

Replaces the application root after resolving it to a stable real path.

<a id="method-i-runtime"></a>
### `#runtime`

```ruby
#runtime()
```

Returns the shared Runtime for this configuration, building it on first use.
Once construction succeeds, the configuration is locked so every standalone
entrypoint continues to use one stable application setup. The conventional
configuration file may finish loading during construction; other writes are
rejected. A failed build leaves the configuration editable for a later
attempt.

<a id="method-i-runtime_hook"></a>
### `#runtime_hook`

```ruby
#runtime_hook(hook_class)
```

Adds a Runtime::Hook subclass to each new runtime and returns it.

<a id="method-i-sandbox"></a>
### `#sandbox`

```ruby
#sandbox()
```

Sandbox declaration used for subsequently built runtimes.

<a id="method-i-sandbox-3D"></a>
### `#sandbox=`

```ruby
#sandbox=(value)
```

Selects the Sandbox provider instantiated around each run's workspace.
LittleGhost does not fall back to unrestricted execution when an explicit
backend is unavailable.

<a id="method-i-service_name"></a>
### `#service_name`

```ruby
service_name() -> value
service_name(value) -> value
```

The low-cardinality service name attached to instrumentation.

<a id="method-i-service_name-3D"></a>
### `#service_name=`

```ruby
service_name=(value) -> value
```

Replaces the service name attached to telemetry from new runtimes.

<a id="method-i-session_actor"></a>
### `#session_actor`

```ruby
session_actor() -> callable, nil
session_actor(callable) -> callable
session_actor { |invocation| ... } -> callable
```

The callable that derives the persistence actor for each invocation.

Pass either a callable or a block. The configured resolver should use trusted
authenticated identity in multi-tenant applications.

<a id="method-i-session_store"></a>
### `#session_store`

```ruby
#session_store()
```

Session-store declaration used for subsequently built runtimes.

<a id="method-i-session_store-3D"></a>
### `#session_store=`

```ruby
#session_store=(value)
```

Selects session persistence with a `:provider` and its constructor
options.

The provider must be a SessionStore subclass. Runtime construction creates and
owns the store instance.

<a id="method-i-skill_paths"></a>
### `#skill_paths`

```ruby
#skill_paths()
```

Skill lookup paths in precedence order. The Array is mutable until the shared
Runtime is built.

<a id="method-i-skill_paths-3D"></a>
### `#skill_paths=`

```ruby
#skill_paths=(value)
```

Replaces skill lookup paths with `value` converted to an Array.

<a id="method-i-skill_resource_root"></a>
### `#skill_resource_root`

```ruby
#skill_resource_root()
```

Optional model-facing root used for skill locations and resources. The value
may be an absolute process-visible path. A `workspace://name`
reference must map to the configured skill path through a read-only file grant
in each Run's Workspace and Sandbox. The application must not expose the same
files through another writable bind mount.

<a id="method-i-skill_resource_root-3D"></a>
### `#skill_resource_root=`

```ruby
#skill_resource_root=(value)
```

Replaces and validates the skill resource root for new runtimes.

<a id="method-i-workspace"></a>
### `#workspace`

```ruby
#workspace()
```

Workspace declaration used for subsequently built runtimes.

<a id="method-i-workspace-3D"></a>
### `#workspace=`

```ruby
#workspace=(value)
```

Selects the Workspace provider instantiated for each run. A declaration may be
a registered provider symbol, callable, or a Hash containing a
`:provider` and constructor options.