Circuit

What is Circuit?

Circuit 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 or laptop
• Home Circuit — remote access - Reach this computer's terminals, coding agents and files from anywhere, not just your home network. See Home Circuit
• Parallel cluster compute - Connect several machines into a compute cluster and run each code node on a different server — ideal for data science and large parallel jobs. See Compute Clusters
• 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

Do I need it?

It depends on how you use Circuitry:

• Circuitry Desktop (macOS/Windows/Linux) — you don't need Circuit. Native execution, file access, and terminals are built into the desktop app. Install Circuit only on other machines you want to add as extra compute nodes.
• iPad and web — install Circuit on your computer to work on the files and projects stored there, and to use that computer as a compute node for native Python, GPU, and terminal access.
• Away from home? — turn on Home Circuit and this computer stays reachable from your iPad or phone wherever you are — switching between your local network and the internet automatically.
• No computer of your own? — use a Cloud Circuit instead. Circuitry runs a Linux machine for you, so you get a terminal, files and somewhere to run code without installing anything. Available on paid plans.
• Everyone — add Circuit on as many additional machines as you like to build a compute cluster: a workflow with parallel Python nodes can run each node on a separate machine. See Compute Clusters.

Installation Options

The desktop tray app is available now. CLI and Docker installs are coming soon.

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)

Downloading:

