EServer Integration Guide

What is EServer?

EServer (Execution Server) is a companion application for Circuitry that supercharges your workflows with:

• Native Python execution - 10-100x faster than browser-based execution
• Remote workflow execution - Run workflows on your desktop from your iPad, phone, or laptop
• File system access - Access files and folders on your computer through Circuitry
• Terminal access - Run terminal commands remotely from Circuitry
• GPU acceleration - Use your computer's GPU for AI and data science tasks
• Always available - Runs in the background, auto-starts on boot

Installation Options

EServer is available in three formats - choose the one that works best for you:

Option 1: Desktop Tray App (Recommended)

The easiest way to get started. Download the installer for your platform:

• macOS: DMG installer for Apple Silicon (M1-M5) or Intel Macs
• Windows: Universal installer for x64 and ARM64
• Linux: .deb packages (Debian/Ubuntu) or AppImage (universal)

Installation Steps:

1. Download the installer from Download Page
2. Install the application (drag to Applications on macOS, run installer on Windows/Linux)
3. Launch EServer - it appears as a tray icon in your menu bar/system tray
4. The server starts automatically and is ready to connect

Option 2: CLI Installation

Perfect for servers, headless machines, or if you prefer command-line tools:

macOS / Linux:

curl -fsSL https://circuitry.dev/install.sh | sh

Windows (PowerShell):

iwr -useb https://circuitry.dev/install.ps1 | iex

Usage:

# Start the server
eserver start

# Check status
eserver status

# Stop the server
eserver stop

# Update to latest version
eserver update

Option 3: Docker Container

Ideal for cloud deployments, Kubernetes, or containerized environments:

# Pull the image
docker pull johnwylie/eserver:latest

# Run the container
docker run -d -p 3030:3030 johnwylie/eserver:latest

See the Docker Documentation for advanced configuration, GPU passthrough, and cloud deployment guides.

Connecting Circuitry to EServer

Automatic Connection (Same Network)

EServer automatically advertises itself on your local network. Circuitry will detect it and show a connection notification.

On your computer:

1. Start EServer (tray app or CLI)
2. The server starts on port 3030 (or 3031-3039 if 3030 is busy)

On Circuitry (any device):

1. Open Circuitry in your browser
2. Click Settings (⚙️) → Models → Execution Server
3. Click "Connect" - Circuitry will auto-discover EServer
4. You'll see "Connected" with a green indicator and latency (e.g., "45ms")

Manual Connection (Cross-Network)

If you want to connect to EServer on a different network (e.g., cloud server, remote desktop):

Find your EServer IP:

• macOS/Linux: Run ifconfig and look for inet address
• Windows: Run ipconfig and look for IPv4 Address
• Example: 192.168.1.100

Connect from Circuitry:

1. Open Settings (⚙️) → Models → Execution Server
2. Uncheck "Auto-discover server"
3. Enter the URL: http://192.168.1.100:3030
4. Click "Test Connection" to verify
5. Click "Connect"

QR Code Connection (Mobile Devices & Docker/CLI)

The easiest way to connect your iPad, iPhone, or other devices to EServer:

Desktop Tray App (macOS/Windows/Linux)

On your computer:

1. Open EServer tray menu (click the tray icon in menu bar/system tray)
2. Click "Show QR Code"
3. A QR code appears with the connection URL

On your mobile device:

1. Open Circuitry in Safari/Chrome
2. Click the EServer indicator (⚡ icon) in the top-right corner
3. Click "Scan QR Code"
4. Point your camera at the QR code on your computer screen
5. Connection is automatically configured with a secure temporary key

Docker / CLI Installation

On your server (Docker, Linux, or remote machine):

# Start the server with network access
eserver config set server.allowNetworkAccess true
eserver start

# In another terminal, generate QR code
eserver qr

You'll see an ASCII QR code displayed in the terminal with connection details.

On your iPad/iPhone/Android:

1. Open the Circuitry app
2. Click the EServer indicator (⚡ icon) in the top-right corner
3. Click "Scan QR Code"
4. Point your camera at the QR code in the terminal
5. Connection is automatically configured with a secure temporary key

Benefits:

• No manual IP address or port entry
• Automatic secure key generation
• Works across your local network
• Each device can connect to multiple EServers

Running Python Workflows on EServer

Enable EServer for Python Nodes

Once connected, you can run Python code nodes on EServer for massive performance gains:

Per-Node Setting:

