Complete Setup Guide

From unboxing to your
first crab reaction.

Six steps. About five minutes. Zero terminal commands beyond a single copy-paste. By the end, your AI coding agent will be reflected on a physical e-paper display sitting next to your keyboard.

~5 min total
Browser only
No SDK required
Start with Step 1 Flash Firmware
Prerequisites

What you'll need

EleksCava e-paper device — ESP32-based hardware with 2.9" display, RGB LED, and 3 buttons.
USB-C cable that supports data transfer — not a charge-only cable.
Chrome 89+ or Edge 89+ on a desktop computer — required for Web Serial flashing.
WiFi credentials — your home or office 2.4 GHz network name and password.
An AI coding assistant — Claude Code, Cursor, Codex, Aider, or any tool that supports hooks.
A phone (optional but helpful) — for the captive-portal WiFi setup in Step 3.
The Six Steps

Setup walkthrough

STEP 01

Flash the firmware

Plug your EleksCava device into your computer with USB-C and head to the web installer. ESP Web Tools handles everything in the browser — no drivers to install, no SDK to download, no command line.

Open Web Installer
If the installer can't see your device, check our flash page FAQ — most issues are missing CH340 drivers or charge-only cables.
STEP 02

Power on & spot the welcome screen

After flashing finishes, the device reboots automatically. You should see the InksPet welcome screen:

  • The pixel-art crab appears on the e-paper display
  • The RGB LED pulses white in idle mode
  • The bottom of the screen shows SETUP MODE

The device has now started its own WiFi hotspot named InksPet_XXXX (where XXXX is the last 4 hex digits of its MAC address).

STEP 03

Connect to your WiFi via captive portal

Take out your phone (or laptop) and join the device's hotspot:

  1. Open WiFi settings and connect to InksPet_XXXX
  2. Your phone should automatically open a captive portal. If it doesn't, open a browser and visit http://192.168.4.1
  3. Pick your home WiFi network from the list
  4. Enter the password and tap Connect

The device will save your credentials, leave AP mode, and reboot into normal mode. The LED switches from white to a slow green breathing pulse — that's the "ready, waiting for an agent" state.

2.4 GHz only. The ESP32 does not support 5 GHz WiFi. If your router broadcasts both bands under the same SSID this is usually fine, but if you have separate 2.4/5 GHz SSIDs, pick the 2.4 GHz one.
STEP 04

Open the dashboard

From any computer on the same network, open a browser and visit:

http://inkspet.local

You should see the InksPet web dashboard — a real-time view of agent state, tool call statistics, and a Hook Setup button. If inkspet.local doesn't resolve (older Windows / corporate networks sometimes block mDNS), check the bottom of the device's e-paper screen — it shows the assigned IP address. Use that instead:

http://192.168.0.63 ← whatever IP your device shows
STEP 05

Hook setup — copy & paste one prompt

On the dashboard, click the Hook Setup button. A dialog opens with an auto-generated prompt that contains:

  • Your device's local IP and hook endpoint
  • Step-by-step instructions for the AI to install the hooks
  • A verification command to confirm the connection

Click Copy, then paste the entire prompt into your AI coding assistant (Claude Code, Cursor, Aider, etc.). The agent will read your project's hook config file, add the InksPet entries, and tell you when it's done.

"Add InksPet hooks to my Claude Code config so it sends events to http://192.168.0.63/hook"
The auto-generated prompt is project-specific — it includes the absolute path to your hook config file, so you don't need to know where Claude Code stores its settings.
STEP 06

Verify your crab reacts

Time to test it. Ask your AI assistant to do something simple, like:

"Read the README and tell me what this project does"

Watch the device. You should see, in this order:

  • Crab transitions to Thinking state — LED breathes blue
  • Crab transitions to Working state when the agent calls a tool — LED solid green
  • Tool call counter increments at the bottom of the screen
  • Crab transitions to Completed state when the agent finishes — LED fades out

Try a command that triggers a permission prompt, too — the screen will switch to a full-width PERMISSION REQUEST layout, the LED will flash yellow, and you can press A / B / C on the device to approve / always-allow / deny without touching your keyboard.

✓ Success looks like this

  • Dashboard loads at http://inkspet.local and shows the device as Online
  • Crab changes state in real time when your AI assistant runs tools
  • LED color matches the agent state — blue for thinking, green for working, yellow for permission, red for errors
  • Physical buttons work — pressing A on a permission screen approves the tool call
  • Tool call counter increments at the bottom of the e-paper display as the agent works
Troubleshooting

When something doesn't work

  • The hotspot only appears on first boot after flashing, or after a factory reset. If you already configured WiFi once, the device skips AP mode.
  • To force the device back into setup mode, long-press button C for 5 seconds — the screen will show SETUP MODE and the hotspot will appear.
  • Make sure your phone is searching for 2.4 GHz networks. Some phones hide them by default.
  • The hotspot name format is exactly InksPet_ followed by 4 hex characters (e.g. InksPet_3F2A).

mDNS (the technology behind .local names) can be blocked by older Windows builds, corporate firewalls, and some routers with mDNS reflection disabled.

The fix: look at the bottom of the e-paper screen — the device prints its IP address on every boot. Open http://<that-ip> directly in your browser and bookmark it.

You can also assign a static DHCP lease to the device's MAC address in your router admin panel so the IP never changes.

  • Open the dashboard and check the Live Events panel. If you see hooks arriving but no state changes, restart the device once.
  • If no events at all are arriving, the hook config didn't install correctly. Re-run the Hook Setup prompt and ask your AI assistant to verify with: "Show me the current InksPet hook config and run a test".
  • Make sure your AI assistant and the device are on the same WiFi network. The hook URL uses a local IP, so a VPN or guest network can break it.
  • Check the firewall on your computer — some corporate setups block outgoing requests to local IPs.

Two options:

  • Soft reset — long-press all three buttons (A + B + C) for 10 seconds. This clears WiFi credentials and hook config but keeps the firmware.
  • Hard reset — re-flash the firmware from the web installer. This wipes everything including the SPIFFS partition and gives you a guaranteed clean state.

Yes. Install the InksPet hooks in each assistant's config — they all post to the same local endpoint. When more than one agent is active, the crab enters Juggling (1 subagent, purple breathing) or Conducting (2+ subagents, purple solid) state automatically.

The dashboard tags each event with the originating agent name so you can see who's doing what.

  • Confirm you're actually in Permission state — the screen layout changes to a full-width "PERMISSION REQUEST" view and the LED flashes yellow.
  • Some AI assistants don't expose hook callbacks for permission responses. Check the compatibility matrix for your tool.
  • If buttons feel unresponsive in general, hold each one for half a second — the firmware debounces input.

All set?

Your crab is alive. From here you can customize LED brightness, agent nicknames, and idle behavior from the dashboard's Settings tab.

Back to Home Open Source on GitHub