Ethui Stacks

A self-hosted, open-source API for web3 stacks.

Warning

This repo is freshly published. Maintenance is ongoing, and bugs are expected.

ethui Stacks can be used either locally or remotely, to provide teams with a full-features tech stack for web3 development:

• anvil node
• subgraph deployment
• IPFS
• explorer

Use it to:

• avoid the boilerplate of setting up full-stack development for web3 projects
• set up a private or public testnet for your projects
• create a shared environment without all the hassles fo public testnets

Project Structure

This monorepo contains:

• server/ - Elixir/Phoenix API server
• frontend/ - React/TypeScript frontend application
• bruno/ - API testing collection

Running locally

Server (API)

cd server
mix setup              # Install dependencies
mix ecto.create        # Create database
mix ecto.migrate       # Run migrations
mix phx.server         # Start server

Or use the setup script:

npm run setup          # Install deps + setup database
npm run dev:server     # Start server

Frontend

cd frontend
npm install
npm run dev

Docker (Full Stack)

docker build -t ethui-stacks .

docker run -v $HOME/.config/ethui/stacks/local:$HOME/.config/ethui/stacks/local -e DATA_ROOT=$HOME/.config/ethui/stacks/local -v /var/run/docker.sock:/var/run/docker.sock --init -p 4000:4000 --name=ethui-stacks ethui-stacks

Running hosted service

Warning

Soon available at https://stacks.ethui.dev

How to use

1. Create a new stack

curl -X POST -d '{"slug": "foo"}' http://api.local.ethui.dev:4000/stacks

2. Access individual services via their subdomain

• http://foo.local.ethui.dev (anvil node)
• http://graph-foo.local.ethui.dev (subgraph queries)
• http://graph-rpc-foo.local.ethui.dev (subgraph RPC client)
• http://ipfs-foo.local.ethui.dev (IPFS)
• http://foo.local.ethui.dev (explorer)

MCP

The server speaks MCP over streamable HTTP at /mcp on the api host, so an agent can provision sandboxes, drive them and hand back explorer links a human can open.

1. Get a token

Authentication is the same JWT as the REST api. The code arrives by email:

curl -X POST https://api.stacks.ethui.dev/auth/send-code \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com"}'

curl -X POST https://api.stacks.ethui.dev/auth/verify-code \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","code":"123456"}'
# -> {"token":"eyJ..."}

2. Add the server

Claude Code:

claude mcp add --transport http --scope user ethui-stacks \
  https://api.stacks.ethui.dev/mcp \
  --header "Authorization: Bearer eyJ..."

--scope user makes it available in every project; drop it to add the server to the current one only. Check it with claude mcp list, then restart Claude Code — MCP servers are loaded when a session starts.

Claude Desktop, and other clients that take JSON:

{
  "mcpServers": {
    "ethui-stacks": {
      "type": "http",
      "url": "https://api.stacks.ethui.dev/mcp",
      "headers": { "Authorization": "Bearer eyJ..." }
    }
  }
}

The token sits in that config in plaintext. Claude Code expands environment variables, so "Bearer ${ETHUI_STACKS_TOKEN}" works if you would rather keep it out of the file.

Point url at your own instance to use a self-hosted Stacks. Running without ETHUI_STACKS_SAAS disables authentication entirely, so the header can be dropped locally.

Tools

• lifecycle: create_stack list_stacks delete_stack
• reads: get_block get_transaction get_address get_logs
• writes: simulate_call execute — raw calldata, from is impersonated so no key is needed
• cheatcodes: impersonate set_balance mine set_block_timestamp snapshot revert

ABI encoding and decoding are deliberately out of scope: calldata goes in raw, so the caller stays free to use cast, viem, or whatever it already has.