Summoner Desktop is a chat-based Electron app for interacting with TCP servers. It keeps long‑lived connections, lets you target remote agents, and structures messages with optional to/from fields.

See Summoner Desktop in action in 4 minutes. Click the thumbnail to watch the walkthrough.

This guide helps you set up and run the app locally, even if you are new to Node.js or Electron.

You will need Node.js (v22.12 or later) and npm (Node package manager). You can check if they're already installed:

node -v
npm -v

If either command is not found, install them:

brew install node

sudo apt update
sudo apt install nodejs npm

💡 Tip: You can also use nvm to manage multiple Node.js versions if you're working on different projects.

Use the official installer at https://nodejs.org/en. See the docs for Node.js and npm.

git clone https://github.com/Summoner-Network/summoner-desktop.git
cd summoner-desktop

For developers:

npm install
npm run dev

For users:

npm install
npm run dist

Outputs installers into release/.

This section is designed so you can use the desktop app without running into missing tools. If you want full functionality (projects, local server, agents), install everything below.

• Node.js v22.12+ and npm (required for dev/run/build)

• Git (required for creating projects or importing agents)
• Python (required for running local server and agents)
  • The app will try .venv/venv first, then python3, then python
• pip (required to install agent requirements.txt)
• bash (macOS/Linux) or PowerShell (Windows)
  • Used by the project setup/reset scripts
• macOS/Linux: lsof (used to find/stop processes by port)
• Windows: netstat (used to find/stop processes by port)

• xattr (used by npm run dist:mac)

• Project creation/reset clones summoner-sdk using git and runs setup scripts (bash or PowerShell).
• Local server + agents run Python scripts and install dependencies with pip.
• Port cleanup uses lsof or netstat to detect/stop stuck processes.

This is the main chat view for agent management, interaction, and monitoring message flow.

• Open Servers to add or select a TCP server.
• The default servers are:
  • Default Space (187.77.102.80:8888)
  • Localhost (127.0.0.1:8888)
• Clicking a server in My Servers switches the chat to that server.

• Type a message and press Enter.
• Use Shift+Enter for a new line.

When a server sends messages, the app captures the sender’s remote_addr.

• Click a remote agent in My Network.
• In the chat footer, set Sending to:
  • none → no to field
  • null → to: null
  • key: <path> → to becomes the selected value from the remote payload
    • Example path: from, meta.user.id, items[0].name

Identities are JSON objects that become the from field in outgoing messages.

• Go to Identities and create or edit an identity.
• In chat, choose Sending as to set from.

By default, messages are sent as plain text.

When to or from is set, outgoing payloads are wrapped as:

{
  "payload": "Hello",
  "to": "Remy",
  "from": { "name": "Bot", "type": "agent" }
}

If you type a JSON object (e.g. {"hello": 5}), it will be sent as that object.
If to/from are set, they are injected unless you already provided those keys.