CMLabs · Psyclone AIOS

# 1. Administering Psyclone

Command lines, system parameters, logging levels and command-line variable overrides — everything an operator sets before and while a system runs.

## Starting Psyclone

Psyclone is started from the command line with a PsySpec file. On Windows: `Psyclone.exe spec=mysystem.xml`; on UNIX/Linux: `./Psyclone spec=mysystem.xml`. Started with no parameters, Psyclone runs in satellite mode: an idle Node waiting to be claimed by a master system on another computer (see Distributed Admin).

    # Run a system
    ./Psyclone spec=pingpong.xml

    # Run a satellite node on a non-default port
    ./Psyclone port=11000

    # Full production-style invocation
    ./Psyclone spec=robot.xml port=9000 html=/opt/psyclone/html verbose=2 debug=0

The classic convenience parameters are:

Parameter | Meaning | Default
--- | --- | ---
`spec=<file>` | PsySpec XML file to load | none (satellite mode)
`port=<n>` | Main network port (inter-system comms and PsyProbe URL) | 10000
`html=<dir>` | PsyProbe HTML directory | auto-detected `./html`
`verbose=<0-9>` / `debug=<0-9>` | System-wide log levels | 1 / 1
`verbose-<topic>=` / `debug-<topic>=` | Per-topic log levels (see below) | inherit

## Command-line variable overrides Shipped

Any `key=value` argument on the command line is fed into the PsySpec variable substitution table before the spec is expanded. The command line wins over the spec's `<variable>` default — the spec provides sane defaults, the operator overrides per deployment without editing XML.

    <psySpec>
      <variable name="nodename" value="devrig" />
      <variable name="RecordingDir" value="./recordings" />
      <module name="Status-%nodename%">
        ...
      </module>
    </psySpec>

    # Same spec, production values — cmdline overrides the <variable> defaults
    ./Psyclone spec=robot.xml port=9000 nodename=rig RecordingDir=/data/rec

The reserved parameters (`spec=`, `port=`, `html=`, `verbose=`, `debug=` and the `verbose-<topic>=`/`debug-<topic>=` forms) keep their established meanings and are not treated as spec variables. Substitution is a literal string replacement of `%name%` anywhere in the spec — names, cranks, trigger types, paths — so the result must remain valid XML.

Tip. Use variables for everything deployment-specific: ports, hostnames, data directories, credentials files. One spec, many rigs — the diff between machines lives entirely on the command line (or in a launcher script).

## Logging: verbose and debug levels

Psyclone separates verbose output (operational narrative) from debug output (developer detail). Both range from 0 (errors only) to 9 (maximum detail); the default for all topics is 1. Levels can be set system-wide or per topic:

    # System-wide
    ./Psyclone spec=sys.xml verbose=5 debug=0

    # Per topic
    ./Psyclone spec=sys.xml verbose-network=5 debug-memory=0

Topic | Covers
--- | ---
System | Startup/shutdown, overall system lifecycle
Network | Connections, interfaces, node-to-node traffic
Memory | Shared memory and allocation activity
Process | Process spaces, external processes
Sync | Node synchronisation (IDs, components, subscriptions)
Node | Node lifecycle and management
Space | Process space creation, restart, monitoring
Component | Component creation and lifecycle
Subscriptions | Subscription registration and matching
Triggers | Trigger firing and dispatch
Timing | Timers, intervals, delays

Each topic accepts the `verbose-<topic>=` and `debug-<topic>=` command-line forms (lower case, e.g. `verbose-subscriptions=7`).

Note. The reference manual also shows system-wide levels on the root element (`<psySpec verbose="5" debug="0" logfile="../log.txt">`). In the current code base the root-level attributes are not wired — use the command line for system-wide levels, and per-component attributes (below) for targeted logging. Roadmap

## Per-module verbose, debug and logfile Shipped

Each component can carry its own logging configuration, independently of the system-wide levels. This is the tool of choice when one module misbehaves in a large system: crank up that module alone, and optionally route its output to a dedicated file, without drowning in output from everything else.

    <module name="Simple" verbose="3" debug="2" logfile="../log2.txt">
      <trigger name="in" type="data.raw" />
      <crank name="c1" function="MyLib::Process" />
      <post name="out" type="data.cooked" />
    </module>

- `verbose` / `debug` — per-module levels (0–9), overriding the node-wide levels for that module's output.
- `logfile` — routes the module's log lines to its own file instead of (only) the node log.

These attributes appeared in the original manual but were historically parsed without effect; they are now fully wired into central logging. They work on all component kinds — modules, whiteboards, catalogs.

## Main port

The main port carries inter-system communication and the PsyProbe URL. Set it on the command line (`port=6789`) or in the spec root: `<psySpec port="6789">`. PsyProbe is then at `http://<hostname>:6789/`. Multiple protocols (HTTP, Telnet, Message) can share the main port via protocol autodetection — see Custom Interfaces.

## PsyProbe HTML location and port

PsyProbe's web root is auto-detected: an `html` directory near the executable, checking the current and parent directories. Override it with `html=<dir>/html` on the command line or in the spec:

    <psyprobe location="some/dir/html" port="6789" />

Normally PsyProbe shares the main port (protocol autodetect); the `port` attribute adds a dedicated PsyProbe port, and `defaultport="no"` removes PsyProbe from the main port entirely. The `<psyprobe>` element can also hold URL aliases and clickable test posts — covered in PsyProbe Configuration.

## Administration checklist

- Pin the main `port=` explicitly in production; do not rely on the 10000 default.
- Move deployment-specific values into `<variable>` entries and override them on the command line.
- Run production at `verbose=1 debug=0`; raise levels per topic or per module when investigating (see Debugging & Traces).
- Building the SSL variant and locking down interfaces is covered in Security & SSL.

PreviousOverview NextSystem Messages