Skip to content

Getting Started

This guide gets you running end-to-end: obtain the codex binary, install the package, and run your first turn with basic configuration.

Along the way, we will refer to a few core terms:

  • Codex: the entry point. It configures how the CLI is launched and creates threads.
  • Thread: a conversation container. Each call to RunAsync is a new turn.
  • Turn: the completed result of a single run (final response, items, usage).
  • ThreadEvent: a streaming event emitted by the CLI and parsed by the SDK.
  • ThreadItem: a completed unit of work produced during a turn (agent message, tool call, file change, etc.).

You do not need an OpenAI API key to use this SDK. It is enough to use a ChatGPT account with Codex access enabled.

1) Get the codex binary

The SDK is just a wrapper around the Codex CLI. Provide the codex binary in one of these ways:

  • Recommended: place the binary under vendor/<target-triple>/codex/ relative to your application output.
  • Alternative: set CodexOptions.CodexPathOverride to the full path of the binary.

Example override:

var codex = new Codex(new CodexOptions
{
    CodexPathOverride = "/path/to/codex"
});

If you need details about how the target triple is resolved or how the SDK locates the binary, see Configuration.

You can download the latest binary here

2) Setup authentication

Before you continue, make sure your Codex instance is authenticated. You can either:

  • Provide an API key when you construct Codex in the next step (via CodexOptions.ApiKey).
  • Or open a terminal, run codex, and complete the browser sign-in flow.

If you skip both, the application will fail with a 401 error.

3) Install the NuGet package

From your project directory, run:

dotnet add package CodexNet

4) Run your first turn

With the package installed and authentication in place, run a quick end-to-end example to confirm everything is wired up.

The example below creates a client, starts a thread, runs a turn, and prints the final response.

using CodexNet;

var codex = new Codex();
var thread = codex.StartThread();
var turn = await thread.RunAsync("Summarize the latest changes in this repo");

Console.WriteLine(turn.FinalResponse);

If it runs as expected, you are ready for the end-to-end flow.

5) Add thread options (optional)

Thread options apply to every turn in that thread. Use them when you would like to set the model, sandbox, or working directory once.

var thread = codex.StartThread(new ThreadOptions
{
    Model = "gpt-test-1",
    SandboxMode = SandboxMode.WorkspaceWrite,
    WorkingDirectory = "/path/to/project",
    SkipGitRepoCheck = true,
});

For the full list of options, see Configuration.

6) Add turn options (optional)

Turn options apply to a single run. Common examples include structured output and cancellation.

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(20));

var schema = new
{
    type = "object",
    properties = new { answer = new { type = "string" } },
    required = new[] { "answer" },
    additionalProperties = false
};

var turn = await thread.RunAsync("Summarize", new TurnOptions
{
    OutputSchema = schema,
    CancellationToken = cts.Token,
});

From here, you can explore inputs, streaming, and other patterns in Inputs and Outputs.