OpenCode: the complete tutorial, from install to a .NET Minimal API gateway

# GitHub repository (formerly sst/opencode, now under the anomalyco org)
https://github.com/anomalyco/opencode

# website and documentation
https://opencode.ai/docs

# official script (macOS / Linux / WSL)
curl -fsSL https://opencode.ai/install | bash

# alternatively: npm
npm install -g opencode-ai

# or Homebrew (the team's recommended tap)
brew install anomalyco/tap/opencode

# verify
opencode --version

opencode

# inside the TUI:
/connect   # → Anthropic → Manually enter API Key
/connect   # → GitHub Copilot → device flow

# models actually available to the connected accounts
/models

opencode

# inside the TUI:
/connect
# → OpenAI
# → ChatGPT Plus/Pro or Manually enter API Key

/models

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3.5:4b": {
          "name": "Qwen3.5 4B",
          "limit": { "context": 32768, "output": 8192 }
        },
        "qwen3.5:9b": {
          "name": "Qwen3.5 9B",
          "limit": { "context": 32768, "output": 8192 }
        }
      }
    }
  },

  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "ollama/qwen3.5:4b",

  "agent": {
    "build":   { "model": "anthropic/claude-sonnet-4-6" },
    "plan":    { "model": "openai/gpt-5.2-codex" },
    "explore": { "model": "ollama/qwen3.5:9b" },
    "general": { "model": "github-copilot/gpt-5.2" }
  }
}

# lightweight small_model (~3.4 GB)
ollama pull qwen3.5:4b

# local explore model (~6.6 GB)
ollama pull qwen3.5:9b

# runtime budget also declared in opencode.json
export OLLAMA_CONTEXT_LENGTH=32768

# macOS app: set the variable, then restart Ollama
launchctl setenv OLLAMA_CONTEXT_LENGTH 32768

---
description: Review the diff for bugs, missing tests and style drift
mode: subagent
model: github-copilot/gpt-5.2
temperature: 0.2
permission:
  edit: deny
  bash: ask
---
You are a code reviewer. Return a punch list by severity:
must-fix, should-fix, nice-to-have.

# start the headless server (in the project folder it should work on)
OPENCODE_SERVER_PASSWORD=supersecret opencode serve --port 4096

# 1) create a session
curl -s -u opencode:supersecret -X POST http://127.0.0.1:4096/session \
  -H 'Content-Type: application/json' -d '{"title":"demo"}'
# → {"id":"ses_090d852eeffeul0zvfzfR2HT77", ...}

# 2) send a prompt to the session (synchronous: waits for the reply)
curl -s -u opencode:supersecret -X POST \
  http://127.0.0.1:4096/session/ses_090d852eeffeul0zvfzfR2HT77/message \
  -H 'Content-Type: application/json' \
  -d '{"parts":[{"type":"text","text":"Explain this repository"}]}'

dotnet new web -f net9.0 -n OpenCodeGateway && cd OpenCodeGateway
dotnet add package Refit.HttpClientFactory --version 13.1.0
dotnet add package Microsoft.AspNetCore.OpenApi --version 9.0.17
dotnet user-secrets init
dotnet user-secrets set "OpenCode:Password" "supersecret"
dotnet user-secrets set "Gateway:ApiKey" "generate-a-long-random-value"

# final structure
# OpenCodeGateway/
# ├── Program.cs
# ├── appsettings.json
# ├── Settings/OpenCodeSettings.cs
# ├── Models/Models.cs
# ├── Clients/IOpenCodeApi.cs
# ├── Services/AssistantService.cs + GatewayExceptions.cs
# ├── Security/GatewayApiKeyFilter.cs
# ├── Extensions/ServiceCollectionExtensions.cs
# └── Endpoints/AssistantEndpoints.cs

public sealed class OpenCodeSettings
{
    public const string SectionName = "OpenCode";

    public string BaseUrl { get; init; } = "http://127.0.0.1:4096";
    public string Username { get; init; } = "opencode";
    public string Password { get; init; } = string.Empty;
    public int TimeoutSeconds { get; init; } = 300;
}

public sealed class GatewaySettings
{
    public const string SectionName = "Gateway";
    public string ApiKey { get; init; } = string.Empty;
    public string[] AllowedAgents { get; init; } = ["build", "plan", "explore", "general"];
}

