awesome-copilot/cookbook/copilot-sdk/dotnet/in-process-runtime.md

# In-Process Runtime

Run the Copilot runtime inside your own process instead of launching a separate Copilot CLI process.

> **Runnable example:** [recipe/in-process-runtime.cs](recipe/in-process-runtime.cs)
>
> ```bash
> dotnet run recipe/in-process-runtime.cs
> ```

## Example scenario

By default, `CopilotClient` launches and manages a separate Copilot CLI child process and talks to
it over stdio or TCP. Some deployments — for example, tightly sandboxed hosts, single-binary
services, or environments where spawning child processes is restricted — need the runtime loaded
directly into the application process instead.

## Using the in-process connection

```csharp
using GitHub.Copilot;

// RuntimeConnection.ForInProcess() is an experimental API (diagnostic GHCP001).
#pragma warning disable GHCP001

var client = new CopilotClient(new CopilotClientOptions
{
    Connection = RuntimeConnection.ForInProcess()
});

await client.StartAsync();

var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "auto",
    OnPermissionRequest = PermissionHandler.ApproveAll
});

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello from the in-process runtime!" });
Console.WriteLine(response?.Data.Content);

await client.StopAsync();
```

`RuntimeConnection.ForInProcess()` is marked `[Experimental("GHCP001")]`, so any code that calls it
must either suppress the diagnostic with `#pragma warning disable GHCP001` (as above) or opt in at
the project level. Everything past client construction — sessions, streaming events, tools, hooks,
and permissions — behaves the same as with the default CLI-launching connection.

## How it works

Instead of spawning a child process, the SDK loads the native Copilot runtime library directly into
your application and communicates with it over an in-memory connection using the same
`Content-Length`-framed JSON-RPC protocol the CLI transport uses. The runtime can invoke SDK
callbacks from native worker threads; the SDK handles marshalling those calls back onto managed
threads for you.

You can also select the in-process transport without changing application code by setting
`COPILOT_SDK_DEFAULT_CONNECTION=inprocess` before startup — the SDK only falls back to this
environment variable when the client doesn't specify a connection explicitly.

## Limitations

The in-process transport is experimental and comes with a few constraints to be aware of:

- **Shared process state**: every in-process client shares the host process's environment,
  current working directory, and native runtime library — there's no per-client working directory
  or environment override.
- **Rejected process options**: `CopilotClientOptions.Environment`, telemetry configuration, and
  similar options that assume a separate child process are not supported and throw if set.
- **One runtime version per process**: once a native runtime library is loaded, starting another
  client with a different runtime library path or version fails. Starting additional clients that
  reuse the same already-loaded library is fine.
- **Persistent load**: the native library stays loaded for the lifetime of the process even after
  `StopAsync()` gracefully shuts down the client's sessions and connection — don't rely on being
  able to unload and swap in a different runtime build later.

## Best practices

1. **Test per platform**: validate startup, model turns, and shutdown on every OS/architecture
   combination you deploy, since runtime library support varies.
2. **Prefer the default CLI transport** unless you specifically need to avoid a child process —
   it's the most established and isolated deployment path.
3. **Still call `StopAsync()`**: graceful shutdown still closes sessions and the JSON-RPC
   connection cleanly, even though the native library itself remains loaded.
4. **Set process-wide values early**: configure environment variables and working directory before
   creating the first in-process client, since later clients can't override them per-instance.