1. Select a Code node in your workflow
2. Set the language to "Python"
3. Click the "Configure Node" icon (⚙️ gear icon on the node)
4. In the node configuration panel, you'll see a green box: "Execute on server"
5. Enable the checkbox to run this node on EServer
6. If you have multiple EServers connected, a dropdown appears where you can select which server to use for this specific node
7. Run the workflow - Python executes on your selected server at native speed

Multiple Server Support:

• Each Code node can use a different EServer
• Great for distributed workflows (e.g., one server with GPU for ML, another for file processing)
• Server selection is saved per-node in the workflow
• If a selected server is offline, the workflow will show an error

Default Setting (All New Python Nodes):

1. Open Settings (⚙️) → Models → Execution Server
2. Enable "Use EServer by default for Python"
3. All new Python nodes will automatically use EServer
4. You can still toggle per-node if needed

Performance Comparison

Here's what you can expect:

When to use EServer:

• Data science and machine learning
• Large dataset processing
• Complex calculations
• GPU-accelerated tasks
• When you need access to pip packages

When to use browser (Pyodide):

• Simple scripts
• Working offline on iPad
• Don't have EServer installed
• Basic calculations

Accessing Files with Circuitry

EServer gives Circuitry access to your computer's file system:

File Browser

1. Open Circuitry
2. Click the File Browser icon (📁)
3. You can now:
   • Browse your computer's files and folders
   • Read file contents
   • Upload files to your computer
   • Download files from your computer
   • Create new folders

Supported file types:

• CSV, JSON, XML - Auto-preview with syntax highlighting
• Images (PNG, JPG, GIF) - Inline preview
• Text files (.txt, .md, .log) - Full-text display
• Code files (.py, .js, .ts) - Syntax highlighting

Using Files in Workflows

Read a file:

1. Add a File node to your workflow
2. Click "Browse" and select a file from EServer
3. The file path is stored in the node
4. When the workflow runs, EServer reads the file and passes content to the next node

Write a file:

1. Add a File Output node to your workflow
2. Specify the output path (e.g., /Users/you/Desktop/output.csv)
3. Connect a data source (e.g., DataGrid, Code node output)
4. When the workflow runs, EServer writes the file to your computer

Accessing Terminals

Run terminal commands on your computer from anywhere:

Opening a Terminal

1. Click the Terminal icon (⌨️) in Circuitry
2. Select EServer as the connection
3. You now have a full shell on your computer:
   • macOS/Linux: bash or zsh
   • Windows: PowerShell or cmd

Terminal in Workflows

Add terminal execution to your workflows:

Terminal Node:

1. Add a Terminal node to your workflow
2. Enter the command (e.g., ls -la, git status)
3. Choose EServer as the executor
4. When the workflow runs, the command executes on your computer
5. The output (stdout/stderr) is passed to the next node

Use Cases:

• Run git commands
• Execute build scripts
• Process files with system tools
• Monitor system resources
• Automate system administration

Compute Node Features

EServer unlocks advanced compute capabilities:

GPU Acceleration

If your computer has a GPU (NVIDIA, AMD, or Apple Silicon), EServer can use it:

Check GPU status:

1. Open Settings → Models → Execution Server
2. Look at "Server Capabilities"
3. GPU Available: Yes/No
4. GPU Name: e.g., "NVIDIA RTX 3080" or "Apple M1 Max"

Use GPU in Python:

import torch

# PyTorch will automatically use GPU if available
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(f"Using device: {device}")

# Your ML code here
model = model.to(device)

Multiple EServers

You can connect to multiple EServers and distribute work:

Setup:

1. Install EServer on multiple computers (e.g., gaming PC, Mac, Linux server)
2. Each EServer gets a different port or IP address
3. Add all connections in Circuitry Settings

Usage:

• Select which EServer to use per-node
• Run different parts of your workflow on different machines
• Load-balance heavy compute tasks
• Use the machine with the best GPU for ML tasks

Parallel Execution

EServer supports true parallel execution:

Fork/Join Pattern:

1. Add a Fork node to split the workflow into branches
2. Each branch can run on a different EServer
3. Add a Join node to merge results
4. All branches execute simultaneously

Example:

Start → Fork → [Branch 1: Python on Mac]
            ↓  [Branch 2: Python on PC with GPU]
            ↓  [Branch 3: Python on Cloud Server]
            → Join → Combine Results → End

Connection Settings

Auto-Discovery

How it works:

• EServer broadcasts its presence on ports 3030-3039
• Circuitry scans these ports when you click "Connect"
• Works on same WiFi network or local network