// ----- gateway contracts -----
public record AskRequest(string Prompt, string? Agent = null, string? SessionId = null);
public record AskResponse(string SessionId, string Reply);
public record ApiErrorResponse(string Code, string Error);

// ----- OpenCode server contracts (camelCase on the wire) -----
public record CreateSessionRequest(string? Title = null);
public record OpenCodeSession(string Id, string? Title = null);

public record OpenCodeMessagePart(string Type, string Text);
public record SendMessageRequest(IReadOnlyList<OpenCodeMessagePart> Parts, string? Agent = null);

public record OpenCodePart(string Type, string? Text = null);
public record OpenCodeMessageInfo(string Id, string Role);
public record OpenCodeMessageResponse(OpenCodeMessageInfo Info, IReadOnlyList<OpenCodePart> Parts);

using Refit;

public interface IOpenCodeApi
{
    [Post("/session")]
    Task<OpenCodeSession> CreateSessionAsync(
        [Body] CreateSessionRequest request, CancellationToken ct = default);

    [Post("/session/{sessionId}/message")]
    Task<OpenCodeMessageResponse> SendMessageAsync(
        string sessionId, [Body] SendMessageRequest request, CancellationToken ct = default);
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using Microsoft.Extensions.Options;
using Refit;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddOpenCode(
        this IServiceCollection services, IConfiguration configuration)
    {
        services.AddOptions<OpenCodeSettings>()
            .Bind(configuration.GetSection(OpenCodeSettings.SectionName))
            .Validate(s => Uri.TryCreate(s.BaseUrl, UriKind.Absolute, out _),
                "OpenCode:BaseUrl must be an absolute URL")
            .Validate(s => !string.IsNullOrWhiteSpace(s.Password),
                "OpenCode:Password is required")
            .Validate(s => s.TimeoutSeconds is > 0 and <= 900,
                "OpenCode:TimeoutSeconds must be between 1 and 900")
            .ValidateOnStart();

        services.AddOptions<GatewaySettings>()
            .Bind(configuration.GetSection(GatewaySettings.SectionName))
            .Validate(s => !string.IsNullOrWhiteSpace(s.ApiKey),
                "Gateway:ApiKey is required")
            .Validate(s => s.AllowedAgents.Length > 0,
                "Gateway:AllowedAgents cannot be empty")
            .ValidateOnStart();

        var serializerOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web)
        {
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        };

        services
            .AddRefitClient<IOpenCodeApi>(
                new RefitSettings(new SystemTextJsonContentSerializer(serializerOptions)))
            .ConfigureHttpClient((provider, client) =>
            {
                var settings = provider.GetRequiredService<IOptions<OpenCodeSettings>>().Value;
                client.BaseAddress = new Uri(settings.BaseUrl);
                client.Timeout = TimeSpan.FromSeconds(settings.TimeoutSeconds);
                var credentials = Convert.ToBase64String(
                    Encoding.UTF8.GetBytes($"{settings.Username}:{settings.Password}"));
                client.DefaultRequestHeaders.Authorization =
                    new AuthenticationHeaderValue("Basic", credentials);
            });

        services.AddScoped<IAssistantService, AssistantService>();
        return services;
    }
}

using System.Net;
using Refit;

public interface IAssistantService
{
    Task<AskResponse> AskAsync(AskRequest request, CancellationToken ct);
}

public sealed class AssistantService(
    IOpenCodeApi openCode,
    ILogger<AssistantService> logger) : IAssistantService
{
    public async Task<AskResponse> AskAsync(AskRequest request, CancellationToken ct)
    {
        try
        {
            var sessionId = request.SessionId
                ?? (await openCode.CreateSessionAsync(
                    new CreateSessionRequest("gateway"), ct)).Id;

            var message = new SendMessageRequest(
                [new OpenCodeMessagePart("text", request.Prompt)],
                request.Agent);

            var response = await openCode.SendMessageAsync(sessionId, message, ct);
            var reply = string.Join("\n", response.Parts
                .Where(p => p.Type == "text" && !string.IsNullOrWhiteSpace(p.Text))
                .Select(p => p.Text));
            return new AskResponse(sessionId, reply);
        }
        catch (ApiException ex) when (request.SessionId is not null &&
            ex.StatusCode == HttpStatusCode.NotFound)
        {
            throw new SessionNotFoundException(ex);
        }
        catch (ApiException ex)
        {
            logger.LogWarning(ex, "OpenCode returned HTTP {StatusCode}", (int)ex.StatusCode);
            throw new OpenCodeRejectedException(ex);
        }
        catch (ApiRequestException ex) when (ex.InnerException is TaskCanceledException &&
            !ct.IsCancellationRequested)
        {
            // Refit 13 wraps the HttpClient timeout: inner TaskCanceledException
            throw new OpenCodeTimeoutException(ex);
        }
        catch (ApiRequestException ex)
        {
            // Refit 13 wraps connection failures (server down, DNS, refused)
            throw new OpenCodeUnavailableException(ex);
        }
        catch (TaskCanceledException ex) when (!ct.IsCancellationRequested)
        {
            throw new OpenCodeTimeoutException(ex);
        }
    }
}

