# Runtime Remsh

> 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. Use when this capability is needed.

- Skill: `tomevault-io/runtime-remsh` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/runtime-remsh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/runtime-remsh/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/runtime-remsh

---


# runtime-remsh

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):

```bash
./bin/lemon-gateway
```

Attach from another terminal (short-name default):

```bash
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:

```bash
./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:

```bash
./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:

```elixir
recompile()
```

Useful follow-up checks:

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

If needed, force reload a module:

```elixir
r(LemonGateway.Run)
```

## Execute arbitrary Elixir code in the live runtime

Interactive (`--remsh`) examples:

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

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

```bash
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:

```bash
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:

```bash
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.

---
> Source: [z80dev/lemon](https://github.com/z80dev/lemon) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-20 -->