Connecting to dev server...

Circuitry Logo
Circuitry
Open Editor

EServer Command-Line Interface

Overview

The EServer CLI provides complete command-line management for Circuitry Execution Server on headless servers and systems without a graphical interface. Perfect for Linux server administrators, Docker deployments, and remote management via SSH.

Installation

Quick Install (Recommended)

macOS / Linux:

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

Windows (PowerShell):

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

This will:

  • Download the latest EServer CLI
  • Install to /usr/local/lib/eserver (macOS/Linux) or %ProgramFiles%\EServer (Windows)
  • Add eserver command to your PATH
  • Verify installation

Manual Installation

Download the appropriate installer for your platform from circuitry.dev/download.

After installing EServer from the installer package, the eserver command will be available in your PATH.

Verify Installation

eserver --version

Quick Start

  1. View Available Commands

    eserver --help

    Shows all available commands and options.

  2. Generate Access Key

    eserver keys create "My Device"

    Save the displayed API key - you'll need it for authentication.

  3. Start Server

    eserver start

  4. Check Status

    eserver status

  5. Generate QR Code (for mobile devices)

    eserver qr

Command Reference

Getting Help

All commands support the --help flag to display usage information:

# General help
eserver --help

# Help for specific commands
eserver start --help
eserver config --help
eserver keys --help
eserver service --help

Common options available on most commands:

  • -c, --config <path> - Specify custom config file path
  • --help - Display help for the command
  • --version - Display EServer version

Server Management

eserver start

Start the execution server.

eserver start [options]

Options:
  -c, --config <path>    Config file path (default: ~/.johnwylie/eserver-config.json)

Example:

eserver start
# Server running on localhost:3030
# Press Ctrl+C to stop

eserver status

Show current server status, statistics, and health.

eserver status [options]

Options:
  -c, --config <path>    Config file path

Output:

āœ“ Server is RUNNING

Server Information:
  Address:         0.0.0.0:3030
  Uptime:          2h 15m
  Python:          3.13.0 (native)

Statistics:
  Total Executions:     142
  Successful:           138
  Failed:               4
  Current Executions:   0
  Avg Execution Time:   45ms

eserver info

Show Python runtime information and capabilities.

eserver info

Configuration Management

eserver config show

Display current server configuration.

eserver config show [options]

Options:
  -c, --config <path>    Config file path

eserver config set <key> <value>

Set configuration value.

eserver config set <key> <value> [options]

Options:
  -c, --config <path>    Config file path

Examples:
  eserver config set server.port 3030
  eserver config set server.allowNetworkAccess true
  eserver config set execution.maxExecutionTime 300000

Common Configuration Keys:

  • server.port - Server port (default: 3030)
  • server.allowNetworkAccess - Allow network access (default: false)
  • server.maxConcurrentExecutions - Max concurrent executions (default: 5)
  • cors.enabled - Enable CORS (default: true)
  • cors.allowAllOrigins - Allow all origins (default: false)
  • execution.maxExecutionTime - Max execution time in ms (default: 300000)

Access Key Management

eserver keys list

List all access keys (without exposing the actual keys).

eserver keys list

Output:
  abc123
    Name:        My Device
    Created:     2025-01-15 10:30:00
    Last Used:   2025-01-15 14:20:00

eserver keys create <name>

Generate new access key.

eserver keys create <name>

Example:
  eserver keys create "Production Server"

Output:
  Key ID:     abc123
  Name:       Production Server
  Key:        es_a1b2c3d4e5f6g7h8...

  āš  Save this key - it will not be shown again!

eserver keys show <keyId>

Show access key details (including full key).

eserver keys show <keyId>

Example:
  eserver keys show abc123

eserver keys revoke <keyId>

Revoke access key.

eserver keys revoke <keyId> [options]

Options:
  -f, --force    Skip confirmation

Example:
  eserver keys revoke abc123 --force

Device Connection

eserver qr

Generate QR code for easy mobile device connection.

Displays an ASCII QR code in your terminal that mobile devices (iPad, iPhone, Android) running Circuitry can scan to automatically connect to this EServer. The QR code contains the server's IP address, port, and a temporary secure access key - no manual configuration needed.

eserver qr [options]

Options:
  -c, --config <path>    Config file path

