Run an ephemeral Erigon instance with a temporary datadir. Use this whenever the user wants to spin up a temporary, throwaway, or sandboxed Erigon node for quick testing, launch a second Erigon instance alongside an existing one, clone a datadir into a temp copy for safe experimentation, or find and clean up leftover ephemeral datadirs and processes from previous sessions. Handles port conflict detection and automatic port offsetting. Trigger on any mention of temporary/throwaway/ephemeral/disposable Erigon instances, running erigon briefly for testing or debugging, starting a second/additional erigon node, or cleaning up old temp erigon data.
Spin up a temporary Erigon instance with its datadir in the system's default temp directory. Handles port conflicts automatically and supports safe cleanup.
Follow these steps in order:
Check if ./build/bin/erigon exists. If it does not exist or the user requests a fresh build, invoke the /erigon-build skill. Otherwise skip this step.
There are two modes: empty (default) or clone (if the user provides a source datadir to clone from).
Always use mktemp -d to create the datadir. This guarantees the directory does not already exist (mktemp creates a new unique directory atomically). Never construct the path manually or use mkdir.
mktemp -d -t erigon-ephemeral
This uses the system's default temp directory (e.g., /var/folders/... on macOS, /tmp on Linux). Capture the output — that is the datadir path. Report the full path to the user so they know where data is stored.
If the user provides a source datadir path, clone it into an ephemeral directory using the erigon-datadir skill's Duplicating a Datadir procedure. Use mktemp -u to generate a unique path without creating it (so the erigon-datadir destination-not-exist precondition is satisfied):
mktemp -u -d -t erigon-ephemeral
Then follow the erigon-datadir skill with source=<user-provided-path> and destination=the generated path. It handles APFS detection, CoW cloning, precondition checks, and post-copy verification.
Never use default ports. Always start with offset +100 to avoid conflicts with any existing Erigon instance using defaults. Check the offset ports for conflicts:
lsof -nP -iTCP:<port> -sTCP:LISTEN 2>/dev/null
Also check UDP ports where applicable (torrent, devp2p, caplin discovery):
lsof -nP -iUDP:<port> 2>/dev/null
| CLI Flag | Default | +100 | +200 | +300 |
|---|---|---|---|---|
--private.api.addr | 127.0.0.1:9090 | 127.0.0.1:9190 | 127.0.0.1:9290 | 127.0.0.1:9390 |
--http.port | 8545 | 8645 | 8745 | 8845 |
--authrpc.port | 8551 | 8651 | 8751 | 8851 |
--ws.port | 8546 | 8646 | 8746 | 8846 |
--torrent.port | 42069 | 42169 | 42269 | 42369 |
--port | 30303 | 30403 | 30503 | 30603 |
--p2p.allowed-ports | 30303-30307 | 30403-30407 | 30503-30507 | 30603-30607 |
--caplin.discovery.port | 4000 | 4100 | 4200 | 4300 |
--caplin.discovery.tcpport | 4001 | 4101 | 4201 | 4301 |
--sentinel.port | 7777 | 7877 | 7977 | 8077 |
--beacon.api.port | 5555 | 5655 | 5755 | 5855 |
--mcp.port | 8553 | 8653 | 8753 | 8853 |
--pprof or --metrics in user's extra flags)| CLI Flag | Default | +100 | +200 | +300 |
|---|---|---|---|---|
--pprof.port | 6060 | 6160 | 6260 | 6360 |
--metrics.port | 6061 | 6161 | 6261 | 6361 |
When an offset is needed, construct the flags as follows (example for offset +100):
--private.api.addr=127.0.0.1:9190 \
--http.port=8645 \
--authrpc.port=8651 \
--ws.port=8646 \
--torrent.port=42169 \
--port=30403 \
--p2p.allowed-ports=30403,30404,30405,30406,30407 \
--caplin.discovery.port=4100 \
--caplin.discovery.tcpport=4101 \
--sentinel.port=7877 \
--beacon.api.port=5655 \
--mcp.port=8653
Note: --private.api.addr takes a full host:port value. --p2p.allowed-ports must list 5 consecutive ports starting from the base --port value.
Run Erigon in the background:
./build/bin/erigon --datadir=<path> [port flags if needed] [user extra flags] &
--chain=dev --beacon.api=beacon,validator,node,config,
--log.console.verbosity=4) which get appended to the command.\ continuation) before launching, so they can see exactly what is being run.run_in_background: true on the Bash tool so the process survives.When the user asks to stop/clean up:
pgrep -f <datadir-path>).rm -rf <datadir-path>.Note: Claude Code cannot automatically clean up on session exit. If the user closes the session without cleaning up, the datadir and process will remain. Use Step 6 to find and clean them up.
This step can be run independently at any time (the user does not need to be launching a new instance). Check for leftover ephemeral datadirs from previous sessions:
ls -d "$TMPDIR"erigon-ephemeral.* 2>/dev/null
If any are found:
du -sh).pgrep -f <dir-name>).If none are found, tell the user there are no leftovers.