Enable/Disable:

1. Settings → Models → Execution Server
2. Toggle "Auto-discover server"
3. When disabled, you must enter the URL manually

Manual URL

Format:

• http://localhost:3030 - Same computer
• http://192.168.1.100:3030 - Local network
• http://your-server.com:3030 - Remote server

Custom Port: If EServer runs on a different port:

• http://localhost:3035 (ports 3030-3039 are tried automatically)

Connection Health

Circuitry monitors the connection:

• Latency: Shown next to "Connected" (e.g., "45ms")
• Status: Green = good, Yellow = slow, Red = disconnected
• Auto-reconnect: If connection drops, Circuitry tries to reconnect automatically

Troubleshooting

Can't Connect to EServer

Check EServer is running:

• macOS: Look for EServer icon in menu bar
• Windows: Look for EServer in system tray
• Linux: Run eserver status in terminal

Check the port:

• Default: 3030
• EServer console shows which port it's using
• Try: curl http://localhost:3030/ping

Check firewall:

• macOS: System Settings → Network → Firewall → Allow EServer
• Windows: Windows Defender Firewall → Allow EServer
• Linux: sudo ufw allow 3030

Check network:

• Same WiFi network? (for auto-discovery)
• Correct IP address? (for manual connection)

Python Not Executing on EServer

Verify toggle is enabled:

• Code node → Config panel → "Execute on EServer" must be checked

Check connection:

• Settings → Execution Server → Must show "Connected" in green

Check logs:

• Browser console (F12 → Console) shows execution errors
• EServer logs (Tray menu → View Logs) shows server-side errors

Try fallback:

• Uncheck "Execute on EServer"
• Workflow will use browser-based Python (slower but always works)

Files Not Accessible

Check permissions:

• EServer needs read/write permissions to the folder
• macOS: System Settings → Privacy → Files and Folders → EServer
• Windows: Run EServer as Administrator
• Linux: Check file ownership and permissions

Check path:

• Use absolute paths: /Users/you/file.txt not ~/file.txt
• Windows: Use forward slashes: C:/Users/you/file.txt

Terminal Commands Fail

Check shell:

• EServer uses the system default shell
• macOS/Linux: bash or zsh
• Windows: PowerShell

Check path:

• Commands must be in PATH
• Use full path: /usr/bin/python3 not just python3

Check permissions:

• Some commands need sudo (not recommended in workflows)

Security Considerations

Local Network

EServer runs on your local network without authentication. This is safe if:

• You trust everyone on your WiFi network
• You're using it at home or on a private network
• Firewall is enabled and configured

Remote Access

If you expose EServer to the internet:

• Use a VPN - Don't expose port 3030 directly to the internet
• Use SSH tunnel - ssh -L 3030:localhost:3030 user@server
• Authentication - Future versions will support API keys
• HTTPS - Use a reverse proxy (nginx, Caddy) with SSL

Code Execution

EServer executes arbitrary code:

• Only run workflows you trust
• Be careful with code from unknown sources
• Review Python code before executing
• Use environment variables for secrets (don't hardcode API keys)

Advanced Configuration

Environment Variables

Set environment variables that all workflows can access:

In Circuitry:

1. Settings → Environment Variables
2. Add variables (e.g., API_KEY, DATABASE_URL)
3. Scope: Global or per-project
4. These are passed to EServer when executing Python

In Python:

import os

api_key = os.environ.get('API_KEY')
db_url = os.environ.get('DATABASE_URL')

Custom Python Packages

Install packages on EServer that Circuitry can use:

CLI Method:

# SSH into the machine running EServer
pip3 install pandas numpy scikit-learn tensorflow

Docker Method:

FROM johnwylie/eserver:latest
RUN pip3 install pandas numpy scikit-learn tensorflow

Verify:

# In a Circuitry Code node
import pandas as pd
import numpy as np
print(pd.__version__, np.__version__)

MCP Proxy (Advanced)

EServer can act as a Model Context Protocol (MCP) proxy:

Enable in EServer:

• This is automatically enabled when EServer starts
• Allows Circuitry to use MCP tools through EServer
• Useful for accessing local MCP servers from remote devices

What's Next?

• EServer CLI Documentation - Complete CLI reference
• Docker Deployment Guide - Cloud deployment, GPU, Kubernetes
• Python Support - Writing Python code in Circuitry
• Workflow Executor - How workflows execute

Getting Help

• Documentation: Docs Home
• Support: Contact support through the app settings