How to use:

  1. Run eserver qr in your terminal on the server
  2. On your iPad/iPhone, open Circuitry
  3. Click the EServer indicator (āš” icon) in the top-right
  4. Tap "Scan QR Code"
  5. Point your camera at the QR code in the terminal
  6. Connection is automatically configured

Output:

šŸ“± EServer Connection QR Code

ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ
ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ
ā–ˆā–ˆā–ˆ ā–„ā–„ā–„ā–„ā–„ ā–ˆā–€ā–ˆ ā–ˆā–„ā–„ā–€ā–ˆ ā–„ā–„ā–„ā–„ā–„ ā–ˆā–ˆā–ˆ
ā–ˆā–ˆā–ˆ ā–ˆ   ā–ˆ ā–ˆā–€ā–€ā–€ā–ˆā–„ā–ˆ ā–ˆ ā–ˆ   ā–ˆ ā–ˆā–ˆā–ˆ
ā–ˆā–ˆā–ˆ ā–ˆā–„ā–„ā–„ā–ˆ ā–ˆā–€ ā–ˆā–€ā–€ā–„ā–€ā–ˆ ā–ˆā–„ā–„ā–„ā–ˆ ā–ˆā–ˆā–ˆ
...

ā„¹ Server Address: http://192.168.1.100:3030

āš  This QR code expires in 5 minutes

Scan with your mobile device to automatically connect

Perfect for:

  • Connecting iPads/iPhones to Docker/CLI EServer instances
  • Quick setup without typing IP addresses or keys
  • Temporary access for testing or demos
  • Connecting multiple devices quickly

Logs

eserver logs

Show server logs.

eserver logs [options]

Options:
  -c, --config <path>    Config file path
  -n, --tail <lines>     Number of lines to show (default: 50)

Example:

eserver logs --tail 100

System Service Management

eserver service install

Install EServer as a system service (requires root/sudo).

sudo eserver service install [options]

Options:
  --exec-path <path>      Path to eserver executable (default: /usr/local/bin/eserver)
  --user <user>           Run as user (Linux, default: eserver)
  --group <group>         Run as group (Linux, default: eserver)
  --working-dir <path>    Working directory (Linux, default: /var/lib/eserver)
  --config-path <path>    Config file path
  --name <name>           Service name (Linux, default: eserver)
  --label <label>         Service label (macOS, default: ai.cognaris.circuitry.eserver)

Linux (systemd):

sudo eserver service install

# Output:
# āœ“ Systemd service installed: /etc/systemd/system/eserver.service
# āœ“ Working directory: /var/lib/eserver
# āœ“ Config path: /etc/eserver/config.json
#
# Next steps:
#   sudo systemctl enable eserver  # Enable auto-start on boot
#   sudo systemctl start eserver   # Start the service now
#   sudo systemctl status eserver  # Check service status

macOS (launchd):

eserver service install

# Output:
# āœ“ Launchd service installed: ~/Library/LaunchAgents/ai.cognaris.circuitry.eserver.plist
# āœ“ Config path: ~/.johnwylie/eserver-config.json
#
# Service commands:
#   launchctl start ai.cognaris.circuitry.eserver
#   launchctl stop ai.cognaris.circuitry.eserver

eserver service uninstall

Uninstall system service (requires root/sudo).

sudo eserver service uninstall [options]

Options:
  --name <name>     Service name (Linux, default: eserver)
  --label <label>   Service label (macOS)

eserver service status

Show service status.

eserver service status [options]

Options:
  --name <name>    Service name (default: eserver)

Usage Examples

First-Time Setup (Linux Server)

# 1. Create access key
eserver keys create "Production API"
# Save the displayed key

# 2. Configure for network access
eserver config set server.allowNetworkAccess true
eserver config set server.port 3030

# 3. Start server to test
eserver start

# 4. In another terminal, check status
eserver status

# 5. Install as system service
sudo eserver service install

# 6. Enable and start service
sudo systemctl enable eserver
sudo systemctl start eserver

# 7. Check service status
sudo systemctl status eserver

Docker Deployment

FROM ubuntu:22.04

# Install Python 3.11+
RUN apt-get update && apt-get install -y python3 python3-pip

# Copy EServer files
COPY circuitry-eserver /usr/local/bin/eserver
RUN chmod +x /usr/local/bin/eserver

# Create config directory
RUN mkdir -p /etc/eserver

# Set up config
RUN eserver config set server.port 3030
RUN eserver config set server.allowNetworkAccess true

