# Class LittleGhost::Runtime

Documentation version: Edge

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

Owns the shared services that assemblies reuse across many Runs.

Most applications do not construct this class. Configure LittleGhost once and
call a named Agent or Assembly; the first standalone call lazily builds
`LittleGhost.runtime`, and later calls reuse it automatically. Each
call still receives a fresh Run, bound participants, Tools, workspace, and
sandbox.

Construct Runtime directly when one process intentionally hosts an isolated
LittleGhost setup:

    configuration = LittleGhost::Configuration.new(
      root: Dir.pwd,
      providers: {
        openrouter: {adapter: :openrouter, api_key: ENV.fetch("OPENROUTER_API_KEY")}
      },
      models: {customer_support: {target: "openrouter:openai/gpt-5.6-luna"}},
      default_model: :customer_support,
      service_name: "support-api"
    )
    runtime = LittleGhost::Runtime.new(configuration: configuration)

    CustomerSupportAgent.new(runtime: runtime)
      .ask("Where is order 481?")
      .response

Explicit construction snapshots the supplied Configuration but does not
replace LittleGhost's shared default Runtime.

A Runtime may build independent Runs concurrently. Each Run gets fresh
participants and Tools. By default, it also gets a Runtime-created Workspace
and Sandbox that the Run owns. Instances supplied by the application remain
caller-owned.

## Advanced construction and ownership

Normal construction reads the application's configured definitions and builds
shared model resolution, persistence, hooks, and resource factories. The
`settings` form and #build are lower-level extension points for deriving
another Runtime from an existing configuration snapshot.

#build_run creates a workspace and sandbox when needed. Once the Run owns
them, it closes them; if construction stops halfway through, Runtime closes
the partial resources. Startup failures are reported to instrumentation and
then raised. Session actor resolution must use authenticated application
identity. The default Sandboxes::Unrestricted uses host permissions and is not
a security boundary for untrusted work.

Shared stores, resolvers, hooks, subscribers, providers, and resource
factories may receive concurrent calls. Calls can overlap on different
threads, or fibers can take turns entering the same object on one thread.
Extensions must protect shared mutable state without relying on thread
identity. One SessionStore instance serializes calls for the same Session. A
store must provide its own coordination across processes.

See [Running in Production](../production.md) for choosing a
concurrency backend and protecting shared extensions.

Runtime has no shutdown operation. Runs close resources created for their
request. The application shuts down shared services and process-wide
Instrumentation subscribers with the rest of the process.

## Inheritance

`LittleGhost::Runtime < Object`

## Attributes

<a id="attribute-i-code_mode_configuration"></a>
### `code_mode_configuration` (R)

Default code-mode declaration for enabled agents.

<a id="attribute-i-configuration"></a>
### `configuration` (R)

Configuration object used to construct this Runtime.

<a id="attribute-i-loader"></a>
### `loader` (R)

Loader used for conventional application definitions.

<a id="attribute-i-model_resolver"></a>
### `model_resolver` (R)

Resolver that turns model roles and targets into executable Models.

<a id="attribute-i-prompt_paths"></a>
### `prompt_paths` (R)

Ordered directories searched for prompt templates.

<a id="attribute-i-root"></a>
### `root` (R)

Canonical application root.

<a id="attribute-i-runtime_hooks"></a>
### `runtime_hooks` (R)

Runtime hooks called around request and session preparation.

<a id="attribute-i-sandbox_declaration"></a>
### `sandbox_declaration` (R)

Configured Sandbox provider symbol, callable, or declaration.

<a id="attribute-i-session_store"></a>
### `session_store` (R)

Shared store used to open per-Run Sessions.

<a id="attribute-i-settings"></a>
### `settings` (R)

Settings snapshot used by new Runs.

<a id="attribute-i-skill_paths"></a>
### `skill_paths` (R)

Ordered directories searched for skill definitions.

<a id="attribute-i-skill_resource_root"></a>
### `skill_resource_root` (R)

Root used for skill-owned resources, when configured.

<a id="attribute-i-workspace_declaration"></a>
### `workspace_declaration` (R)

Configured Workspace provider symbol, callable, or declaration.

## Class methods

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

```ruby
.new(configuration:, settings: nil)
```

Starts a runtime from `configuration` or an existing settings snapshot.

## Instance methods

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

```ruby
#build(**overrides)
```

Creates a sibling runtime with explicit setting overrides.

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

```ruby
#build_run(payload,
      agent_class: nil,
      assembly_class: nil,
      entrypoint_class: nil,
      execution_class: nil,
      cancellation_token: Support::CancellationToken.new,
      workspace: nil,
      sandbox: nil,
      include_agent_events_by_default: false)
```

Creates a Run that owns any workspace and sandbox built for the request.

`include_agent_events_by_default` is trusted stream policy for the Run
returned by this build. It applies only when the Invocation omits
`include_agent_events` and must not be forwarded to auxiliary Runs built while
preparing the request.

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

```ruby
#build_sandbox(workspace:, invocation: nil)
```

Instantiates the configured sandbox around `workspace`, or an unrestricted
sandbox by default.

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

```ruby
#build_workspace(invocation: nil)
```

Instantiates the configured workspace, or a root-scoped Workspace by default.

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

```ruby
embed(model:, inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil) -> Embeddings::Response
```

Embeds text through this Runtime's model resolver.

Returns an Embeddings::Response without creating a Run or invoking runtime
hooks. See LittleGhost.embed for the operation contract.

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

```ruby
generate(model:, messages:, result_schema: nil, settings: {}, structured_result_repair_attempts: 1, cancellation_token: Support::CancellationToken.new, deadline: nil) -> RunResult
```

Generates one response through this Runtime's model resolver.

Returns a RunResult without creating a Run or invoking runtime hooks. See
LittleGhost.generate for the operation contract.

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

```ruby
#parse(payload)
```

Coerces an application payload into the configured Invocation class.