Support multiple named providers with a configurable default

Follows the Finch pool pattern: configure multiple providers by name
with their options, and designate one as the default.

  config :terrarium,
    default: :daytona,
    providers: [
      daytona: {Terrarium.Daytona, api_key: "..."},
      e2b: {Terrarium.E2B, api_key: "..."},
      local: Terrarium.Providers.Local
    ]

Provider config opts are merged with call-site opts, with call-site
taking precedence. Config-dependent tests are isolated in a separate
async: false test file.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

lib/terrarium.ex

@@ -15,21 +15,26 @@ defmodule Terrarium do
 
   ## Configuration
 
-  Configure a default provider so you don't have to pass it on every call:
+  Configure multiple providers and set a default:
 
-      # config/config.exs
-      config :terrarium, provider: Terrarium.Providers.Local
-
-      # config/prod.exs
-      config :terrarium, provider: Terrarium.Daytona
+      config :terrarium,
+        default: :daytona,
+        providers: [
+          daytona: {Terrarium.Daytona, api_key: System.fetch_env!("DAYTONA_API_KEY")},
+          e2b: {Terrarium.E2B, api_key: System.fetch_env!("E2B_API_KEY")},
+          local: Terrarium.Providers.Local
+        ]
 
   ## Usage
 
-      # Using the configured default provider
+      # Uses the default provider
       {:ok, sandbox} = Terrarium.create(image: "debian:12")
 
-      # Or explicitly passing a provider
-      {:ok, sandbox} = Terrarium.create(MyApp.Sandbox.Daytona, image: "debian:12")
+      # Uses a named provider
+      {:ok, sandbox} = Terrarium.create(:e2b, image: "debian:12")
+
+      # Uses an explicit provider module
+      {:ok, sandbox} = Terrarium.create(Terrarium.Daytona, image: "debian:12", api_key: "...")
 
       # Execute commands
       {:ok, result} = Terrarium.exec(sandbox, "echo hello")
@@ -45,43 +50,52 @@ defmodule Terrarium do
   alias Terrarium.Sandbox
 
   @doc """
-  Creates a new sandbox using the given provider, or the configured default.
+  Creates a new sandbox.
+
+  Can be called in three ways:
+
+  - `Terrarium.create(opts)` — uses the configured default provider
+  - `Terrarium.create(:name, opts)` — uses a named provider from config
+  - `Terrarium.create(ProviderModule, opts)` — uses the module directly
+
+  Provider-specific options from config are merged with call-site opts,
+  with call-site opts taking precedence.
 
   ## Options
 
   Options are provider-specific. Common options include:
 
   - `:image` — the base image for the sandbox
   - `:resources` — CPU, memory, and disk configuration
+  - `:provider` — inline provider as a module or `{module, opts}` tuple
 
   ## Examples
 
-      # With configured default provider
       {:ok, sandbox} = Terrarium.create(image: "debian:12")
-
-      # With explicit provider
+      {:ok, sandbox} = Terrarium.create(:e2b, image: "debian:12")
       {:ok, sandbox} = Terrarium.create(MyProvider, image: "debian:12")
   """
-  @spec create(module() | keyword(), keyword()) :: {:ok, Sandbox.t()} | {:error, term()}
+  @spec create(module() | atom() | keyword(), keyword()) :: {:ok, Sandbox.t()} | {:error, term()}
   def create(provider_or_opts \\ [], opts \\ [])
 
-  def create(provider, opts) when is_atom(provider) do
-    provider.create(opts)
+  def create(name, opts) when is_atom(name) and name != nil do
+    {provider, provider_opts} = resolve_named_or_module(name)
+    provider.create(Keyword.merge(provider_opts, opts))
   end
 
   def create(opts, []) when is_list(opts) do
-    {provider, opts} = resolve_provider(opts)
-    provider.create(opts)
+    {provider, provider_opts, opts} = resolve_from_opts(opts)
+    provider.create(Keyword.merge(provider_opts, opts))
   end
 
   @doc """
   Creates a new sandbox, raising on error.
   """
-  @spec create!(module() | keyword(), keyword()) :: Sandbox.t()
+  @spec create!(module() | atom() | keyword(), keyword()) :: Sandbox.t()
   def create!(provider_or_opts \\ [], opts \\ [])
 
-  def create!(provider, opts) when is_atom(provider) do
-    case create(provider, opts) do
+  def create!(name, opts) when is_atom(name) and name != nil do
+    case create(name, opts) do
       {:ok, sandbox} -> sandbox
       {:error, reason} -> raise "Failed to create sandbox: #{inspect(reason)}"
     end
@@ -191,21 +205,44 @@ defmodule Terrarium do
     provider.ls(sandbox, path)
   end
 
