runtime-remsh

name: runtime-remsh description: Connect to a running Lemon or lemon-gateway BEAM node, run recompile() for hot code reload, and execute Elixir code in that live runtime via IEx remsh or rpc-eval. metadata: { "lemon": { "requires": { "bins": ["elixir", "iex"] } } }

Use this skill when the user asks to connect to a running Lemon instance, recompile changed Elixir code without restarting, or run Elixir inside the live runtime.

Trigger

Use this skill for requests like:

"connect to the running gateway"
"attach to lemon and run recompile()"
"execute this Elixir in the live runtime"
"run rpc-eval against the node"

Preconditions

The target process must be started as a distributed node (--sname or --name) with a cookie.
The attaching shell must use the same naming mode and same cookie.
For ./bin/lemon-gateway, do not use --no-distribution.

Quickstart (local gateway)

Start gateway (terminal 1):

./bin/lemon-gateway

Attach from another terminal (short-name default):

iex --sname lemon_attach --cookie lemon_gateway_dev_cookie --remsh "lemon_gateway@$(hostname -s)"

If gateway was started with explicit settings, use those exact values:

./bin/lemon-gateway --sname lemon_gateway --cookie "change-me"
iex --sname lemon_attach --cookie "change-me" --remsh "lemon_gateway@$(hostname -s)"

For long-name mode:

./bin/lemon-gateway --name lemon_gateway@my-host.example.com --cookie "change-me"
iex --name lemon_attach@my-host.example.com --cookie "change-me" --remsh lemon_gateway@my-host.example.com

Tip: ./bin/lemon-gateway prints the exact Remote shell target to use.

Recompile changed code in the live runtime

Inside attached IEx:

recompile()

Useful follow-up checks:

node()
Application.started_applications() |> Enum.map(&elem(&1, 0))

If needed, force reload a module:

r(LemonGateway.Run)

Execute arbitrary Elixir code in the live runtime

Interactive (--remsh) examples:

LemonGateway.Config.get()
LemonGateway.Config.get(:default_engine)

Non-interactive one-off (--rpc-eval) example:

elixir --sname lemon_probe --cookie lemon_gateway_dev_cookie --rpc-eval "lemon_gateway@$(hostname -s)" "IO.inspect(LemonGateway.Config.get(:default_engine))"

Long-name one-off:

elixir --name lemon_probe@my-host.example.com --cookie "change-me" --rpc-eval "lemon_gateway@my-host.example.com" "IO.puts(node())"

Troubleshooting

nodedown or timeout:
- Ensure both sides use short names (--sname) or both use long names (--name).
- Confirm the exact target node name from gateway startup logs.
Invalid challenge reply:
- Cookie mismatch. Use the same cookie on launcher and attach command.
Attach works but app calls fail:
- Target process may have exited after startup; check gateway logs.
Verify registration with EPMD:

epmd -names

Safety

Default to read-only inspection unless the user asked to mutate state.
Call out risky runtime actions before executing them (state mutation, process termination, file/network side effects).
Prefer --rpc-eval for small one-off checks and --remsh for multi-step debugging.