skip to content

With Rails' web-console gem, how do you open a console in a view or controller, and what does config.web_console.permissions control?

level: middleimportance: should knowfreq 30%

answer

  1. console in a view or action
  2. rendered at the bottom, not in place
  3. one per request: DoubleRenderError
  4. localhost always allowed
  5. Docker bridge IP and "Cannot render console"

basics

~20 s

Call console in a view or controller action and web-console appends a Ruby console, bound to that context, to the HTML page. config.web_console.permissions lists the extra IP addresses or networks allowed to see it; localhost is always allowed.

solid answer

~40 s

web-console defines `console` in `Kernel`. `<% console %>` in a template, or `console` in an action, records that binding, and the gem's middleware appends a console to the HTML response; it is not rendered where you call it. Only one call per request is allowed, and a second raises `WebConsole::DoubleRenderError`. Responses that are not HTML get no console. Because it runs arbitrary Ruby on the server, it only answers requests from permitted addresses. Localhost (`127.0.0.0/8`, `::1` and the IPv4-mapped loopback) is always allowed, and `config.web_console.permissions = "172.16.0.0/12"` adds more, for example a Docker bridge network. A refused request logs `Cannot render console from <ip>! Allowed networks: ...` while `whiny_requests` is on. The gem aborts boot outside development unless `config.web_console.development_only = false`.

go deeper

for a junior

Recall that console in a view or action opens a browser console in that context and that only one is allowed per request.

for a middle

Explain how the middleware injects the console into HTML responses and how permissions decide who gets one, including the Docker bridge case.

for a senior

Treat web-console as remote code execution: keep it development-only, keep permissions narrow, and recognise the log line when it is refused.

for a principal

Set the team's policy for in-browser consoles in shared development and review environments, balancing convenience against code-execution risk.

## Opening a console on purpose The exception page is not the only place web-console helps. You can ask for a console on **any** page. The gem defines `console` as a `Kernel` method: ```erb <%# app/views/carts/show.html.erb %> <% console %> <h1>Your cart</h1> <%= render @cart.line_items %> ``` ```ruby class CartsController < ApplicationController def show @cart = Cart.find(params[:id]) console # a console in this action's binding end end ``` How it behaves: 1. `console` stores the **caller's binding**, the view's or the action's, in a thread-local and returns `nil`, so `<% %>` and `<%= %>` both print nothing at that spot. 2. When the response comes back, **`WebConsole::Middleware`** sees a stored session and a response whose `Content-Type` includes `html`, and injects the console UI into the page. 3. The console appears at the bottom of the page. Each line you type is sent to the middleware's endpoint under `/__web_console` (`config.web_console.mount_point`) and evaluated in that binding: `@cart`, `params`, helpers in a view, locals. 4. **One per request.** A second `console` call in the same request raises **`WebConsole::DoubleRenderError`**. 5. JSON responses get no console, because the middleware injects it only when the `Content-Type` contains `html`. `binding.console` also exists, for when you want a specific binding without unwinding the stack. In the toy-store discount bug, a `console` call in `CartsController#show` lets you evaluate `@cart.line_items.map { [_1.sku, _1.discount_rate] }` against real data in the page you are looking at, with no terminal involved. ## Who may use it: config.web_console.permissions A web console is **remote code execution by design**. Anyone who can reach it can run Ruby as your app. So web-console checks the requesting IP address before injecting or evaluating anything: - **Always allowed:** `127.0.0.0/8`, `::1` and `::ffff:127.0.0.0/104`, the IPv4 and IPv6 loopback networks. - **`config.web_console.permissions`** adds a single address or a network, as a string or an array: `"192.168.0.100"`, `"192.168.0.0/16"`. - **`config.web_console.allowed_ips`** is accepted as an alternative name. The older **`whitelisted_ips`** is deprecated. The usual reason to touch it is **Docker**. When the app runs in a container, or a devcontainer, your browser's request reaches Rails from the bridge network's gateway address, not from `127.0.0.1`. The console then does not appear, and the log says why: ``` Cannot render console from 172.18.0.1! Allowed networks: 127.0.0.0/127.255.255.255, ::1, ... ``` The fix is to permit that network in `config/environments/development.rb`, for example `config.web_console.permissions = "172.16.0.0/12"`. Keep it as narrow as your setup allows. Set `config.web_console.whiny_requests = false` if you want that log line gone. ## Symptoms and causes | Symptom | Usual cause | |---|---| | No console on the page, and a `Cannot render console from ...` log line | The request came from an address outside the permitted networks | | No console on a JSON endpoint | The response's content type is not HTML | | `WebConsole::DoubleRenderError` | `console` was called twice in one request, for example in a view and in a partial | | Boot aborts with "Web Console is activated in the test environment" | The gem was moved out of the `:development` group | ## A short session 1. Add `console` to `CartsController#show` and reload the cart page. 2. Evaluate `@cart.line_items.map { [_1.sku, _1.discount_rate] }` in the console at the bottom. 3. Spot the item whose rate is `nil` and fix the data or the code. 4. Remove the `console` call, because a stray call would show the console to anyone permitted. ## Guardrails beyond the IP check | Guardrail | What it does | |---|---| | Gemfile group | The generated Gemfile puts `web-console` in `:development` only, and skips it entirely for `--api` apps | | `development_only` | At boot the gem **aborts** if it is loaded outside development, unless you set `config.web_console.development_only = false` | | Permissions | Only listed networks and localhost get a console | | Content type | Only HTML responses get the console injected | Never widen permissions to `0.0.0.0/0` or run the gem on a shared staging server. Anyone on that network could run Ruby in your app. ## Takeaway `console` in a view or action gives you a browser console bound to that exact context, injected at the bottom of the HTML page, once per request. `config.web_console.permissions` decides which addresses besides localhost may use it, and the Docker bridge address is the classic reason to set it.

  • Why does web-console refuse to start when the app boots in the test environment?
    The `web_console.development_only` initializer aborts boot with a message when the gem is loaded outside development, unless `config.web_console.development_only = false` is set. The generated Gemfile keeps the gem in the `:development` group, so this only fires when someone moves it, for example into `:development, :test`.
  • A view calls `console` and a partial it renders calls `console` again. What happens?
    The first call stores its binding in a thread-local. The second sees it already set and raises `WebConsole::DoubleRenderError`, so the page fails to render. Keep a single `console` call per request, and put it where the binding you need lives.

  • <%= console %> renders the console exactly where the tag sits in the template.
  • web-console permissions default to the local network, so Docker works out of the box.
  • config.web_console.whitelisted_ips is the current name for the allowed networks.
  • Calling console in a JSON action shows the console in the API response.
  • Setting permissions to 0.0.0.0/0 is fine on a staging server behind a login.
  • web-console only works on the exception page, not on normal pages.