// Services/GatewayExceptions.cs
public sealed class SessionNotFoundException(Exception inner) : Exception("Session not found", inner);
public sealed class OpenCodeTimeoutException(Exception inner) : Exception("OpenCode timeout", inner);
public sealed class OpenCodeUnavailableException(Exception inner) : Exception("OpenCode unavailable", inner);
public sealed class OpenCodeRejectedException(Exception inner) : Exception("OpenCode rejected request", inner);

using System.Security.Cryptography;
using System.Text;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.Extensions.Options;

public sealed class GatewayApiKeyFilter(IOptions<GatewaySettings> options) : IEndpointFilter
{
    public const string HeaderName = "X-API-Key";

    public ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        var supplied = context.HttpContext.Request.Headers[HeaderName].ToString();
        var suppliedHash = SHA256.HashData(Encoding.UTF8.GetBytes(supplied));
        var expectedHash = SHA256.HashData(Encoding.UTF8.GetBytes(options.Value.ApiKey));
        if (!CryptographicOperations.FixedTimeEquals(suppliedHash, expectedHash))
            return ValueTask.FromResult<object?>(TypedResults.Unauthorized());
        return next(context);
    }
}

// Endpoints/AssistantEndpoints.cs
public static class AssistantEndpoints
{
    public static void MapAssistantEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/v1/assistant")
            .WithTags("Assistant")
            .AddEndpointFilter<GatewayApiKeyFilter>();

        group.MapPost("/", AskAsync).WithName("AskAssistant")
            .Produces(StatusCodes.Status401Unauthorized)
            .ProducesProblem(StatusCodes.Status502BadGateway)
            .ProducesProblem(StatusCodes.Status503ServiceUnavailable)
            .ProducesProblem(StatusCodes.Status504GatewayTimeout);
    }

    private static async Task<Results<Ok<AskResponse>, BadRequest<ApiErrorResponse>,
        NotFound<ApiErrorResponse>, ProblemHttpResult>> AskAsync(
        AskRequest request, IAssistantService assistant,
        IOptions<GatewaySettings> gateway, CancellationToken ct)
    {
        if (string.IsNullOrWhiteSpace(request.Prompt))
            return TypedResults.BadRequest(
                new ApiErrorResponse("invalid_prompt", "Prompt is required"));
        if (request.SessionId is not null &&
            !request.SessionId.StartsWith("ses_", StringComparison.Ordinal))
            return TypedResults.BadRequest(
                new ApiErrorResponse("invalid_session", "SessionId must start with 'ses_'"));
        if (request.Agent is not null &&
            !gateway.Value.AllowedAgents.Contains(request.Agent, StringComparer.Ordinal))
            return TypedResults.BadRequest(
                new ApiErrorResponse("invalid_agent", "Agent is not allowed"));

        try { return TypedResults.Ok(await assistant.AskAsync(request, ct)); }
        catch (SessionNotFoundException) { return TypedResults.NotFound(
            new ApiErrorResponse("session_not_found", "OpenCode session not found")); }
        catch (OpenCodeTimeoutException) { return TypedResults.Problem(
            statusCode: StatusCodes.Status504GatewayTimeout, title: "OpenCode timed out"); }
        catch (OpenCodeUnavailableException) { return TypedResults.Problem(
            statusCode: StatusCodes.Status503ServiceUnavailable, title: "OpenCode is unavailable"); }
        catch (OpenCodeRejectedException) { return TypedResults.Problem(
            statusCode: StatusCodes.Status502BadGateway, title: "OpenCode rejected the request"); }
    }
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddOpenCode(builder.Configuration);

