class LittleGhost::Runtime

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 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.