-  defp resolve_provider(opts) do
+  # Resolves an atom that could be either a named provider from config
+  # or a direct provider module.
+  defp resolve_named_or_module(name) do
+    providers = Application.get_env(:terrarium, :providers, [])
+
+    case Keyword.fetch(providers, name) do
+      {:ok, {module, opts}} -> {module, opts}
+      {:ok, module} when is_atom(module) -> {module, []}
+      :error -> {name, []}
+    end
+  end
+
+  # Resolves the provider from opts (inline :provider key) or falls back
+  # to the configured default.
+  defp resolve_from_opts(opts) do
     case Keyword.pop(opts, :provider) do
       {nil, opts} ->
-        case Application.get_env(:terrarium, :provider) do
-          nil ->
-            raise ArgumentError,
-                  "no default provider configured. Either pass a provider module explicitly " <>
-                    "or set one in your config: config :terrarium, provider: Terrarium.Providers.Local"
-
-          provider ->
-            {provider, opts}
-        end
-
-      {provider, opts} ->
-        {provider, opts}
+        {provider, provider_opts} = resolve_default!()
+        {provider, provider_opts, opts}
+
+      {{module, provider_opts}, opts} when is_atom(module) ->
+        {module, provider_opts, opts}
+
+      {module, opts} when is_atom(module) ->
+        {provider, provider_opts} = resolve_named_or_module(module)
+        {provider, provider_opts, opts}
+    end
+  end
+
+  defp resolve_default! do
+    case Application.get_env(:terrarium, :default) do
+      nil ->
+        raise ArgumentError,
+              "no default provider configured. Either pass a provider explicitly " <>
+                "or configure one: config :terrarium, default: :local, providers: [local: Terrarium.Providers.Local]"
+
+      name ->
+        resolve_named_or_module(name)
     end
   end
 end

test/terrarium/config_test.exs

@@ -0,0 +1,45 @@
+defmodule Terrarium.ConfigTest do
+  use ExUnit.Case, async: false
+
+  alias Terrarium.Sandbox
+
+  # These tests modify Application config and must run sequentially.
+
+  setup do
+    on_exit(fn ->
+      Application.delete_env(:terrarium, :default)
+      Application.delete_env(:terrarium, :providers)
+    end)
+  end
+
+  describe "named providers from config" do
+    test "resolves a named provider" do
+      Application.put_env(:terrarium, :providers, test: Terrarium.TestProvider)
+
+      assert {:ok, %Sandbox{provider: Terrarium.TestProvider}} = Terrarium.create(:test)
+    end
+
+    test "resolves a named provider with {module, opts} tuple" do
+      Application.put_env(:terrarium, :providers, test: {Terrarium.TestProvider, some: "config"})
+
+      assert {:ok, %Sandbox{provider: Terrarium.TestProvider}} = Terrarium.create(:test)
+    end
+  end
+
+  describe "default provider from config" do
+    test "uses the configured default provider" do
+      Application.put_env(:terrarium, :default, :test)
+      Application.put_env(:terrarium, :providers, test: Terrarium.TestProvider)
+
+      assert {:ok, %Sandbox{provider: Terrarium.TestProvider}} = Terrarium.create()
+    end
+
+    test "merges config opts with call-site opts" do
+      Application.put_env(:terrarium, :default, :test)
+      Application.put_env(:terrarium, :providers, test: {Terrarium.TestProvider, from_config: true})
+
+      assert {:ok, %Sandbox{provider: Terrarium.TestProvider}} =
+               Terrarium.create(from_call: true)
+    end
+  end
+end

test/terrarium_test.exs

@@ -3,18 +3,27 @@ defmodule TerrariumTest do
 
   alias Terrarium.Sandbox
 
-  describe "create/2" do
+  describe "create/2 with explicit module" do
     test "delegates to the provider's create callback" do
       assert {:ok, %Sandbox{id: "test-123", provider: Terrarium.TestProvider}} =
                Terrarium.create(Terrarium.TestProvider)
     end
+  end
 
-    test "uses the provider from opts when no module is passed" do
+  describe "create/1 with inline :provider option" do
+    test "accepts a provider module in opts" do
       assert {:ok, %Sandbox{provider: Terrarium.TestProvider}} =
                Terrarium.create(provider: Terrarium.TestProvider)
     end
 
-    test "raises when no provider is configured and none is passed" do
+    test "accepts a {module, opts} tuple in opts" do
+      assert {:ok, %Sandbox{provider: Terrarium.TestProvider}} =
+               Terrarium.create(provider: {Terrarium.TestProvider, some: "config"})
+    end
+  end
+
+  describe "create/1 with no provider" do
+    test "raises when no default is configured" do
       assert_raise ArgumentError, ~r/no default provider configured/, fn ->
         Terrarium.create()
       end
@@ -38,7 +47,9 @@ defmodule TerrariumTest do
   describe "exec/3" do
     test "delegates to the provider's exec callback" do
       sandbox = %Sandbox{id: "test-123", provider: Terrarium.TestProvider}
-      assert {:ok, %Terrarium.Process.Result{exit_code: 0, stdout: "hello\n"}} = Terrarium.exec(sandbox, "echo hello")
+
+      assert {:ok, %Terrarium.Process.Result{exit_code: 0, stdout: "hello\n"}} =
+               Terrarium.exec(sandbox, "echo hello")
     end
   end