# Generate initial access key
RUN eserver keys create "Docker Container" > /etc/eserver/initial-key.txt

# Expose port
EXPOSE 3030

# Start server
CMD ["eserver", "start", "--config", "/etc/eserver/config.json"]

Connecting iPad/iPhone to EServer

This is the easiest way to connect your iPad or iPhone to a Docker/CLI EServer instance.

  1. On your server (Docker, Linux, or macOS), start server with network access:

    eserver config set server.allowNetworkAccess true
eserver start

  2. In another terminal, generate QR code:

    eserver qr

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

  3. On your iPad/iPhone:

    • Open the Circuitry app
    • Open a workflow with a Code node
    • Change the language to Python
    • Click the "Configure Node" icon (gear icon on the node)
    • In the node configuration panel, click "EServer Settings"
    • Tap "Scan QR Code"
    • Point your camera at the QR code in the terminal
    • Connection is automatically configured with a secure temporary key

  4. Using the connection:

    • The EServer now appears in your available servers list
    • In any Code node, select "Execute on EServer"
    • If you have multiple EServers, choose which one to use for that specific node
    • Python code in that node will execute on the selected server (10-100x faster than browser)

Benefits:

  • No manual IP address or port entry
  • Automatic secure key generation
  • Works across your local network
  • Each node can use a different EServer if needed

Automated Deployment Script

#!/bin/bash
# deploy-eserver.sh

# Configure server
eserver config set server.port 3030
eserver config set server.allowNetworkAccess true
eserver config set execution.maxExecutionTime 600000

# Create access keys for different services
eserver keys create "Web API" | grep "Key:" | awk '{print $2}' > /etc/secrets/web-api-key
eserver keys create "Mobile App" | grep "Key:" | awk '{print $2}' > /etc/secrets/mobile-key

# Install and start service
sudo eserver service install --user eserver --group eserver
sudo systemctl enable eserver
sudo systemctl start eserver

# Verify installation
sleep 2
eserver status

echo "EServer deployed successfully"

Configuration File

The server configuration is stored in JSON format. Default locations:

  • Linux/macOS: ~/.johnwylie/eserver-config.json
  • Linux (service): /etc/eserver/config.json

Example Configuration:

{
  "version": "1.0",
  "server": {
    "port": 3030,
    "host": "localhost",
    "allowNetworkAccess": false,
    "maxConcurrentExecutions": 5,
    "requestTimeout": 300000
  },
  "cors": {
    "enabled": true,
    "origins": ["http://localhost:3001"],
    "allowAllOrigins": false
  },
  "security": {
    "allowedIPs": [],
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000
    }
  },
  "execution": {
    "maxExecutionTime": 300000,
    "saveHistory": true,
    "maxHistorySize": 100
  },
  "python": {
    "preferredCommand": "python3",
    "minVersion": "3.11"
  }
}

Troubleshooting

Server Won't Start

  1. Check Python installation:

    eserver info

  2. Check port availability:

    lsof -i :3030  # Check if port is in use

  3. Check configuration:

    eserver config show

  4. Check logs:

    eserver logs --tail 100

Permission Denied

Service installation requires root/sudo:

sudo eserver service install

Cannot Connect from Other Devices

Enable network access:

eserver config set server.allowNetworkAccess true

Check firewall:

# Linux (ufw)
sudo ufw allow 3030/tcp

# Linux (firewalld)
sudo firewall-cmd --add-port=3030/tcp --permanent
sudo firewall-cmd --reload

Service Not Starting on Boot

# Linux
sudo systemctl enable eserver
sudo systemctl start eserver

# macOS
launchctl load ~/Library/LaunchAgents/ai.cognaris.circuitry.eserver.plist

Security Best Practices

  1. Use Access Keys: Always use access keys for authentication
  2. Restrict Network Access: Only enable network access when needed
  3. Use Firewall: Configure firewall to restrict access to trusted IPs
  4. Regular Key Rotation: Revoke and regenerate access keys periodically
  5. Monitor Logs: Regularly check logs for suspicious activity
  6. Limit Permissions: Run service as dedicated user (not root)

API Integration

Access keys can be used in HTTP requests:

# Get server status
curl -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  http://localhost:3030/status

# Execute Python code
curl -X POST http://localhost:3030/execute/node \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(\"Hello from EServer\")",
    "language": "python"
  }'

Support

For help and questions:

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

See Also