Behaviour for runtime sandbox adapters.

Adapters implement sandbox creation and management. Currently only the Test adapter is shipped. Custom adapters can be created by implementing this behaviour.

Required Callbacks

• create/1 - Create a new sandbox, return its ID and metadata
• exec/3 - Execute a command in the sandbox
• terminate/2 - Stop and cleanup the sandbox
• status/2 - Get the current sandbox status

Optional Callbacks

• get_url/2 - Get URL for an exposed port
• read_file/3 - Read file contents from sandbox
• write_file/4 - Write file to sandbox
• write_files/3 - Write multiple files to sandbox
• await_ready/3 - Wait for sandbox to become ready
• update/3 - Update sandbox config without destroying
• stop/2 - Stop sandbox without destroying (pause)
• start/2 - Start a stopped sandbox (resume)

Standard Config Fields

These config fields should work consistently across adapters:

• :image - Container image (e.g., "node:22-slim")
• :memory_mb - Memory limit in MB (e.g., 512)
• :env - Environment variables as [{name, value}]
• :ports - Ports to expose (format varies by adapter)
• :mounts - Volume/file mounts (format varies by adapter)
• :proxy - Enable proxy mode for controlled network access

Adapters may support additional adapter-specific config fields.

Example

defmodule MyAdapter do
  @behaviour Puck.Sandbox.Runtime.Adapter

  @impl true
  def create(config) do
    # Create sandbox, return {:ok, sandbox_id, metadata} or {:error, reason}
  end

  @impl true
  def exec(sandbox_id, command, opts) do
    # Execute command, return {:ok, %ExecResult{}} or {:error, reason}
  end

  @impl true
  def terminate(sandbox_id, opts) do
    # Cleanup sandbox, return :ok or {:error, reason}
  end

  @impl true
  def status(sandbox_id, opts) do
    # Return :running | :stopped | :terminated | :unknown
  end
end