Installation

View Source

Requirements

  • Elixir 1.15+
  • Phoenix 1.8+
  • An existing Phoenix application (or create one with mix phx.new)

OpenResponses ships an Igniter installer that handles everything:

mix igniter.install open_responses

This will:

  1. Add open_responses to your dependencies
  2. Register the Ash domain in your config
  3. Mount POST /v1/responses in your router
  4. Add Cachex and OpenResponses.LoopSupervisor to your supervision tree
  5. Create a provider config block in config/runtime.exs

Manual installation

If you prefer to wire things up yourself, add to mix.exs:

defp deps do
  [
    {:open_responses, "~> 0.1"},
    {:cachex, "~> 3.6"}
  ]
end

Then follow the steps below.

1. Add to your supervision tree

In lib/your_app/application.ex, add after Phoenix.PubSub:

children = [
  # ... existing children ...
  {Cachex, name: :response_cache},
  OpenResponses.LoopSupervisor
]

2. Register the Ash domain

In config/config.exs:

config :your_app,
  ash_domains: [
    # ... existing domains ...
    OpenResponses.Responses
  ]

3. Mount the router scope

In lib/your_app_web/router.ex:

scope "/v1", OpenResponsesWeb do
  pipe_through :api

  post "/responses", OpenResponsesWeb.ResponseController, :create
end

4. Configure providers

In config/runtime.exs:

config :open_responses, :provider_config, %{
  openai: [api_key: System.fetch_env!("OPENAI_API_KEY")],
  anthropic: [api_key: System.fetch_env!("ANTHROPIC_API_KEY")],
  gemini: [api_key: System.fetch_env!("GEMINI_API_KEY")]
}

Optional: Prometheus metrics

OpenResponses ships a PromEx plugin. To enable it, add OpenResponses.PromEx to your supervision tree and mount the metrics endpoint:

# application.ex
children = [OpenResponses.PromEx, ...]

# router.ex
get "/metrics", PromEx.Plug, prom_ex_module: OpenResponses.PromEx

See Observability for full details.

Verifying the installation

Start your server and send a test request:

curl -X POST http://localhost:4000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model": "mock-model", "input": [{"role": "user", "content": "hello"}]}'

You should receive a JSON response with "status": "completed".