1. Sign in at circuitry.dev and open your dashboard
2. Click the Downloads card (or go directly to the Download Page — you'll be asked to sign in)
3. The page detects your platform and offers the matching installer. Downloads require a plan that includes the desktop apps (Personal and up)

Installing:

• macOS: Open the downloaded DMG and drag Circuit to Applications, then launch it from Applications
• Windows: Run the downloaded installer and follow the prompts
• Linux: Install the package for your distribution — sudo dpkg -i <file>.deb (Debian/Ubuntu), sudo rpm -i <file>.rpm (Fedora/RHEL), or make the AppImage executable (chmod +x <file>.AppImage) and run it

First Launch:

1. Launch Circuit - it appears as a tray icon in your menu bar/system tray
2. The server starts automatically and is ready to connect
3. Open at Login is enabled by default so Circuit starts automatically on reboot

Open at Login:

• Enabled by default on first launch - Circuit starts automatically when you log in
• Toggle via the tray menu: click the tray icon → Open at Login (checkbox)
• Uses native platform APIs: macOS Login Items, Windows Registry, Linux XDG autostart
• Disable if you prefer to start Circuit manually

Option 2: CLI Installation — Coming soon

A command-line installer for servers and headless machines is on the way. For now, use the Desktop Tray App (Option 1).

Option 3: Docker Container — Coming soon

A Docker image for cloud, Kubernetes, and containerized deployments is on the way. For now, use the Desktop Tray App (Option 1).

Connecting to Circuit

Automatic Connection (Same Network)

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

On your computer:

1. Start Circuit (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 → Circuit
3. Click "Connect" - Circuitry will auto-discover Circuit
4. You'll see "Connected" with a green indicator and latency (e.g., "45ms")

Manual Connection (Cross-Network)

If you want to connect to Circuit on a different network (e.g., Cloud Circuit, remote desktop):

Find your Circuit 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 → Circuit
2. Uncheck "Auto-discover server"
3. Enter the URL: http://192.168.1.100:3030
4. Click "Test Connection" to verify
5. Click "Connect"

Remote Access with Home Circuit

The connections above work on your local network. Home Circuit keeps this computer reachable when you leave it behind — at a café with your iPad, or away from the office.

1. In Circuitry, open the server menu in the top bar and choose Home Circuit
2. Follow the three steps — it ticks each one off as it's done
3. On the computer, click the Circuit icon and turn on Allow Remote Connections

Your devices then switch between the local network and Home Circuit automatically, always preferring the local network when you're home. It isn't screen sharing — Circuitry talks to your machine directly over an end-to-end encrypted connection, and only devices you paired in person can connect. Full details, including the security model: Home Circuit.

QR Code Connection (Mobile Devices & Docker/CLI)

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

Desktop Tray App (macOS/Windows/Linux)

On your computer:

1. Open Circuit 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 Circuit 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 Circuit 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 Circuits

Running Python Workflows on the Server

Enable Circuit for Python Nodes

Once connected, you can run Python code nodes on Circuit 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 Circuit
6. If you have multiple Circuits 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 Circuit
• 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 → Circuit
2. Enable "Use Circuit by default for Python"
3. All new Python nodes will automatically use Circuit
4. You can still toggle per-node if needed

Performance Comparison

Here's what you can expect:

When to use Circuit:

• 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 Circuit installed
• Basic calculations

Accessing Files with Circuitry

Circuit 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 Circuit
3. The file path is stored in the node
4. When the workflow runs, Circuit 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, Circuit 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 Circuit 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 Circuit 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

Circuit unlocks advanced compute capabilities:

GPU Acceleration

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

Check GPU status:

1. Open Settings → Models → Circuit
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 Circuits

You can connect to multiple Circuits and distribute work:

Setup:

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

Usage:

• Select which Circuit 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

Circuit supports true parallel execution — connect several machines into a compute cluster and spread the work across them. This is ideal for data science and large parallel jobs: fan a dataset out across machines, run native Python (and GPU) on each, and merge the results. See Compute Clusters for connecting and routing across servers.

Fork/Join Pattern:

1. Add a Fork node to split the workflow into branches
2. Each branch can run on a different Circuit
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 Circuit]
            → Join → Combine Results → End

Connection Settings

Auto-Discovery

How it works:

• Circuit 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 → Circuit
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 Circuit 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 Circuit

Check Circuit is running:

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

Check the port:

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

Check firewall:

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

Check network:

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

iPhone or iPad Can't Connect (Local Network Permission)

On iPhone and iPad, an app must be granted Local Network access before it can reach Circuit on your computer. When that permission is missing, iOS reports it as "The Internet connection appears to be offline" — even though your Wi-Fi is fine. That message is misleading, and it is the most common cause of a phone or tablet that won't pair.

First check: Settings → Privacy & Security → Local Network → is Circuitry listed and switched on?

• Listed but off — turn it on, then reopen Circuitry.
• Listed and already on, but still failing — switch it off and on again, fully close Circuitry, and reopen it.
• Not listed at all — iOS believes it has already asked, so it never prompts.

If it still fails, delete Circuitry and reinstall it. A fresh install has no stale permission record and asks properly the first time it needs the network. Your documents and projects are not stored on the device alone, so nothing is lost.

Signs it is this and not your network:

• Other apps and websites work normally on the same Wi-Fi.
• Safari on the same device can load http://<your-computer-ip>:3030/ping — Safari is exempt from this permission, so if Safari works and Circuitry doesn't, it is the permission and not your network.
• The failure is instant rather than a slow timeout.

Running a development build from Xcode? There is one more cause. iOS ties this permission to the app's signing identity, so a build signed against a wildcard provisioning profile can never hold the permission you grant it — Settings shows it switched on while the system refuses every request, and no amount of reinstalling, rebooting or resetting privacy will help. Register a real App ID for the bundle identifier and rebuild. App Store builds are never affected.

Pairing QR Code Expired

Each pairing QR code is valid for about five minutes, and Circuit replaces it automatically when it lapses. If setting up takes a while — granting permissions, say — the code you scanned may already be dead by the time you retry. Show the QR code again and scan the fresh one rather than retrying the old scan.

Circuit Frozen or Unresponsive

If the tray icon stops responding — the menu won't open, or Stop/Quit do nothing — the app itself is frozen. This is rare, but can happen when the whole system runs out of memory (for example while running large local AI models): the operating system suspends background apps, and because Circuit runs as a background tray app it may not appear in the macOS "Force Quit" or out-of-memory dialogs.

A frozen app ignores a normal Quit, so force-stop it from a terminal and relaunch:

macOS (Terminal):

pkill -9 -f "Circuit"
open -a "Circuit"

Windows (PowerShell or Command Prompt):

taskkill /F /IM "Circuit.exe"

Then relaunch Circuit from the Start menu.

Linux:

pkill -9 -f circuitry-eserver
circuitry-eserver &

You can also force-quit it from Activity Monitor (macOS) or Task Manager (Windows) — search for "Circuit". Circuitry reconnects automatically once the server is back up.

Python Not Executing on Circuit

Verify toggle is enabled:

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

Check connection:

• Settings → Circuit → Must show "Connected" in green

Check logs:

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

Try fallback:

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

Files Not Accessible

Check permissions:

• Circuit needs read/write permissions to the folder
• macOS: System Settings → Privacy → Files and Folders → Circuit
• Windows: Run Circuit 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:

• Circuit 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

Circuit 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 Circuit 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

Circuit 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 Circuit 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 Circuit that Circuitry can use:

CLI Method:

# SSH into the machine running Circuit
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)

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

Enable in Circuit:

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

Multi-Client Support: When multiple Circuitry clients (iPad, browser, Electron) are connected to Circuit, MCP connection requests are broadcast to all clients. The first client to approve binds the MCP session to that client. See Multi-Client Connection Behavior for details.

What's Next?

• Circuit 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