var app = builder.Build();

app.MapOpenApi(); // GET /openapi/v1.json
app.MapAssistantEndpoints();

app.Run();

/* appsettings.json:
{
  "OpenCode": {
    "BaseUrl": "http://127.0.0.1:4096",
    "Username": "opencode",
    "TimeoutSeconds": 300
  },
  "Gateway": {
    "AllowedAgents": ["build", "plan", "explore", "general"]
  }
} */

# terminal 1 — the OpenCode server
OPENCODE_SERVER_PASSWORD=supersecret opencode serve --port 4096

# terminal 2 — the .NET gateway
dotnet run --urls http://localhost:5099

# terminal 3 — the test
curl -s -X POST http://localhost:5099/api/v1/assistant \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: generate-a-long-random-value' \
  -d '{"prompt":"Say hello","agent":"plan"}'

# response shape; text and ID depend on the live run
# → {"sessionId":"ses_...","reply":"..."}
# send sessionId in the next body to continue the same conversation

# CLAUDE.md — OpenCodeGateway

.NET 9 Minimal API gateway that calls OpenCode via `opencode serve`.

## Stack
- .NET 9 Minimal API — NEVER MVC Controllers
- Refit for HTTP clients — NEVER hand-rolled HttpClient
- DTOs: positional records — NEVER object/dynamic/anonymous types
- Settings: Options pattern with a SectionName constant

## Commands
- `dotnet build` — build
- `dotnet run --urls http://localhost:5099` — start on the tutorial's port

## Conventions
- Endpoints in `Endpoints/*.cs` as `MapXEndpoints` extensions over MapGroup
- DI registrations in `Extensions/ServiceCollectionExtensions.cs` (AddX)
- Handlers: TypedResults + explicit Results<...> return types

---
name: opencode-contract-check
description: Verify the gateway's Refit DTOs (Models/Models.cs)
  against the live OpenAPI spec of opencode serve. Use after an
  OpenCode upgrade or when CreateSession/SendMessage start failing
  at deserialization.
---

# Check contract drift towards opencode serve

1. Health check (basic auth if the server has a password):
   `curl -s -u opencode:$OPENCODE_SERVER_PASSWORD http://127.0.0.1:4096/global/health`.
   If the server is down, ask to start `opencode serve` and stop.
2. Fetch the OpenAPI 3.1 spec (JSON):
   `curl -s -u opencode:$OPENCODE_SERVER_PASSWORD http://127.0.0.1:4096/doc`.
3. Extract the schemas for the only endpoints the gateway uses:
   `POST /session` and `POST /session/{id}/message`.
4. Compare with the records in `Models/Models.cs`:
   OpenCodeSession, SendMessageRequest, OpenCodeMessageResponse,
   OpenCodePart (missing fields, renames, type changes).
5. Report the drift by severity (must-fix / nice-to-have) and propose
   the record diffs — do NOT apply them without confirmation.
6. Note in the report the server version read from /global/health.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Refit;

// Example contract: replace the route and methods with the real API contract.
public interface IProtectedApi
{
    [Get("/api/profile")]
    Task<HttpResponseMessage> GetProfileAsync(CancellationToken ct = default);
}

public static class ProtectedApiServiceCollectionExtensions
{
    public static IServiceCollection AddProtectedApi(this IServiceCollection services)
    {
        // DelegatingHandlers are registered as transient...
        services.AddTransient<JwtAuthHandler>();
        services.AddTransient<HttpLoggingHandler>();

        // ...and chained onto the Refit client.
        // On requests, auth runs before logging; no headers or bodies are printed.
        services
            .AddRefitClient<IProtectedApi>()
            .ConfigureHttpClient((provider, client) =>
            {
                var settings = provider.GetRequiredService<IOptions<AuthSettings>>().Value;
                client.BaseAddress = new Uri(settings.BaseUrl);
            })
            .AddHttpMessageHandler<JwtAuthHandler>()
            .AddHttpMessageHandler<HttpLoggingHandler>();

        return services;
    }
}

using System.Diagnostics;

