scorpiox-host Networking — SCORPIOX CODE

Overview

scorpiox-host is a lightweight HTTP server that acts as a session gateway for scorpiox code instances. It manages sessions, routes events, and queues messages — enabling multi-session orchestration, monitoring dashboards, and remote control of running AI coding agents.

The implementation spans three files: scorpiox-host.c (main binary with server + CLI), libsxnet/sx_host.c (library functions), and libsxnet/sx_host.h (header). Built on raw POSIX sockets with zero external dependencies.

🔌

Session Gateway

Central hub for multiple scorpiox code sessions. Register, list, and inspect sessions via REST endpoints.

📡

Event Bus

Real-time event streaming — thinking, tool-start, tool-done, complete, error, idle, user-message, compact.

📬

Message Queue

Per-session message queuing with 32-message buffer. POST messages in, GET pulls and clears the queue.

🔄

sx.c Integration

Background pull thread baked into sx.c — sessions auto-register and stream events to the host.

👻

Daemonize

Run as a background daemon with PID file. Clean fork, setsid, and redirect to /dev/null.

⚡

Zero Dependencies

POSIX sockets only — no libcurl, no libev, no libuv. Compiles anywhere with a C compiler.

Architecture

scorpiox-host operates as both a server and a CLI client. When invoked with --daemon or without arguments, it starts the HTTP server on port 7432. With subcommands like status, sessions, or send, it acts as a CLI client connecting to the running server.

                Architecture
                
┌─────────────────────────────────────────────────────┐
│                  scorpiox-host :7432                 │
│                                                     │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │  Session     │  │  Event       │  │  Message   │ │
│  │  Registry    │  │  Ring Buffer │  │  Queue     │ │
│  │  (CRUD)      │  │  (per sess)  │  │  (32 max)  │ │
│  └──────┬───── ┘  └──────┬───────┘  └─────┬──────┘ │
│         │                │                │         │
│  ───────┴────────────────┴────────────────┴───────  │
│                   HTTP Router                       │
│         GET/POST → parse → dispatch → JSON          │
└──────────────────────┬──────────────────────────────┘
                       │
          ┌────────────┼────────────┐
          │            │            │
     ┌────┴────┐  ┌────┴────┐  ┌───┴─────┐
     │  sx.c   │  │  sx.c   │  │  CLI /  │
     │ inst #1 │  │ inst #2 │  │ curl    │
     └─────────┘  └─────────┘  └─────────┘
                
            

REST API Reference

All endpoints return application/json unless noted otherwise. No authentication required (bind to localhost for production use).

Method	Path	Description
GET	/health	Health check — returns {"status":"ok"}
GET	/status	Server summary — version, port, uptime, session count, active count, total events
GET	/sessions	List all sessions — JSON array with id, state, last_event, event_count, model, provider
GET	/sessions/:id	Session detail — full info including recent events (last 10), model, provider, cwd, start_time
GET	/sessions/:id/events	Session events — returns JSONL (newline-delimited JSON) of all buffered events
POST	/sessions/:id/events	Fire an event — accepts {"event":"...","data":"..."} body
POST	/sessions/:id/register	Register a session — creates or updates session entry
GET	/sessions/:id/messages	Pull queued messages — returns JSON array and clears the queue
POST	/sessions/:id/messages	Queue a message — max 32 per session, 8192 bytes each, returns 429 if full
POST	/stop	Graceful server shutdown

Event Bus

Each session maintains a ring buffer of events. Events are fired via POST /sessions/:id/events and consumed via GET /sessions/:id/events (JSONL format). The sx.c integration fires events automatically during agentic execution.

Event Types

thinking

tool-start

tool-done

complete

error

idle

user-message

compact

Event Payload

                JSON
                
// POST /sessions/abc-123/events
{
  "event": "tool-start",
  "data": "Bash: git status"
}

// Response
{
  "ok": true,
  "event_count": 42
}
                
            

Usage Examples

Start the Server

                Shell
                
# Start in foreground on default port 7432
$ scorpiox-host

# Start as daemon
$ scorpiox-host --daemon

# Custom port
$ scorpiox-host --port 9000

# Check if running
$ scorpiox-host status
Host running on :7432 — 3 sessions, 2 active
                
            

CLI Client

                Shell
                
# List all sessions
$ scorpiox-host sessions
abc-123  active   tool-start   openai/gpt-4.1  events:42
def-456  idle     complete     anthropic/claude  events:18

# Send a message to a session
$ scorpiox-host send abc-123 "refactor the auth module"

# Stop the server
$ scorpiox-host stop
                
            

curl Examples

                Shell
                
# Health check
$ curl -s http://localhost:7432/health
{"status":"ok"}

# Server status
$ curl -s http://localhost:7432/status | jq .
{
  "version": "1.0",
  "port": 7432,
  "uptime": 3621,
  "sessions": 3,
  "active": 2,
  "total_events": 847
}

# Register a session
$ curl -X POST http://localhost:7432/sessions/my-session/register   -H "Content-Type: application/json"   -d '{"model":"gpt-4.1","provider":"openai","cwd":"/home/dev/project"}'

# Fire an event
$ curl -X POST http://localhost:7432/sessions/my-session/events   -H "Content-Type: application/json"   -d '{"event":"thinking","data":"analyzing codebase"}'

# Queue a message (max 32 per session, 8192 bytes each)
$ curl -X POST http://localhost:7432/sessions/my-session/messages   -H "Content-Type: application/json"   -d '{"content":"fix the failing test in auth.c"}'

# Pull messages (returns array, clears queue)
$ curl -s http://localhost:7432/sessions/my-session/messages
[{"content":"fix the failing test in auth.c"}]

# Get events (JSONL format)
$ curl -s http://localhost:7432/sessions/my-session/events
{"event":"thinking","data":"analyzing codebase","ts":1710312000}
{"event":"tool-start","data":"Bash: make test","ts":1710312005}
                
            

Configuration

scorpiox-host uses CLI flags rather than config-file keys. The server binds to 0.0.0.0 by default — for production use, bind to 127.0.0.1 or use a firewall.

Flag	Default	Description
--port	7432	TCP port to listen on
--daemon	off	Fork to background, write PID file
--pid-file	/tmp/scorpiox-host.pid	PID file path for daemon mode

Session Limits

                Compile-time Constants
                
#define MAX_SESSIONS      64     // max concurrent sessions
#define MAX_EVENTS        256    // ring buffer size per session
#define MAX_MESSAGES      32     // message queue depth per session
#define MAX_MESSAGE_SIZE  8192   // max bytes per message
                
            

sx.c Integration

When scorpiox-host is running, the main sx binary detects it and auto-registers the current session. A background pull thread checks for queued messages and injects them as user input. Events like thinking, tool-start, and tool-done are fired automatically during agentic execution.

                Flow
                
// sx.c startup sequence:
1. Check if scorpiox-host is running on :7432
2. POST /sessions/<session-id>/register
   → sends model, provider, cwd, git branch
3. Start background pull thread
   → GET /sessions/<session-id>/messages every 2s
   → inject received messages as user prompts
4. During execution, fire events:
   → POST /sessions/<session-id>/events
   → {"event":"thinking"}, {"event":"tool-start","data":"Bash: ..."}
5. On completion:
   → POST {"event":"complete"} or {"event":"error"}
                
            

This enables building monitoring dashboards, CI/CD watchers, and multi-agent orchestration — all through the simple REST interface. No WebSockets, no gRPC, no protobuf — just HTTP and JSON over port 7432.