public sealed class HttpLoggingHandler(ILogger<HttpLoggingHandler> logger) : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        // Correlate request and response lines with a short id.
        var id = Guid.NewGuid().ToString("N")[..8];
        var target = SafeTarget(request.RequestUri);
        var stopwatch = Stopwatch.StartNew();

        logger.LogInformation("[{Id} req] {Method} {Target}", id, request.Method, target);
        try
        {
            var response = await base.SendAsync(request, cancellationToken);
            logger.LogInformation(
                "[{Id} res] {StatusCode} in {ElapsedMs} ms",
                id, (int)response.StatusCode, stopwatch.ElapsedMilliseconds);
            return response;
        }
        catch (Exception exception)
        {
            logger.LogWarning(exception,
                "[{Id} err] {Method} {Target} after {ElapsedMs} ms",
                id, request.Method, target, stopwatch.ElapsedMilliseconds);
            throw;
        }
    }

    private static string SafeTarget(Uri? uri)
    {
        if (uri is null)
            return "(unknown)";

        var value = uri.IsAbsoluteUri ? uri.GetLeftPart(UriPartial.Path) : uri.OriginalString;
        var queryIndex = value.IndexOf('?');
        return queryIndex >= 0 ? value[..queryIndex] : value;
    }
}

using System.Net.Http.Headers;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Refit;

public sealed class AuthSettings
{
    public const string SectionName = "Auth";
    public string BaseUrl { get; init; } = string.Empty;
    public string UserName { get; init; } = string.Empty;
    public string Password { get; init; } = string.Empty;
}

public record TokenRequest(string UserName, string Password);
public record TokenResponse(string Token, DateTimeOffset ExpiresAt);

// Refit client for the endpoint that issues the JWT.
// Registered WITHOUT JwtAuthHandler: no recursive auth.
public interface IAuthApi
{
    [Post("/api/auth/signin")]
    Task<TokenResponse> SignInAsync([Body] TokenRequest request, CancellationToken ct = default);
}

public sealed class JwtTokenProvider(
    IHttpClientFactory httpClientFactory,
    IOptions<AuthSettings> options)
{
    private readonly SemaphoreSlim gate = new(1, 1);
    private string? token;
    private DateTimeOffset expiresAt;

    /// <summary>Returns a cached JWT, requesting a new one when missing or close to expiry.</summary>
    public async Task<string> GetTokenAsync(CancellationToken ct)
    {
        await gate.WaitAsync(ct);
        try
        {
            if (token is null || DateTimeOffset.UtcNow >= expiresAt.AddMinutes(-1))
            {
                var settings = options.Value;
                var authApi = RestService.For<IAuthApi>(httpClientFactory.CreateClient("AuthApi"));
                var response = await authApi.SignInAsync(new TokenRequest(settings.UserName, settings.Password), ct);
                token = response.Token;
                expiresAt = response.ExpiresAt;
            }

            return token;
        }
        finally
        {
            gate.Release();
        }
    }
}

public sealed class JwtAuthHandler(JwtTokenProvider tokenProvider) : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        // Attach a valid bearer token to every outgoing call.
        var token = await tokenProvider.GetTokenAsync(cancellationToken);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

        return await base.SendAsync(request, cancellationToken);
    }
}

public static class AuthServiceCollectionExtensions
{
    public static IServiceCollection AddJwtAuthentication(
        this IServiceCollection services, IConfiguration configuration)
    {
        services.AddOptions<AuthSettings>()
            .Bind(configuration.GetSection(AuthSettings.SectionName))
            .Validate(s => Uri.TryCreate(s.BaseUrl, UriKind.Absolute, out _),
                "Auth:BaseUrl must be an absolute URL")
            .Validate(s => !string.IsNullOrWhiteSpace(s.UserName),
                "Auth:UserName is required")
            .Validate(s => !string.IsNullOrWhiteSpace(s.Password),
                "Auth:Password is required")
            .ValidateOnStart();

        // Named client without JwtAuthHandler: avoids recursion during login.
        services.AddHttpClient("AuthApi", (provider, client) =>
        {
            var settings = provider.GetRequiredService<IOptions<AuthSettings>>().Value;
            client.BaseAddress = new Uri(settings.BaseUrl);
        });

        services.AddSingleton<JwtTokenProvider>();
        services.AddTransient<JwtAuthHandler>();
        return services;
    }
}