expecco Wiki (Version 26.x) - Benutzerbeiträge [de]

Release Notes 26.x

2026-08-21T18:19:01Z

Sv: 26.2: native Remote Access SSH/SFTP action blocks (link to main article)

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==
* Feature: [[ElementaryBlock_Element/en#Scheme_Blocks_(Bridged)|bridged Scheme]] (currently only Racket Scheme) action blocks
* Feature: [[ElementaryBlock_Element/en#Octave_Blocks_(Bridged)|bridged Octave/Matlab]] action blocks
* Feature: [[Expecco_API/en#C#_Actions|bridged C#]] action blocks
* Feature: '''NEW''' AI Coding provider "'''Claude Code (subscription)'''" — uses your existing Claude subscription via the locally installed ''Claude Code'' command line program instead of an API key, so no key has to be entered and no per-token API charges are billed. Choose it like any other provider in the settings dialog (Plugins → AI Coding); the API key, endpoint URL and proxy fields are hidden for it because they do not apply, and the authentication method reads "Subscription (external login)". It requires ''Claude Code'' to be installed and logged in once (run <code>claude</code> in a terminal and complete the login). The model is selectable either as a tier alias (''sonnet'', ''opus'', ''haiku'' — always the current model of that tier) or as a pinned model id.
* Feature: two new AI actions that work on the selected '''class''' rather than on a single method, reachable from the '''AI''' menu of the class browser: "'''Explain Class'''" explains the class as a whole — what it is responsible for, what its instance variables hold and how its protocols fit together — and "'''Generate Class Documentation'''" proposes a class documentation text which the "[Apply]" button installs into the class' documentation.
* Feature: HTTP/2 (h2) support in the embedded web server, negotiated via TLS ALPN, with HPACK header compression and request multiplexing over a single connection. Implemented in pure Smalltalk, so no external library is required. This is the server side only — the HTTP client (''HTTPInterface'') continues to speak HTTP/1.1. A server configured without a certificate stays on HTTP/1.1, because h2 is negotiated during the TLS handshake; the offer can be turned off with <code>HTTPServer http2Enabled:false</code>.
* Feature: ALM repository project version access in the project tree; see versions directly in a second tree (readonly), drag items out of it, execute test plans etc. Create new version and easy commit.
* Feature: TEAM support; multiple teams users can live-edit the same suite for merge, group development, passing work to other users or demonstration.
* Feature: improved SSDP service announcement
* Feature: full ipV6 UDP support (mostly socketAddress fixes and multicast support)
* Feature: '''NEW''' [[SNMP Plugin Reference/en|SNMP]] support, reimplemented in expecco itself - no ''net-snmp'' installation is needed any more, and the blocks behave identically on every supported platform. SNMP v1, v2c and v3 (authentication with MD5, SHA-1 or one of the SHA-2 protocols of RFC 7860, encryption with DES or AES-128); a whole table read by one block with its rows and their INDEX decoded (ifTable, ipAddrTable, tcpConnTable, ...); many devices asked the same question at once, in parallel; traps and informs both received and sent. An up to date set of MIB modules (net-snmp 5.9.5.2) is delivered, so the names of SNMPv2-MIB, IF-MIB, IP-MIB, TCP-MIB and friends resolve out of the box - the deprecated RFC1213-MIB groups (''at'', ''egp'', ''ipRouteTable'') are not part of it and are shown numerically, add ''RFC1213-MIB.txt'' to a MIB directory ("Add MIB Directory") if a device still needs those names. Fixes on the way: object identifiers were corrupted on 64bit systems, which made most SNMP blocks return wrong values.
* Feature: the [[Remote Access/en#From expecco actions|Remote Access]] plugin gained '''native''' (pure-Smalltalk, via <code>exept:libcrypt/ssh</code>) SSH and SFTP action blocks — SSH open/close, execute command (with optional stdin), execute a list of commands (each on its own channel or in one persistent shell), password authentication, and SFTP upload (from a file, String or stream), download (to a file and/or a stream, streamed without buffering), list, delete, rename and make-directory; each block ships with a runnable Test/Demo network. No external <code>ssh</code>/<code>plink</code> binary is required.
* Fix: JSON printer's recursive store detection was generating false positives
* Improvement: better Python syntax highlighter

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports '''Anthropic Claude''', '''OpenAI ChatGPT''', '''ollama''' and others as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via [[Tools_FileBrowser/en|FileBrowser]])
* Feature: public/private keypair generation via a [[Tools_FileBrowser/en|FileBrowser]] menu (for easy SSH setup)
* Improvement: Bundled python3 installer updated to version 3.13.14
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed the [[Number_API_Functions|Number]] stack (see also in [[Numeric_Limits/en| Numeric Limits]]):
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. and type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan). Now all test cases produce a result within the precision limits of their type
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]]
* UI: '''Ctrl-Return''' now accepts the default action in every modal dialog — both the modern SimpleDialog-based ones (check-in log message, search dialogs, ...) and old-style DialogBox-based ones (EnterBox, OptionBox, InfoBox, ...). Unlike plain Return, Ctrl-Return submits the dialog even when the focus is on a multi-line text editor (which normally keeps Return as a newline), so there is no need to tab off the editor first.
* UI: Transcript (the console) always appends text at end.
* UI: Transcript does not scroll to end on incoming text while moving the scrollbar
* Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
* Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
* Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Performance: speedup of cryptographic algorithms (affects key generation and other)
* Performance: tuned loading of stored ets/elf files (30-40% speedup)
* Performance: further speedup when loading test-result archives that embed large execution logs — typical load is roughly a third faster again

Remote Access

2026-08-21T18:18:59Z

Sv: native SSH/SFTP-Aktionsbloecke (26.2) unter 'Aus expecco-Aktionen'

{{Languages|Remote Access|label=Deutsch}}

'''Fernzugriff''' bezeichnet die Möglichkeit, einen entfernten
Rechner oder ein entferntes Netzwerk aus diesem expecco-Image heraus
zu bedienen — Shells zu öffnen, Befehle abzusetzen, Dateien zu
verschieben oder ein Testgerät anzusteuern. Drei Protokoll-Familien
sind unterstützt, in absteigender Empfehlungsreihenfolge:

* '''SSH und SFTP''' (empfohlen) — verschlüsselte Shell und sichere Dateiübertragung über einen SSH-2-Tunnel. Reine Smalltalk-Implementierung in <code>exept:libcrypt/ssh</code>; keine externe Abhängigkeit von OpenSSL oder libssh. Für alles mit Zugangsdaten oder sensiblen Nutzdaten.
* '''Lokale Kommando-Shell''' — fork + exec auf der lokalen Maschine. Für die Anbindung lokaler Werkzeuge und für die lokale Seite eines hybriden Workflows.
* '''Telnet''' (veraltet) — Klartext-Terminalsitzung. Keine Verschlüsselung, Passwörter im Klartext auf der Leitung. Nur einsetzen, wenn die Gegenstelle keine Alternative bietet.

= SSH und SFTP =

Der SSH-Stack deckt das vollständige SSH-2-Protokoll ab
(RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) inklusive der
chacha20-poly1305-Transportchiffrierung von OpenSSH sowie das
SFTP-v3-Subsystem (draft-ietf-secsh-filexfer-02). Zwei Schichten:

* '''<code>SSH::Client</code>''' — programmatischer SSH-Zugriff (entferntes <code>exec</code>, TTY-Shell, Agent-Weiterleitung, ProxyJump-Bastion).
* '''<code>SSH::SftpFilename</code>''' — eine
<code>Filename</code>-Unterklasse, die es dem restlichen ST/X
erlaubt, einen entfernten SFTP-Pfad zu behandeln wie eine lokale
Datei.

Die folgenden Abschnitte sind nutzeraufgaben-zuerst aufgebaut:
zuerst das, was der Anwender sieht und tut, darunter die
expecco-Bibliotheks-Anbindung, ganz unten Implementierungsdetails
für Interessierte.

== Aus dem FileBrowserV2 ==

Im Adress-Dropdown eine <code>sftp://</code>-URL einfügen. Der
Browser-Tab füllt sich wie bei einem lokalen Pfad.
Baum-Ausklappen, Spaltensortierung (Name / Größe / mtime),
Vorschau und Doppelklick zum Öffnen im Editor verhalten sich
normal. Der erste Klick auf einen Host dauert ~200–500 ms
(TCP + KEX + Auth); folgende Klicks nutzen die gepoolte
Verbindung weiter.

URL-Syntax:

<pre>
sftp://[user[:password]@]host[:port]/remote/path
</pre>

Fehlt <code>user</code>, wird der lokale Login-Name verwendet, Port
ist standardmäßig 22, Pfad standardmäßig <code>/</code>. Das
optionale <code>:password</code>-Segment ist das RFC-3986-Userinfo-Passwort
— wann es angebracht ist und welche Sicherheitsabwägungen
damit verbunden sind, beschreibt [[#Passwort-Authentifizierung]].
Wenn vorhanden, dient es als USERAUTH-Fallback nach den üblichen
Publickey-/Agent-Versuchen und wird '''niemals''' wieder von der
druckbaren URL-Form ausgegeben — das Protokollieren des
Dateinamens leakt also nicht das Credential.

Die Schaltfläche '''Refresh''' in der Symbolleiste
(Pfeil-Kreis-Symbol zwischen ''Forward'' und ''DirectoryUp'') liest
Baum und Inhalts-Panel auf Anforderung neu ein. Funktioniert
einheitlich für lokale und SFTP-Pfade; bei SFTP wird zusätzlich der
per-Datei-STAT-Cache geleert, sodass Änderungen, die direkt auf
der Gegenseite gemacht wurden, sofort sichtbar werden — ohne auf
den Ablauf der 5-Sekunden-Cache-TTL zu warten.

Der kleine Pfeil neben dem Refresh-Symbol öffnet ein Aufklappmenü
mit einem einzelnen Kontrollkästchen, '''Automatic Refresh''', das
den Hintergrund-Task an- bzw. abschaltet, der alle expandierten
Baumeinträge auf externe Änderungen prüft. Die Vorgabe richtet
sich nach der aktuellen Wurzel:

* Lokales Dateisystem → '''an''' (10-Sekunden-Zyklus, entspricht dem bisherigen Verhalten).
* SFTP → '''aus'''. Jeder Zyklus kostet einen STAT-Roundtrip pro Kind — für eine Handvoll lokaler Verzeichnisse harmlos, über das Netz schmerzhaft. Bei Bedarf manuell auf Refresh klicken, um Änderungen zu sehen.

Beim Wechsel zwischen lokalen und SFTP-Wurzeln wird der Schalter
automatisch umgelegt — aber nur, sofern man ihn für die
vorherige Wurzel nicht selbst verstellt hat. Eine explizite
Benutzerwahl bleibt über Navigationen hinweg erhalten.

Das Menü '''Tools''' im FileBrowserV2 bietet vier Aktionen — die
drei SSH-spezifischen sind nur bei geladener SSH-Bibliothek
sichtbar:

* '''Generate SSH Key Pair...''' — öffnet den Schlüsselerzeugungs-Dialog, siehe [[#Einen SSH-Schlüssel erzeugen]] unten.
* '''SSH Connect...''' — öffnet ein interaktives VT100-Terminal zu einem entfernten Host.
* '''SFTP Connect...''' — navigiert diesen Browser-Tab über SFTP auf ein entferntes Dateisystem.
* '''Filesystem Info...''' — zeigt Größe, freien Platz und Belegung des Dateisystems, das das aktuell angezeigte Verzeichnis enthält. Funktioniert einheitlich für lokale und SFTP-Pfade; bei SFTP setzt der Aufruf voraus, daß der Server die Erweiterung
<code>statvfs@openssh.com</code> ankündigt (jedes moderne OpenSSH
tut das). Größen werden in IEC-Binäreinheiten ausgegeben (MiB,
GiB, TiB) — gewählt wird die größte Einheit, die einen Wert ≥ 1
liefert, damit ein TB-großes Volume als ''X TiB'' statt
''10240 GiB'' erscheint.

== Aus dem Launcher ==

Das Untermenü '''Workspace''' im Launcher enthält zwei eigenständige
Einträge (nur sichtbar bei geladenem SSH-Paket):

* '''SSH Terminal''' — fragt nach einem Ziel der Form <code>user[:password]@host[:port]</code> und öffnet ein VT100-Terminal als eigenständiges Fenster. Das ist das Launcher-Pendant zum FileBrowserV2-Eintrag '''Tools → SSH Connect...'''.
* '''SFTP Connection''' — fragt nach einem SFTP-Ziel (gleiche URL-Grammatik wie in der FileBrowserV2-Adresszeile, siehe [[#Aus dem FileBrowserV2]]) und öffnet einen frischen FileBrowserV2, der bereits dorthin navigiert ist.

Beide Einträge unterstützen die in [[#Passwort-Authentifizierung]]
beschriebene URL-Form mit eingebettetem Passwort.

== Aus expecco-Aktionen ==

Das Expecco-RemoteAccess-Plugin
([[Expecco::RemoteAccessImportPlugin]]) stellt folgende Testaktionen
in der expecco-Aktionspalette bereit:

* '''CmdShell - Open SSH Remote Connection''' — öffnet eine SSH-Sitzung über das plattformeigene <code>ssh</code>-Binary (PuTTYs <code>plink</code> unter Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — dasselbe, jedoch mit expliziter Public-Key-Authentifizierung.

Voraussetzung: ein eingerichtetes Schlüsselpaar (privater
Schlüssel auf dieser Maschine, öffentlicher Teil in der
<code>~/.ssh/authorized_keys</code> des Zielhosts). Schlüssel
erzeugen entweder über den Dialog unten oder über
<code>ssh-keygen</code>.

Das Plugin fügt zusätzlich eine Settings-Seite hinzu:
'''Extras → Settings → Plugins → Remote Access — SSH Keys''' mit
einer einzelnen Schaltfläche '''Generate SSH Key Pair...''', die
denselben Dialog öffnet.

Seit expecco 26.2 stellt das Plugin zusätzlich '''native''' SSH- und SFTP-Aktionsblöcke bereit, in reinem Smalltalk auf Basis von <code>exept:libcrypt/ssh</code> implementiert — kein externes <code>ssh</code>- oder <code>plink</code>-Binary erforderlich. Eine Verbindung wird einmal geöffnet und ihr <code>SshHandle</code> an die folgenden Blöcke weitergereicht.

SSH-Blöcke:

* '''SSH - Open Connection''' — verbinden und authentifizieren (expliziter privater Schlüssel, ssh-agent oder die Standard-Schlüssel in <code>~/.ssh</code>); liefert ein <code>SshHandle</code> für die Blöcke unten.
* '''SSH - Open Connection with Password''' — dasselbe, jedoch mit Klartext-Passwort statt eines Schlüssels.
* '''SSH - Execute Command''' — führt ein einzelnes Kommando aus; liefert stdout, stderr und Exit-Status, mit einem optionalen stdin-Stream, der an den entfernten Prozess geleitet wird.
* '''SSH - Execute Commands''' — führt eine Liste von Kommandos aus, jedes als eigener Exec-Kanal, auf einer offenen Verbindung.
* '''SSH - Execute Commands In Shell''' — führt eine Liste von Kommandos in einer einzigen, dauerhaften Login-Shell aus, sodass Zustand wie das Arbeitsverzeichnis über die Kommandos hinweg erhalten bleibt.
* '''SSH - Close Connection''' — schließt eine oben geöffnete Verbindung.

SFTP-Blöcke (jeweils auf einem offenen <code>SshHandle</code> aufsetzend):

* '''SFTP - Upload File''' und '''SFTP - Upload File from String/Stream''' — schreibt eine lokale Datei bzw. Inhalt aus dem Speicher / einen Read-Stream auf einen entfernten Pfad (gestreamt, ohne die ganze Datei zu puffern).
* '''SFTP - Download File''' — liest eine entfernte Datei in eine lokale Datei und/oder in einen übergebenen Write-Stream (gestreamt, ohne die ganze Datei zu puffern).
* '''SFTP - List Directory''' — listet die Einträge eines entfernten Verzeichnisses auf.
* '''SFTP - Delete File''', '''SFTP - Rename''' und '''SFTP - Make Directory''' — Verwaltung entfernter Dateien.

Jeder dieser Blöcke bringt ein lauffähiges Test/Demo-Netz (in seinem ''Test/Demo''-Reiter) mit, das sich mit dem Host aus den Umgebungsvariablen <code>DEMO_SSH_HOST</code>, <code>DEMO_SSH_PORT</code> und <code>DEMO_SSH_USER</code> verbindet.

== Einen SSH-Schlüssel erzeugen ==

=== Der Dialog (FileBrowserV2 / Settings-Seite) ===

Der Dialog fragt alle Parameter in einem Formular ab:

* '''Comment''' — wird in den erzeugten Schlüssel eingebettet (Voreinstellung <code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — schreibt
<code>~/.ssh/id_ed25519_stx</code> (oder wohin man will) samt
zugehöriger <code>.pub</code>-Datei daneben.
** ''Save to disk AND load into ssh-agent'' — schreibt die Datei UND übergibt den Schlüssel dem laufenden ssh-agent.
** ''Load into ssh-agent only'' — der Schlüssel lebt nur im Speicher des Agents; nach Agent-Neustart ist er verloren.
* '''Private key file''' — vollständiger Pfad; ausgegraut im Agent-only-Modus.
* '''Passphrase / Confirm''' — leer lässt die On-Disk-Datei unverschlüsselt (Agent-only-Modus ignoriert die Passphrase, da das OpenSSH-Agent-Wire-Protokoll nur den entschlüsselten Schlüssel transportiert).

Bei '''Generate''' wird die Public-Key-Zeile (dieselbe
<code>ssh-ed25519 AAAA... comment</code>-Zeichenfolge, die
ssh-keygen ausgibt) in die System-Zwischenablage kopiert — zum
direkten Einfügen in die <code>~/.ssh/authorized_keys</code> des
Zielhosts.

=== Aus einem Workspace ===

Für Headless-Deployments, Sandbox-Builds oder Skripte stellt
<code>SSH::Client</code> einen reinen Smalltalk-Schlüsselgenerator
bereit, dessen Ausgabe bit-kompatibel zu
<code>ssh-keygen -t ed25519</code> ist:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Passphrase-verschlüsselt auf Platte speichern"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ UND in den laufenden Agent laden"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Public-Key-Zeile zum Einfügen in authorized_keys ausgeben"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Die so erzeugten Schlüssel sind mit den OpenSSH-Werkzeugen voll
interoperabel (<code>ssh-keygen -y -f ...</code> rekonstruiert den
öffentlichen Schlüssel, <code>ssh-keygen -p -f ...</code> ändert
die Passphrase usw.).

=== Mit den Shell-Werkzeugen ===

Der klassische Weg funktioniert weiterhin:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== ssh-agent vorbereiten ==

Der Weg über den Agent ist dem direkten Lesen von Schlüsseldateien
deutlich vorzuziehen: er hält verschlüsselte private Schlüssel
einmal pro Sitzung entsperrt und kann Identitäten verwalten
(hardware-tokengestützte Schlüssel, KeePassXC-Einträge), die ST/X
nie direkt sehen soll.

ST/X erkennt den Agent-Pfad automatisch, sobald
<code>$SSH_AUTH_SOCK</code> '''zum Zeitpunkt des Starts von stx'''
in der Prozessumgebung gesetzt ist. Eine spätere Zuweisung aus
einem Workspace nützt nichts.

=== Linux / macOS ===

Die meisten Desktop-Distributionen starten einen Agent automatisch
beim Login (gnome-keyring unter GNOME, ssh-agent.service unter
systemd, KWallet unter KDE). Prüfen im Terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh oder ähnlich
ssh-add -l # listet geladene Identitäten
ssh-add ~/.ssh/id_ed25519 # eigene laden, falls nicht da
</pre>

Läuft gar kein Agent, dieses Snippet in die Shell-rc-Datei
aufnehmen:

<pre>
# ~/.bashrc oder ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X muss aus einer Shell gestartet werden, die diese rc bereits
gelesen hat — ein Desktop-Launcher aus dem Dateimanager erbt die
Variable nicht. Empfehlung: ein kleines Wrapper-Skript unter
<code>~/.local/bin/</code>, das die rc sourcet und dann stx
startet.

Die Settings-Seite ('''Extras → Settings → Plugins → Remote
Access — SSH Keys''') zeigt an, ob das laufende Image einen
Agent sieht.

==== Permanente Einrichtung via systemd ====

Für einen wirklich sitzungsübergreifenden Agent (überlebt Desktop-
Abmeldung, kommt beim nächsten Login wieder hoch) die bei den
meisten Distros mit dem Paket <code>openssh-clients</code>
ausgelieferte Per-User-systemd-Unit aktivieren:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Anschließend <code>SSH_AUTH_SOCK</code> in der Shell-rc auf den
User-Service-Socket zeigen lassen (ersetzt das
<code>eval $(ssh-agent -s)</code>-Snippet oben):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Schlüssel automatisch beim ersten Einsatz laden ====

Um den manuellen <code>ssh-add</code>-Schritt zu sparen, kann
OpenSSH Schlüssel beim ersten Bedarf selbst in den Agent laden.
In <code>~/.ssh/config</code> eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

Die erste SSH-Verbindung fragt dann einmal nach der Passphrase und
übergibt den entsperrten Schlüssel an den Agent; weitere
Verbindungen nutzen die gespeicherte Identität ohne Prompt.

=== Windows ===

Windows 10+ bringt das native OpenSSH inklusive Agent-Dienst mit.
Einmalige Einrichtung:

# '''Dienste''' (<code>services.msc</code>) als Administrator öffnen.
# '''OpenSSH Authentication Agent''' suchen, Starttyp auf '''Automatisch''' setzen, '''Starten''' anklicken.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Prüfen: <code>ssh-add -l</code>.

Der Windows-OpenSSH-Agent lauscht auf einer Named Pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), nicht auf einem
Unix-Socket. ST/X unterstützt beide Transporte, jedoch setzt das
Windows-ssh-add <code>SSH_AUTH_SOCK</code> '''nicht''' selbst.
Daher einmalig systemweit setzen:

# {{Key|Win}} drücken → "Umgebungsvariablen" → „Systemumgebungs- variablen bearbeiten".
# '''Umgebungsvariablen''' → unter '''Benutzervariablen''', '''Neu''' klicken.
# Name: <code>SSH_AUTH_SOCK</code>
# Wert: <code>\\.\pipe\openssh-ssh-agent</code>
# Ab- und wieder anmelden (oder stx neu starten), damit die neue Umgebung übernommen wird.

==== PowerShell-Schnelleinrichtung ====

Derselbe Aufbau aus einer '''Administrator-PowerShell''' heraus,
z.B. für Skripte oder unbeaufsichtigte Bereitstellung:

<pre>
# Agent jetzt und bei jedem Neustart starten (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# SSH_AUTH_SOCK dauerhaft für den Benutzer setzen (übersteht Reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Schlüssel laden (fragt nach Passphrase, falls die Datei verschlüsselt ist).
ssh-add $HOME\.ssh\id_ed25519
</pre>

Für einen einmaligen Agent-Start ohne dauerhafte Aktivierung
(z.B. Einzelsitzung) die <code>Set-Service</code>-Zeile weglassen
und nur <code>Start-Service ssh-agent</code> ausführen. Die
env-var-Zeile lässt sich ebenfalls weglassen, wenn
<code>SSH_AUTH_SOCK</code> nur in der aktuellen Shell gebraucht
wird — dann statt der <code>[Environment]</code>-Variante
<code>$env:SSH_AUTH_SOCK = '...'</code> verwenden.

Auf stark abgespeckten Windows-Installationen ist der
ssh-agent-Dienst eventuell nicht vorhanden. Einmalig nachrüsten
über '''Einstellungen → Apps → Optionale Features → OpenSSH-
Client'''.

Alternative Agenten:

* '''PuTTY pageant''' — eigenes Protokoll; von ST/X's
<code>SSH::Agent</code> '''nicht''' unterstützt. Schlüssel zu
OpenSSH migrieren.
* '''Git für Windows ssh-agent''' — funktioniert;
<code>SSH_AUTH_SOCK</code> auf den dort veröffentlichten Socket
zeigen lassen.
* '''WSL 2''' — ein ST/X innerhalb der WSL sieht den WSL-eigenen Agent normal; ein ST/X auf der Windows-Seite nicht. Eine Brücke per <code>npiperelay</code> + <code>socat</code> ist möglich.

Prüfung über die Settings-Seite
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
die Anzeige dort meldet, ob das laufende Image den Agent sieht.

==== Schlüssel automatisch beim ersten Einsatz laden ====

Windows-OpenSSH speichert agent-geladene Schlüssel '''nicht'''
über Agent-Neustarts hinweg. Um nicht nach jedem Reboot manuell
<code>ssh-add</code> aufrufen zu müssen, dieselbe Lazy-Load-
Konfiguration in <code>%USERPROFILE%\.ssh\config</code>
eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH lädt den Schlüssel dann beim ersten Einsatz in den Agent
(fragt einmal nach der Passphrase) und nutzt ihn für die übrige
Sitzung weiter.

== Passwort-Authentifizierung ==

Empfohlen ist Public-Key-Authentifizierung (mit oder ohne
ssh-agent). Passwort-Authentifizierung ist als Fallback gedacht,
wenn keine Schlüssel verfügbar sind: Altsysteme, Ad-hoc-Zugriff
auf einen Testserver, Skripte gegen ein Konto, dessen Besitzer den
Public Key nicht hinterlegen möchte. Zu beachten:

* Das Klartext-Passwort liegt auf ST/X-Seite für die Lebensdauer des <code>SSH::Client</code> im Speicher — entsprechend behandeln wie jedes andere In-Memory-Geheimnis.
* Der Server entscheidet, welche Methoden er akzeptiert. Steht in <code>sshd_config</code> <code>PasswordAuthentication no</code>, kann keine Smalltalk-seitige Einstellung das überschreiben.
* Auf Drahtebene entspricht der Vorgang RFC 4252 §8: das Passwort wandert innerhalb der verschlüsselten SSH-Transportschicht, niemals im Klartext über das Netz.

=== Aus einer URL ===

Sowohl die FileBrowserV2-Adressleiste als auch die Launcher-Dialoge
'''Workspace → SFTP Connection''' / '''Workspace → SSH
Terminal''' akzeptieren ein eingebettetes Passwort an der
standardmäßigen RFC-3986-Userinfo-Position:

<pre>
sftp://alice:s3cret@host.example.com/srv/data
ssh alice:s3cret@host.example.com:2222
</pre>

Der Parser splittet am '''letzten''' <code>@</code>, sodass
Passwörter mit enthaltenem <code>@</code> dennoch korrekt geparst
werden; der erste <code>:</code> im Userinfo-Teil trennt Benutzer
und Passwort. Passwörter, die selbst ein <code>:</code> enthalten,
werden in dieser Form nicht unterstützt — dafür die
programmatische API unten verwenden.

Das Passwort wird aus der druckbaren URL entfernt: jede Stelle, die
am Ende den Dateinamen ausgibt (Statuszeile,
<code>printOn:</code>, <code>nameString</code>, die Breadcrumb-Leiste)
zeigt die credential-freie Form
<code>sftp://alice@host.example.com/...</code>.

=== Aus Code ===

Zwei äquivalente Wege, einem <code>SSH::Client</code> ein Passwort
mitzugeben:

<pre>
"/ Literal -- am einfachsten, Passwort ist nur ein Ivar
client := SSH::Client newToHost:'host.example.com' port:22 user:'alice'.
client password:'s3cret'.
client connect.
</pre>

<pre>
"/ Callback -- lazy; das Passwort lebt nie auf dem Client.
"/ Praktisch für interaktive Abfrage, Keychain-Lookup oder ein
"/ Vault-gespeichertes Geheimnis, das nicht langlebig im Speicher
"/ liegen soll.
client passwordCallback:[ Dialog requestPassword:'SSH-Passwort' ].
client connect.
</pre>

Sind beide gesetzt, gewinnt der Callback. Beide werden lazy
während <code>#connect</code> ausgewertet, nachdem die
Publickey-/Agent-Versuche abgelehnt wurden — ein
funktionierender Schlüssel schlägt also immer ein parallel
konfiguriertes Passwort.

=== Reihenfolge der Authentifizierungsversuche ===

<code>SSH::Client>>authenticate</code> geht jedes verfügbare
Credential der Reihe nach durch und kehrt beim ersten zurück, das
der Server akzeptiert:

# ssh-agent-Identitäten, sofern <code>#useAgent</code> aufgerufen wurde und der Agent Schlüssel geladen hat.
# ed25519-Privatschlüssel-Seed, sofern <code>#privateKeyFromFile:</code> einen geladen hat.
# RSA-Privatschlüssel.
# ECDSA-Privatschlüssel.
# Passwort, sofern <code>#password:</code> / <code>#passwordCallback:</code> gesetzt ist '''und''' der Server <code>password</code> in seiner USERAUTH_FAILURE-Methodenliste weiterhin anbietet.

Jeder Schritt wird übersprungen, wenn die letzte
<code>USERAUTH_FAILURE</code>-Antwort des Servers die jeweilige
Methode aus der erlaubten Liste gestrichen hat — auf
<code>publickey</code> wird also nicht weiter herumgehämmert,
sobald der Server damit aufhört. Der Passwortversuch läuft nur,
wenn der Server <code>password</code> noch verlangt; ein falsch
konfiguriertes Passwort gegen einen reinen Schlüssel-Server erzeugt
also einen sauberen <code>SSH::AuthenticationError</code> ohne
zusätzlichen nutzlosen Roundtrip.

== Konfiguration ==

Alle Stellschrauben sind klassenseitig auf
<code>SSH::SftpFilename</code> erreichbar:

{| class="wikitable"
! Accessor !! Voreinstellung !! Steuert
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 Min) || Wie lange
eine gepoolte Verbindung im Leerlauf liegen darf, bevor sie beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet wird.
Liegt knapp unter dem typischen
<code>ClientAliveInterval × ClientAliveCountMax</code> des sshd,
damit wir uns recyceln, bevor der Server uns mit TCP-RESET
trennt. <code>nil</code> setzt auf Voreinstellung zurück.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Maximales Alter (s)
eines gecachten STAT, bevor <code>#ensureAttrs</code> neu am
Server fragt. Eltern-listDir stempelt ohnehin frische Attribute
auf alle Kinder, daher zahlt das Navigieren im offenen
Verzeichnis das TTL nicht. <code>0</code> schaltet den Cache
ab.
|-
| <code>#closeAllConnections</code> || (Aktion) || Reißt jede
gepoolte Verbindung ab. Nützlich nach einem bekannt schlechten
Netzereignis, vor einem bewussten Identitätswechsel oder zum
sauberen Image-Shutdown.
|}

== Diagnose ==

=== SemaphoreMonitor ===

<code>SemaphoreMonitor</code> über das Untermenü „Status" des
Launchers öffnen. Der pro-Host-SFTP-Mutex erscheint als
<code>SFTP/<user@host:port></code>, der pool-weite Mutex als
<code>SFTP/pool</code>. Per Rechtsklick:

* '''Copy Waiters Stack to Clipboard''' — schreibt den Walkback des letzten Eigners samt aller Waiter als Text in die Zwischenablage. Unverzichtbar, wenn ein Prozess in
<code>readWait</code> innerhalb von
<code>withSftpClientDo:</code> klemmt.
* '''Copy List to Clipboard''' — die ganze Tabelle, ideal für eine E-Mail-Diagnose.
* '''Detect Deadlocks''' — DFS über den Wait-for-Graph, meldet Zyklen.

=== Logger ===

Interessante Ereignisse werden über <code>Logger</code> geloggt:

* <code>warning:</code> bei automatischem Reconnect nach toter Verbindung.
* <code>warning:</code> bei Idle-Verdrängung eines Pool-Eintrags.
* <code>warning:</code> wenn eine SSH-Schlüsseldatei nicht geparst werden konnte — die Datei wird übersprungen.

== Einschränkungen ==

* '''Nur SFTP v3.''' Kein SETSTAT (kein entferntes chmod / chown / utime), kein SSH_FXP_READLINK exponiert (<code>#isSymbolicLink</code> liefert immer <code>false</code>,
<code>#linkInfo</code> die normale stat-Info). Einige
SFTPv5+-Annehmlichkeiten werden dennoch über OpenSSH-spezifische
SSH_FXP_EXTENDED-Aufrufe nutzbar — siehe
[[#OpenSSH-SFTP-Erweiterungen]] weiter unten.
* '''Serialisierung pro Host.''' Zwei gleichzeitige Operationen am selben Host stehen am Host-Mutex an. Siehe [[#Ausblick]].
* '''<code>#renameTo:</code>-Fallback hat ein TOCTOU-Fenster.''' Bei Servern, die <code>posix-rename@openssh.com</code> ankündigen (jedes moderne OpenSSH tut das), ist das Überschreiben atomar. Beim seltenen Server, der das nicht tut, wird auf Delete-dann-Rename ausgewichen und ein anderer Prozess kann sich dazwischenschieben.
* '''<code>#isNonEmptyDirectory</code> ist eine Heuristik.''' Liefert immer <code>#isDirectory</code> (die genaue Antwort würde drei Roundtrips pro Verzeichnis-Symbol kosten, was das ursprüngliche Baum-Ausklappen unerträglich gebremst hatte).

== Implementierungsdetails ==

Für Leser, die die Architektur verstehen wollen. Fünf Klassen,
von oben nach unten:

{| class="wikitable"
! Klasse !! Aufgabe
|-
| <code>SSH::SftpFilename</code> || Filename-Unterklasse, die
öffentliche API. Bildet <code>sftp://...</code>-URLs auf
entfernte Dateien ab und stellt <code>directoryContents</code>,
<code>readingFileDo:</code>, <code>renameTo:</code> usw. bereit.
|-
| <code>SSH::SftpClient</code> || SFTP-v3-Protokoll
(Request/Response-Codec, listDir, stat, open, read, write, mkdir).
Wird von SftpFilename angesteuert.
|-
| <code>SSH::Channel</code> || SSH-Kanal-Multiplexer (CHANNEL_OPEN,
DATA, EOF, CLOSE, WINDOW_ADJUST). Eine logische Sitzung pro
Channel-Instanz.
|-
| <code>SSH::Client</code> || High-Level-SSH-Client: öffnet den
Transport, führt KEX, Hostschlüssel-Prüfung und userauth durch und
verteilt anschließend Kanäle.
|-
| <code>SSH::Transport</code> || Drahtschicht. Banner- und
KEXINIT-Austausch, ChaCha20-Poly1305-Paket-Framing, sendSeq /
recvSeq, Heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH-SFTP-Erweiterungen ===

SFTP v3 (Entwurf draft-ietf-secsh-filexfer-02) ist bewusst
minimal gehalten. OpenSSH bringt einen offenen
Erweiterungsmechanismus mit: der Server listet im
<code>SSH_FXP_VERSION</code>-Reply die Erweiterungsnamen auf, die
er versteht, und der Client ruft sie über
<code>SSH_FXP_EXTENDED(200)</code>-Pakete mit dem
Erweiterungsnamen als erstem String auf. Jede Erweiterung wird
über <code>SSH::SftpClient>>supportsExtension:</code>
feature-detektiert; Aufrufer fallen zurück, wenn der Server sie
nicht ankündigt.

Der Stack nutzt heute vier OpenSSH-Erweiterungen:

* <code>posix-rename@openssh.com</code> — atomares rename-mit-Überschreiben. Wird automatisch von
<code>SftpFilename>>renameTo:</code> aufgegriffen; die
Delete-dann-Rename-Fallback-Variante kommt nur bei Servern zum
Einsatz, die die Erweiterung nicht haben.
* <code>hardlink@openssh.com</code> — Erzeugt einen POSIX-Hardlink. Verfügbar als <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX-
<code>statvfs(3)</code>-typische Dateisystem-Statistik.
Verfügbar als <code>SftpFilename>>fileSystemInfo</code>;
das Ergebnis ist form-kompatibel zu
<code>OperatingSystem getDiskInfoOf:</code>, sodass Aufrufer
lokale und entfernte Pfade einheitlich behandeln können.
Treibt den Menü-Eintrag '''Tools → Filesystem Info...''' an,
der am Anfang dieser Seite beschrieben ist.
* <code>fsync@openssh.com</code> — schreibt den serverseitigen Schreibpuffer eines geöffneten Handles auf Platte. Liegt als
<code>SftpClient>>fsyncHandle:</code> bereit; noch nicht
in eine "Durable-Write"-API auf Filename-Ebene eingebunden.

Die verbleibenden OpenSSH-Erweiterungen
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
werden in der angekündigten Liste erkannt, aber nicht auf
Filename-Ebene gekapselt — es gibt dafür noch keinen
Filename-seitigen Aufrufer.

=== Verbindungs-Pooling ===

Alle <code>SftpFilename</code>-Instanzen, die auf dasselbe Tripel
<code>user@host:port</code> zeigen, teilen sich einen
<code>SSH::Client</code> samt einem <code>SSH::SftpClient</code>.
Der Pool ist klassenseitig und wird von einem einzigen
<code>ConnectionPoolMutex</code> bewacht:

* '''Lazy-Aufbau''' — TCP + KEX + userauth + SFTP-INIT laufen erst beim ersten SFTP-Aufruf, nicht in <code>forUrl:</code>.
* '''Serialisierung pro Host''' — SFTP-Anfragen an einen bestimmten Host werden durch einen <code>RecursionLock</code> mit dem Namen <code>SFTP/<user@host:port></code> serialisiert (sichtbar im SemaphoreMonitor).
* '''Idle-Verdrängung''' — ein Pool-Eintrag, der länger als
<code>idleEvictionSeconds</code> ungenutzt liegt, wird beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet.
* '''Automatischer Reconnect''' — ein Fehler auf Transportebene (Broken Pipe, EOF, MNU auf nil-Socket) verdrängt den Pool-Eintrag, öffnet einen frischen Client und wiederholt die Anfrage '''einmal'''. Anwendungsfehler aus SFTP-STATUS-Antworten werden sofort durchgereicht.

== Ausblick ==

Geplant, aber noch nicht umgesetzt:

* '''Multi-Channel-Parallelität pro Host''' — aktuell bedeutet eine TCP- plus eine SFTP-Verbindung pro Host, dass N gleichzeitige Anfragen serialisieren. Pipelining über mehrere SshClients im Pool (bevorzugt) oder ein transport-seitiger Reader-Prozess, der eingehende Pakete in Pro-Kanal-Postfächer demultiplext, würde es dem Baum-Panel erlauben, weiter aufzulisten, während das Inhalts-Panel eine große Datei liest.
* '''Genaues <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (nur erstes Batch) + CLOSE — drei Roundtrips pro Sondierung; lohnt erst, wenn der SftpClient Anfragen pipelinen kann.
* '''SFTP-v5/v6-Aushandlung''' für erweiterte Attribute und FTP-artige Kanonisierung. (Atomares Überschreibungs-rename ist bereits über die OpenSSH-Erweiterung
<code>posix-rename@openssh.com</code> abgedeckt; siehe
[[#OpenSSH-SFTP-Erweiterungen]].)

= Kommando-Shell =

Lokale Kommando-Shell auf dieser expecco-Maschine. Typische
Anwendungen: lokale Kommandozeile, lokales Hilfsprogramm,
Brücke zwischen entferntem Workflow und lokalem Tool.

Das RemoteAccess-Plugin stellt bereit:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

Keine Zugangsdaten, kein Netzwerk — läuft als der Benutzer des
expecco-Prozesses. Ausgaben gehen in das expecco-Log.

= Telnet =

[[File:Warning.svg|24px|Warnung]] '''Telnet ist ein veraltetes
Protokoll ohne Verschlüsselung.''' Passwörter werden im Klartext
über die Leitung übertragen; jeder im Netzpfad kann sie lesen.
Telnet NUR einsetzen, wenn die Gegenstelle keine Alternative
bietet (typisch: alte Industriesteuerungen, Laborgeräte,
eingebettete Messgeräte ohne SSH-Stack). Für alles andere
[[#SSH und SFTP]] verwenden.

Das expecco-Plugin stellt bereit:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (interne Demo)

Das Telnet-Protokoll (RFC 854) ist ein bidirektionaler
8-Bit-Byte-Strom über TCP, mit In-Band-Steuersequenzen für
Terminal-Optionen. Verbindungsaufbau zum Ziel-Host:Port; nach
optionalem In-Band-Login können beide Seiten Daten senden.

= Siehe auch =

* [[SSH Client|SSH::Client]] — die SSH-Schicht (exec, TTY, Agent-Weiterleitung, ProxyJump).
* [[FileBrowserV2]] — die Haupt-UI dieses Stacks.
* [[ClaudeCode plugin|Claude Code]] — nutzt denselben SSH-Stack als HTTPS-Transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Netz]]
[[Category:SSH]]

Remote Access/en

2026-08-21T18:18:58Z

Sv: add native SSH/SFTP action blocks (26.2) to 'From expecco actions'

{{Languages|Remote Access/en|label=English}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation in <code>exept:libcrypt/ssh</code>; no external dependency on OpenSSL or libssh. Use this for anything that touches credentials or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine. Used for local-tool integration and for the local end of a remote workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No encryption, passwords on the wire in clear. Use only when the target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code> subclass that lets the rest of ST/X treat a remote SFTP path the same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user[:password]@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>. The optional <code>:password</code> piece is the
RFC-3986-style userinfo password — see
[[#Password authentication]] for when this is appropriate and what
the security trade-offs are. When present, it is used as a USERAUTH
fallback after the normal publickey/agent attempts and is '''never'''
re-emitted by the printable URL form, so logging the filename does
not leak the credential.

The '''Refresh''' button in the toolbar (the round-arrow icon
between ''Forward'' and ''DirectoryUp'') re-reads both the
directory tree and the contents pane on demand. Works uniformly
for local and SFTP paths; for SFTP it also flushes the per-file
STAT cache, so changes made directly on the remote side become
visible immediately rather than waiting for the 5-second cache TTL
to expire.

The small arrow next to the Refresh icon opens a dropdown with a
single checkbox, '''Automatic Refresh''', controlling the
background polling task that walks every expanded tree item to
detect external changes. The default depends on the current root:

* Local filesystem → '''on''' (10-second cycle, matches the long-standing behaviour).
* SFTP → '''off'''. Each cycle costs one STAT round-trip per child, which is fine for a handful of local directories but painful over the network. Click Refresh manually when you need to pick up remote changes.

When you navigate between local and SFTP roots the toggle flips
automatically — but only if you haven't overridden it for
the previous root. An explicit user choice is preserved across
navigations.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a remote host.
* '''SFTP Connect...''' — points this browser tab at a remote filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of the filesystem holding the currently displayed directory. Works uniformly for local paths and SFTP paths; for SFTP it requires the server to advertise the <code>statvfs@openssh.com</code> extension (every modern OpenSSH does). Sizes are reported in IEC binary units (MiB, GiB, TiB) — the largest unit yielding a value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB'' rather than ''10240 GiB''.

== From the Launcher ==

The Launcher's '''Workspace''' submenu carries two stand-alone
entries (gated on the SSH package being loaded):

* '''SSH Terminal''' — prompts for a target in the form <code>user[:password]@host[:port]</code> and opens a top-level VT100 terminal connected to it. No FileBrowser involved — this is the launcher analogue of the FileBrowserV2 '''Tools → SSH Connect...''' entry.
* '''SFTP Connection''' — prompts for an SFTP target (same URL grammar as the FileBrowserV2 location bar, see [[#From the FileBrowserV2]]) and opens a fresh FileBrowserV2 already navigated to that path.

Both entries honour the URL-embedded password syntax described in
[[#Password authentication]].

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

Since expecco 26.2 the plugin additionally provides '''native''' SSH and SFTP action blocks, implemented in pure Smalltalk on top of <code>exept:libcrypt/ssh</code> — no external <code>ssh</code> or <code>plink</code> binary is required. A connection is opened once and its <code>SshHandle</code> is passed to the following blocks.

SSH blocks:

* '''SSH - Open Connection''' — connect and authenticate (explicit private key, ssh-agent, or the default <code>~/.ssh</code> keys), yielding an <code>SshHandle</code> for the blocks below.
* '''SSH - Open Connection with Password''' — the same, but authenticating with a plaintext password instead of a key.
* '''SSH - Execute Command''' — run a single command; captures stdout, stderr and exit status, with an optional stdin stream piped to the remote process.
* '''SSH - Execute Commands''' — run a list of commands, each as its own exec channel, on an open connection.
* '''SSH - Execute Commands In Shell''' — run a list of commands in one persistent login shell, so that state such as the working directory carries across commands.
* '''SSH - Close Connection''' — close a connection opened above.

SFTP blocks (each layered on an open <code>SshHandle</code>):

* '''SFTP - Upload File''' and '''SFTP - Upload File from String/Stream''' — write a local file, or in-memory content / a read stream, to a remote path (streamed, without buffering the whole file).
* '''SFTP - Download File''' — read a remote file to a local file and/or into a supplied write stream (streamed, without buffering the whole file).
* '''SFTP - List Directory''' — list the entries of a remote directory.
* '''SFTP - Delete File''', '''SFTP - Rename''' and '''SFTP - Make Directory''' — remote file management.

Each of these blocks ships with a runnable Test/Demo network (its ''Test/Demo'' tab) that connects to the host given by the <code>DEMO_SSH_HOST</code>, <code>DEMO_SSH_PORT</code> and <code>DEMO_SSH_USER</code> environment variables.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code> (or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only; gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file unencrypted (agent-only mode ignores the passphrase, since the OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to '''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally; a ST/X on the Windows side does not. Bridging needs a helper like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Password authentication ==

Public-key (with or without ssh-agent) is the recommended path.
Password authentication is supported as a fallback for the cases
where keys are not available: legacy hosts, on-the-fly access to a
test box, scripted access to an account whose owner refuses to add
your public key. Keep in mind:

* The plaintext password lives in memory on the ST/X side for the lifetime of the <code>SSH::Client</code> — treat it like any other in-memory secret.
* The server still controls which methods it accepts. If <code>sshd_config</code> has <code>PasswordAuthentication no</code>, no Smalltalk-side configuration can override that.
* Wire-level the handshake is RFC 4252 §8: the password is sent inside the encrypted SSH transport, never in clear over the network.

=== From a URL ===

Both the FileBrowserV2 location bar and the launcher's
'''Workspace → SFTP Connection''' / '''Workspace → SSH
Terminal''' prompts accept an inline password in the standard
RFC-3986 userinfo position:

<pre>
sftp://alice:s3cret@host.example.com/srv/data
ssh alice:s3cret@host.example.com:2222
</pre>

The parser splits on the '''last''' <code>@</code> so passwords
containing <code>@</code> still parse; the first <code>:</code>
inside the userinfo separates user from password. Passwords
containing <code>:</code> are not supported in this form —
use the programmatic API below.

The password is stripped from the printable URL: every place that
ends up logging or displaying the filename (status line,
<code>printOn:</code>, <code>nameString</code>, the breadcrumb path)
shows the credential-free form
<code>sftp://alice@host.example.com/...</code>.

=== From code ===

Two equivalent ways to attach a password to an
<code>SSH::Client</code>:

<pre>
"/ literal -- simplest, password is just an ivar
client := SSH::Client newToHost:'host.example.com' port:22 user:'alice'.
client password:'s3cret'.
client connect.
</pre>

<pre>
"/ callback -- lazy; the password never lives on the client.
"/ Useful with an interactive prompt, a keychain lookup, or a
"/ vault-fetched secret that you do not want long-lived in memory.
client passwordCallback:[ Dialog requestPassword:'SSH password' ].
client connect.
</pre>

The callback wins if both are set. Both are evaluated lazily
during <code>#connect</code>, after publickey/agent attempts have
been rejected, so a working key always wins over a password when
both are configured.

=== Authentication order ===

<code>SSH::Client>>authenticate</code> walks every available
credential in this order, returning on the first one the server
accepts:

# ssh-agent identities, if <code>#useAgent</code> was called and the agent has loaded keys.
# ed25519 private-key seed, if <code>#privateKeyFromFile:</code> picked one up.
# RSA private key.
# ECDSA private key.
# Password, if <code>#password:</code> / <code>#passwordCallback:</code> was set '''and''' the server still advertises <code>password</code> in its USERAUTH_FAILURE methods list.

Each step is skipped when the server's last
<code>USERAUTH_FAILURE</code> reply dropped the relevant method
from its allowed list — we do not bang on
<code>publickey</code> after the server stops offering it. The
password attempt is only fired when the server still wants
<code>password</code>, so a misconfigured client password against a
key-only server raises a clean
<code>SSH::AuthenticationError</code> without an extra useless
round-trip.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's walkback plus each waiter's, formatted as plain text. Use when a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed (e.g. legacy PEM, encrypted-without-agent) — the file is skipped, others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime), no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On servers that advertise <code>posix-rename@openssh.com</code> (every modern OpenSSH does), overwrite is atomic; on the rare server that does not, the receiver is emulated as delete-then-rename and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always returns <code>#isDirectory</code> (the accurate answer would cost three round-trips per directory icon, which made the original tree expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link. Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe, EOF, MNU on nil socket) evicts the dead pool entry, opens a fresh client, retries the request '''once'''. Application-level SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP + one SFTP channel per host means N concurrent requests serialise. Pipelining over multiple SshClients in the pool (preferred), or a transport-level reader process demultiplexing to per-channel inboxes, would let the tree pane keep listing while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (first batch only) + CLOSE — three RTTs per probe; needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style canonicalisation. (Atomic-overwrite rename is already handled via the OpenSSH <code>posix-rename@openssh.com</code> extension; see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]

Release Notes 26.x

2026-08-21T12:10:26Z

Sv: 26.2: the four SNMP entries consolidated into one

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==
* Feature: [[ElementaryBlock_Element/en#Scheme_Blocks_(Bridged)|bridged Scheme]] (currently only Racket Scheme) action blocks
* Feature: [[ElementaryBlock_Element/en#Octave_Blocks_(Bridged)|bridged Octave/Matlab]] action blocks
* Feature: [[Expecco_API/en#C#_Actions|bridged C#]] action blocks
* Feature: '''NEW''' AI Coding provider "'''Claude Code (subscription)'''" — uses your existing Claude subscription via the locally installed ''Claude Code'' command line program instead of an API key, so no key has to be entered and no per-token API charges are billed. Choose it like any other provider in the settings dialog (Plugins → AI Coding); the API key, endpoint URL and proxy fields are hidden for it because they do not apply, and the authentication method reads "Subscription (external login)". It requires ''Claude Code'' to be installed and logged in once (run <code>claude</code> in a terminal and complete the login). The model is selectable either as a tier alias (''sonnet'', ''opus'', ''haiku'' — always the current model of that tier) or as a pinned model id.
* Feature: two new AI actions that work on the selected '''class''' rather than on a single method, reachable from the '''AI''' menu of the class browser: "'''Explain Class'''" explains the class as a whole — what it is responsible for, what its instance variables hold and how its protocols fit together — and "'''Generate Class Documentation'''" proposes a class documentation text which the "[Apply]" button installs into the class' documentation.
* Feature: HTTP/2 (h2) support in the embedded web server, negotiated via TLS ALPN, with HPACK header compression and request multiplexing over a single connection. Implemented in pure Smalltalk, so no external library is required. This is the server side only — the HTTP client (''HTTPInterface'') continues to speak HTTP/1.1. A server configured without a certificate stays on HTTP/1.1, because h2 is negotiated during the TLS handshake; the offer can be turned off with <code>HTTPServer http2Enabled:false</code>.
* Feature: ALM repository project version access in the project tree; see versions directly in a second tree (readonly), drag items out of it, execute test plans etc. Create new version and easy commit.
* Feature: TEAM support; multiple teams users can live-edit the same suite for merge, group development, passing work to other users or demonstration.
* Feature: improved SSDP service announcement
* Feature: full ipV6 UDP support (mostly socketAddress fixes and multicast support)
* Feature: '''NEW''' [[SNMP Plugin Reference/en|SNMP]] support, reimplemented in expecco itself - no ''net-snmp'' installation is needed any more, and the blocks behave identically on every supported platform. SNMP v1, v2c and v3 (authentication with MD5, SHA-1 or one of the SHA-2 protocols of RFC 7860, encryption with DES or AES-128); a whole table read by one block with its rows and their INDEX decoded (ifTable, ipAddrTable, tcpConnTable, ...); many devices asked the same question at once, in parallel; traps and informs both received and sent. An up to date set of MIB modules (net-snmp 5.9.5.2) is delivered, so the names of SNMPv2-MIB, IF-MIB, IP-MIB, TCP-MIB and friends resolve out of the box - the deprecated RFC1213-MIB groups (''at'', ''egp'', ''ipRouteTable'') are not part of it and are shown numerically, add ''RFC1213-MIB.txt'' to a MIB directory ("Add MIB Directory") if a device still needs those names. Fixes on the way: object identifiers were corrupted on 64bit systems, which made most SNMP blocks return wrong values.
* Fix: JSON printer's recursive store detection was generating false positives
* Improvement: better Python syntax highlighter

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports '''Anthropic Claude''', '''OpenAI ChatGPT''', '''ollama''' and others as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via [[Tools_FileBrowser/en|FileBrowser]])
* Feature: public/private keypair generation via a [[Tools_FileBrowser/en|FileBrowser]] menu (for easy SSH setup)
* Improvement: Bundled python3 installer updated to version 3.13.14
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed the [[Number_API_Functions|Number]] stack (see also in [[Numeric_Limits/en| Numeric Limits]]):
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. and type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan). Now all test cases produce a result within the precision limits of their type
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]]
* UI: '''Ctrl-Return''' now accepts the default action in every modal dialog — both the modern SimpleDialog-based ones (check-in log message, search dialogs, ...) and old-style DialogBox-based ones (EnterBox, OptionBox, InfoBox, ...). Unlike plain Return, Ctrl-Return submits the dialog even when the focus is on a multi-line text editor (which normally keeps Return as a newline), so there is no need to tab off the editor first.
* UI: Transcript (the console) always appends text at end.
* UI: Transcript does not scroll to end on incoming text while moving the scrollbar
* Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
* Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
* Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Performance: speedup of cryptographic algorithms (affects key generation and other)
* Performance: tuned loading of stored ets/elf files (30-40% speedup)
* Performance: further speedup when loading test-result archives that embed large execution logs — typical load is roughly a third faster again

Release Notes 26.x

2026-08-21T12:05:47Z

Sv: 26.2 SNMP: link to the plugin page, SHA-2, tables and traps

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==
* Feature: [[ElementaryBlock_Element/en#Scheme_Blocks_(Bridged)|bridged Scheme]] (currently only Racket Scheme) action blocks
* Feature: [[ElementaryBlock_Element/en#Octave_Blocks_(Bridged)|bridged Octave/Matlab]] action blocks
* Feature: [[Expecco_API/en#C#_Actions|bridged C#]] action blocks
* Feature: '''NEW''' AI Coding provider "'''Claude Code (subscription)'''" — uses your existing Claude subscription via the locally installed ''Claude Code'' command line program instead of an API key, so no key has to be entered and no per-token API charges are billed. Choose it like any other provider in the settings dialog (Plugins → AI Coding); the API key, endpoint URL and proxy fields are hidden for it because they do not apply, and the authentication method reads "Subscription (external login)". It requires ''Claude Code'' to be installed and logged in once (run <code>claude</code> in a terminal and complete the login). The model is selectable either as a tier alias (''sonnet'', ''opus'', ''haiku'' — always the current model of that tier) or as a pinned model id.
* Feature: two new AI actions that work on the selected '''class''' rather than on a single method, reachable from the '''AI''' menu of the class browser: "'''Explain Class'''" explains the class as a whole — what it is responsible for, what its instance variables hold and how its protocols fit together — and "'''Generate Class Documentation'''" proposes a class documentation text which the "[Apply]" button installs into the class' documentation.
* Feature: HTTP/2 (h2) support in the embedded web server, negotiated via TLS ALPN, with HPACK header compression and request multiplexing over a single connection. Implemented in pure Smalltalk, so no external library is required. This is the server side only — the HTTP client (''HTTPInterface'') continues to speak HTTP/1.1. A server configured without a certificate stays on HTTP/1.1, because h2 is negotiated during the TLS handshake; the offer can be turned off with <code>HTTPServer http2Enabled:false</code>.
* Feature: ALM repository project version access in the project tree; see versions directly in a second tree (readonly), drag items out of it, execute test plans etc. Create new version and easy commit.
* Feature: TEAM support; multiple teams users can live-edit the same suite for merge, group development, passing work to other users or demonstration.
* Feature: improved SSDP service announcement
* Feature: full ipV6 UDP support (mostly socketAddress fixes and multicast support)
* Feature: new [[SNMP Plugin Reference/en|SNMP]] blocks: read a whole table (ifTable, ipAddrTable, tcpConnTable, ...) with its rows and their INDEX decoded, ask many devices the same question at once, and receive traps and informs with a trap listener as well as send them.
* Improvement: the [[SNMP Plugin Reference/en|'''SNMP''']] blocks no longer use the external ''net-snmp'' library; SNMP v1, v2c and v3 (authentication with MD5, SHA-1 or one of the SHA-2 protocols of RFC 7860, encryption with DES or AES-128) are now implemented in expecco itself and behave identically on all supported platforms.
* Improvement: an up to date set of MIB modules (from net-snmp 5.9.5.2) is delivered with the SNMP library, so symbolic names such as those of IF-MIB, IP-MIB or TCP-MIB are resolved out of the box. The deprecated RFC1213-MIB groups (''at'', ''egp'' and ''ipRouteTable'') are no longer part of it and are shown numerically instead; add ''RFC1213-MIB.txt'' to a MIB directory ("Add MIB Directory") if a device still requires those names.
* Fix: SNMP object identifiers were corrupted on 64bit systems, so that most SNMP blocks returned wrong values.
* Fix: JSON printer's recursive store detection was generating false positives
* Improvement: better Python syntax highlighter

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports '''Anthropic Claude''', '''OpenAI ChatGPT''', '''ollama''' and others as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via [[Tools_FileBrowser/en|FileBrowser]])
* Feature: public/private keypair generation via a [[Tools_FileBrowser/en|FileBrowser]] menu (for easy SSH setup)
* Improvement: Bundled python3 installer updated to version 3.13.14
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed the [[Number_API_Functions|Number]] stack (see also in [[Numeric_Limits/en| Numeric Limits]]):
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. and type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan). Now all test cases produce a result within the precision limits of their type
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]]
* UI: '''Ctrl-Return''' now accepts the default action in every modal dialog — both the modern SimpleDialog-based ones (check-in log message, search dialogs, ...) and old-style DialogBox-based ones (EnterBox, OptionBox, InfoBox, ...). Unlike plain Return, Ctrl-Return submits the dialog even when the focus is on a multi-line text editor (which normally keeps Return as a newline), so there is no need to tab off the editor first.
* UI: Transcript (the console) always appends text at end.
* UI: Transcript does not scroll to end on incoming text while moving the scrollbar
* Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
* Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
* Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Performance: speedup of cryptographic algorithms (affects key generation and other)
* Performance: tuned loading of stored ets/elf files (30-40% speedup)
* Performance: further speedup when loading test-result archives that embed large execution logs — typical load is roughly a third faster again

Weitere Plugins

2026-08-21T12:05:46Z

Sv: SNMP Plugin ergaenzt

* [[Code Ausführung]]
* [[Daten/Nachrichten/Dokument Formate]]
* [[QM Schnittstellen]]
* [[Import/Export von Spezifikationen]]
* [[Databases|Datenbanken]]

* [[NoSQL|NoSQL Datenbanken]]
* [[GembirdPowerControlPlugin Reference]] -- kontrolliert eine fernsteuerbare Stromversorgung zum autom. An- bzw. Abschalten von Geräten (Teil des Basissystems)
* [[SNMP Plugin Reference/en|SNMP Plugin]] -- fragt SNMP-fähige Geräte ab (Router, Switches, Drucker, Server, USVs), liest ganze Tabellen und empfängt bzw. sendet Traps (Teil des Basissystems)

SNMP Plugin Reference/en

2026-08-21T12:01:07Z

Sv: SNMP plugin description: library blocks, protocol versions, MIBs, tables, traps, Test/Demo variables

== SNMP Plugin ==
The SNMP plugin lets a test suite talk to SNMP capable equipment - routers, switches, printers, servers,
UPS units, sensors - and receive the notifications such a device sends. It delivers the '''SNMP Library''',
whose blocks cover the manager side of SNMP v1, v2c and v3: reading and writing objects, walking subtrees,
reading whole tables, resolving MIB names, and receiving as well as sending traps.

Everything is implemented in expecco itself. No ''net-snmp'' installation and no other external library is
needed, and the blocks behave the same on every supported platform.

=== The SNMP Library ===
The blocks are found in the library "''SNMP Library''", grouped into six categories. Every block carries its
own documentation, every pin explains what it expects, and every block has a Test/Demo network which shows it
in use.

==== SNMP Connection ====
* '''Open SNMP Session''' - open a session to a device with SNMP v1 or v2c, using a community string.
* '''Open SNMPV3 Session''' - open an SNMPv3 session with a user name, an authentication and an encryption protocol, and the two passphrases. The context name and context engine id can be given for agents which partition their MIB into contexts.
* '''Close SNMP Session''' - release the session and its socket.
* '''SNMP Timeout/Retries''' - how long to wait for an answer and how often to repeat a request.
* '''SNMP Session Info''' - which host, port, version, community and context a session handle refers to.
* '''SNMP Last Error''' - why the last request did not deliver a value, as a symbolic reason (noResponse, timedOut, noSuchName, wrongDigest, notWritable, ...).
* '''SNMP Max Repetitions''' - how many objects one GetBulk request asks for; this is what a walk uses.

==== SNMP Requests ====
* '''SNMP Get''' / '''SNMP Get Next''' / '''SNMP Get Bulk''' - read one object, the object following it, or a batch of following objects.
* '''SNMP Get Subtree''' - walk everything below an object (for instance the whole ''system'' group or an entire table) and answer it as an oid to value dictionary.
* '''SNMP Set''' - write one object. Without an explicit type the type is taken from the MIB definition, and the object is read back afterwards, so the outputs show what the agent really stored.
* '''SNMP Multi Get''' / '''Multi Get Next''' / '''Multi Get Bulk''' / '''Multi Set''' - the same for several objects in ONE request, which is much faster than asking one by one.
* '''SNMP Get with Default''' - read an object which only some devices implement, answering a default instead of failing.
* '''Read SNMP Table''' - read a whole conceptual table (ifTable, ipAddrTable, tcpConnTable, ...) and answer its rows in index order. The rows are also delivered one by one, so a following step can run once per row.
* '''Table Row Value''' / '''Table Row Index''' / '''Table Row as Dictionary''' - read a column of a row by name or number, the decoded INDEX of a row, or the whole row as a columnName to value dictionary.
* '''SNMP Get on Hosts''' / '''SNMP Multi Get on Hosts''' - ask many devices the same question at once. The hosts are queried in parallel, so the block takes about as long as the slowest device rather than the sum of all of them; a host which does not answer is reported, not an error.

==== MIB Access ====
* '''Name to OID''' / '''OID to Name''' - translate between a MIB name (''sysDescr.0'', ''SNMPv2-MIB::sysDescr.0'') and the numeric object identifier.
* '''Resolve OIDs in Dictionary Keys''' / '''... Values''' - replace the OIDs in the result of a walk or a multi get by their MIB names, which is what makes such a result readable in the report.
* '''Describe MIB Object''' - what the MIB knows about an object: full name, syntax, access, status, unit, the labels of an enumerated INTEGER, and whether it is a table or a table row with its INDEX.

==== MIB Management ====
* '''Add MIB Directory''' - parse the MIB files of a directory and add them, so vendor specific names can be used in the other blocks.
* '''Shutdown MIB''' - forget everything read from MIB files; the next name to resolve reads them again.

==== SNMP Traps ====
* '''Start Trap Listener''' - listen for notifications on a UDP port. The standard port 162 needs root privileges on unix, so an unprivileged port such as 11162 is often used.
* '''Wait for Trap''' - wait for the next notification and answer its sender, version, identifier (resolved through the MIB) and all its variables. Notifications which arrived before the block ran are not lost, and an inform request is acknowledged automatically.
* '''Stop Trap Listener''' - stop listening and release the port.
* '''Send Trap''' - send a notification to a trap receiver, as a plain trap or as an inform request which the receiver has to acknowledge.

=== Protocol versions and security ===
SNMP '''v1''' and '''v2c''' identify the caller with a community string, which travels in clear text.

SNMP '''v3''' authenticates and encrypts with the User-based Security Model. Supported protocols:
* authentication: ''md5'' and ''sha1'' (RFC 3414), and the SHA-2 protocols ''sha224'', ''sha256'', ''sha384'' and ''sha512'' (RFC 7860). Current net-snmp builds refuse MD5, so prefer SHA-256.
* encryption: ''des'' and ''aes128'' (RFC 3826). Encryption is only possible together with authentication.

Engine discovery and the clock synchronisation an authenticated session needs happen automatically.

=== MIBs ===
A current set of MIB modules is delivered with the library, so the usual names - those of SNMPv2-MIB, IF-MIB,
IP-MIB, TCP-MIB, UDP-MIB, HOST-RESOURCES-MIB and many more - resolve without any setup. Vendor MIBs are added
with "''Add MIB Directory''", either from a directory of your own or from ''~/.snmp/mibs'', which is read
automatically.

The deprecated RFC1213-MIB groups ''at'', ''egp'' and ''ipRouteTable'' are not part of the delivered set;
objects below them are shown numerically. Their replacements are ''ipNetToMediaTable'', ''ipCidrRouteTable''
and ''inetCidrRouteTable''. If a device really needs the old names, drop ''RFC1213-MIB.txt'' into a MIB
directory.

=== Reading a table ===
"''Read SNMP Table''" answers the rows of a conceptual table. A row knows its columns by name and the INDEX
which identifies it, and "''Table Row Index''" decodes that INDEX as the MIB defines it - the interface number
for ''ifTable'', the IP address for ''ipAddrTable'', the four parts of a connection for ''tcpConnTable''.
Values arrive as Smalltalk objects: a counter as a number, an ''ifOperStatus'' as its label (''up'', ''down''),
an IP address as an address, ''sysUpTime'' as a time duration.

=== Traps and informs ===
A test can wait for a notification instead of polling: start a listener, let the device do whatever should
trigger the trap, and read it with "''Wait for Trap''". Traps of all three versions are accepted; for SNMPv3
the sender is the authoritative engine, so the listener localizes the keys per sending device by itself.
Notifications which do not authenticate, or whose community is not accepted, are dropped silently.

An inform request is acknowledged automatically, and "''Send Trap''" can send one, so a suite can also play
the role of the device.

=== Test/Demo networks ===
Every block has a Test/Demo network. The ones which need a device use these environment variables of the
library, so that one place decides which equipment the demos talk to:

{| class="wikitable"
! Variable !! Meaning
|-
| DemoSNMPHost || the device the demos read from
|-
| DemoSNMPCommunity || the community string used for v1 / v2c
|-
| DemoSNMPV3User || the SNMPv3 user name
|-
| DemoSNMPV3AuthPassphrase || its authentication passphrase (the demo agent uses SHA-256)
|-
| DemoSNMPV3PrivPassphrase || its encryption passphrase (the demo agent uses AES-128)
|}

Change them to a device of your own before running the demos. The trap demos need nothing on the network -
they start a listener, send themselves a trap and read it back.

=== See also ===
* [https://www.rfc-editor.org/rfc/rfc3416 RFC 3416] - the SNMP protocol operations
* [https://www.rfc-editor.org/rfc/rfc3414 RFC 3414] - the User-based Security Model of SNMPv3
* [https://www.rfc-editor.org/rfc/rfc7860 RFC 7860] - the SHA-2 authentication protocols
* [https://www.rfc-editor.org/rfc/rfc2578 RFC 2578] - SMIv2, how a MIB module is written

[[Category:Plugins]]

Release Notes 26.x

2026-08-16T14:38:25Z

Sv: 26.2: SNMP without net-snmp, current MIBs, 64bit OID fix

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==
* Feature: [[ElementaryBlock_Element/en#Scheme_Blocks_(Bridged)|bridged Scheme]] (currently only Racket Scheme) action blocks
* Feature: [[ElementaryBlock_Element/en#Octave_Blocks_(Bridged)|bridged Octave/Matlab]] action blocks
* Feature: [[Expecco_API/en#C#_Actions|bridged C#]] action blocks
* Feature: '''NEW''' AI Coding provider "'''Claude Code (subscription)'''" — uses your existing Claude subscription via the locally installed ''Claude Code'' command line program instead of an API key, so no key has to be entered and no per-token API charges are billed. Choose it like any other provider in the settings dialog (Plugins → AI Coding); the API key, endpoint URL and proxy fields are hidden for it because they do not apply, and the authentication method reads "Subscription (external login)". It requires ''Claude Code'' to be installed and logged in once (run <code>claude</code> in a terminal and complete the login). The model is selectable either as a tier alias (''sonnet'', ''opus'', ''haiku'' — always the current model of that tier) or as a pinned model id.
* Feature: two new AI actions that work on the selected '''class''' rather than on a single method, reachable from the '''AI''' menu of the class browser: "'''Explain Class'''" explains the class as a whole — what it is responsible for, what its instance variables hold and how its protocols fit together — and "'''Generate Class Documentation'''" proposes a class documentation text which the "[Apply]" button installs into the class' documentation.
* Feature: HTTP/2 (h2) support in the embedded web server, negotiated via TLS ALPN, with HPACK header compression and request multiplexing over a single connection. Implemented in pure Smalltalk, so no external library is required. This is the server side only — the HTTP client (''HTTPInterface'') continues to speak HTTP/1.1. A server configured without a certificate stays on HTTP/1.1, because h2 is negotiated during the TLS handshake; the offer can be turned off with <code>HTTPServer http2Enabled:false</code>.
* Feature: ALM repository project version access in the project tree; see versions directly in a second tree (readonly), drag items out of it, execute test plans etc. Create new version and easy commit.
* Feature: TEAM support; multiple teams users can live-edit the same suite for merge, group development, passing work to other users or demonstration.
* Feature: improved SSDP service announcement
* Feature: full ipV6 UDP support (mostly socketAddress fixes and multicast support)
* Improvement: the '''SNMP''' blocks no longer use the external ''net-snmp'' library; SNMP v1, v2c and v3 (authentication with MD5 or SHA-1, encryption with DES or AES-128) are now implemented in expecco itself and behave identically on all supported platforms.
* Improvement: an up to date set of MIB modules (from net-snmp 5.9.5.2) is delivered with the SNMP library, so symbolic names such as those of IF-MIB, IP-MIB or TCP-MIB are resolved out of the box. The deprecated RFC1213-MIB groups (''at'', ''egp'' and ''ipRouteTable'') are no longer part of it and are shown numerically instead; add ''RFC1213-MIB.txt'' to a MIB directory ("Add MIB Directory") if a device still requires those names.
* Fix: SNMP object identifiers were corrupted on 64bit systems, so that most SNMP blocks returned wrong values.
* Fix: JSON printer's recursive store detection was generating false positives
* Improvement: better Python syntax highlighter

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports '''Anthropic Claude''', '''OpenAI ChatGPT''', '''ollama''' and others as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via [[Tools_FileBrowser/en|FileBrowser]])
* Feature: public/private keypair generation via a [[Tools_FileBrowser/en|FileBrowser]] menu (for easy SSH setup)
* Improvement: Bundled python3 installer updated to version 3.13.14
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed the [[Number_API_Functions|Number]] stack (see also in [[Numeric_Limits/en| Numeric Limits]]):
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. and type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan). Now all test cases produce a result within the precision limits of their type
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]]
* UI: '''Ctrl-Return''' now accepts the default action in every modal dialog — both the modern SimpleDialog-based ones (check-in log message, search dialogs, ...) and old-style DialogBox-based ones (EnterBox, OptionBox, InfoBox, ...). Unlike plain Return, Ctrl-Return submits the dialog even when the focus is on a multi-line text editor (which normally keeps Return as a newline), so there is no need to tab off the editor first.
* UI: Transcript (the console) always appends text at end.
* UI: Transcript does not scroll to end on incoming text while moving the scrollbar
* Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
* Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
* Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Performance: speedup of cryptographic algorithms (affects key generation and other)
* Performance: tuned loading of stored ets/elf files (30-40% speedup)
* Performance: further speedup when loading test-result archives that embed large execution logs — typical load is roughly a third faster again

KI Coding Plugin

2026-08-06T08:36:52Z

Sv: Cgs Korrekturen in Individuelle Toolrechte wiederhergestellt (von mir versehentlich ueberschrieben)

{{Languages|KI Coding Plugin|label=Deutsch}}

= KI Coding Plugin =

Die hier beschriebenen KI-Funktionen sind Teil des Lizenz-Features '''AI Coding'''. Ist dieses Feature in Ihrer Lizenz nicht enthalten, erscheinen die ''Ask AI''-Menüeinträge zwar weiterhin sichtbar in den Editor-Toolbars, sind aber deaktiviert (Tooltip: "''Install the AI coding plugin to enable''").

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic (aka Claude)''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI (i.e. ChatGPT)''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
* '''llama.cpp''' lokal oder remote
* '''Groq''', '''Zen''', '''LLaMa''', '''Tabnine''' etc.
* '''Claude Code (subscription)''' — nutzt Ihr vorhandenes Claude-Abonnement statt eines API-Schlüssels ''(verfügbar ab expecco 26.2)''
* '''Inhouse''' — ihre eigene in-house (in-Firma) KI.

Wichtig: 
Der zusätzliche Eintrag '''Inhouse''' ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern oder einer anderen fimeninternen KI chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Lizenzierung ==

Die KI-Funktionen sind auf '''zwei getrennte Lizenz-Features''' aufgeteilt. Die Trennung verläuft genau entlang der Grenze zwischen ''lesen'' und ''verändern'':

* '''KI Coding''' (im Lizenzfile: ''AI Coding'') — die Grundlizenz. Sie lädt das Plugin überhaupt erst und schaltet Chat-Fenster, Anbieterauswahl und die lesenden (''safe'') Werkzeuge frei.
* '''KI Advanced Coding''' (im Lizenzfile: ''AI Advanced Coding'') — ein eigenes, zusätzlich zu erwerbendes Feature. Es setzt ''KI Coding'' voraus und schaltet die schreibenden (''unsafe'') Werkzeuge frei.

=== KI Coding ===

Ohne dieses Feature ist das Plugin nicht geladen: die ''Ask AI''-Einträge bleiben in den Editor-Toolbars sichtbar, sind aber deaktiviert (Tooltip: "''Install the AI coding plugin to enable''").

Mit ''KI Coding'' können Sie in vollem Umfang mit dem Modell arbeiten, solange es dabei bleibt, Ihr Projekt zu ''lesen'': Elemente suchen, Netzwerke und Quellcode analysieren, Aktivitylogs auswerten, Dokumentation entwerfen, Fehlerursachen erklären lassen. Vorschläge des Modells — etwa neuer Quellcode für eine Elementaraktion — erscheinen im Chat-Fenster und werden von Ihnen bewusst übernommen (''Apply''-Knopf oder copy/paste). Die Entscheidung, ob eine Änderung in die Suite gelangt, liegt in jedem Einzelfall bei Ihnen.

=== KI Advanced Coding ===

Dieses Feature schaltet die Werkzeuge frei, mit denen das Modell Ihr Projekt und Ihre Arbeitsumgebung '''selbst verändern''' kann — im Wesentlichen die im Abschnitt [[#Unsafe Tools|Unsafe Tools]] aufgeführten Funktionen: Elemente anlegen, Netzwerke ändern, Methoden und Klassen definieren, Aktionen und Testfälle ausführen sowie Änderungen in die Versionsverwaltung einchecken.

Fehlt das Feature, stehen diese Werkzeuge '''auch dann nicht zur Verfügung, wenn sie im ChatView ausdrücklich erlaubt wurden'''. Das Modell erhält in diesem Fall eine Fehlermeldung statt der Ausführung; die Sitzung läuft normal weiter.

=== Sicherheitsaspekte ===

Die Lizenz ist die '''äußere''' von zwei voneinander unabhängigen Schutzschichten. Beide müssen eine Aktion erlauben, damit sie ausgeführt wird:

* '''Lizenz-Ebene''' (''KI Advanced Coding'') — organisatorisch, gilt für die gesamte Installation und ist '''vom Anwender nicht umschaltbar'''. Sie hängt an der signierten Lizenzdatei und lässt sich nicht über eine Einstellung, eine Umgebungsvariable oder eine Konfigurationsdatei aktivieren.
* '''Laufzeit-Ebene''' (''MCP''-Knopf, Tools-Menü, Planungsmodus) — situativ, gilt für die einzelne Chat-Sitzung und ist vom Anwender jederzeit umschaltbar. Siehe [[#Individuelle Toolrechte|Individuelle Toolrechte]].

Daraus ergeben sich die praktisch wichtigen Eigenschaften:

* '''Eine Organisation kann verbindlich festlegen, dass die KI grundsätzlich nur lesend arbeitet.''' Wird ''KI Advanced Coding'' nicht lizenziert, bleibt es dabei — unabhängig davon, was einzelne Anwender in ihrem ChatView einstellen, und unabhängig davon, ob jemand versehentlich "Alle Tools automatisch erlauben" aktiviert.
* '''Grundsatz der geringsten Rechte.''' Der Auslieferungszustand ist lesend; Schreibrechte müssen bewusst erworben werden und sind damit auch eine dokumentierte Entscheidung, kein Nebeneffekt einer Voreinstellung.
* '''Die Prüfung gilt auch für den Zugriff von außen.''' Greift ein externes CLI-Programm (''claude code'', ''cursor'', ''zed'', ''tabnine'') über das MCP-Protokoll auf expecco zu, unterliegen die schreibenden Werkzeuge derselben Prüfung. Ein externes Programm kann sie nicht umgehen — es erhält dieselbe Fehlermeldung wie das Modell im internen Chat.
* '''Der Prüfpunkt liegt bei der Ausführung, nicht in der Oberfläche.''' Die Werkzeuge werden nicht lediglich im Menü ausgeblendet; der Aufruf selbst wird abgewiesen. Ein ausgeblendeter Menüeintrag wäre keine Sicherheitsmaßnahme.

Ebenso wichtig ist, was die Lizenz '''nicht''' leistet:

* Sie begrenzt, '''was die KI in expecco tun darf''' — nicht, '''welche Daten das Haus verlassen'''. Welcher Anbieter Ihren Quellcode zu sehen bekommt, entscheidet allein die Anbieterwahl; siehe [[#Datenschutz / Datenfluss|Datenschutz / Datenfluss]]. Auch mit reinem ''KI Coding'' wird beim Einsatz eines Cloud-Anbieters Projektinhalt übertragen.
* Sie ersetzt nicht die Prüfung dessen, was das Modell vorschlägt. Auch eine lizenzierte Änderung ist eine Änderung eines Modells und gehört wie jeder fremde Beitrag reviewt.
* Sie schützt nicht vor einem kompromittierten CLI-Programm auf demselben Rechner. Für sicherheitskritische Umgebungen gelten weiterhin die Hinweise im Abschnitt [[#Tool Use|Tool Use]] zur Isolation solcher Rechner.

Für eine sicherheitskritische Umgebung ergibt sich daraus die restriktivste sinnvolle Konfiguration: ''KI Coding'' ohne ''KI Advanced Coding'', kombiniert mit einem lokal betriebenen Modell (''ollama'' oder ''llama.cpp''). Dann verlässt kein Projektinhalt Ihr Netz, und die KI kann ausschließlich lesen und vorschlagen.

== Architektur und Sicherheit ==

Mit "''Sicherheit''" ist hier gemeint: "''können die Daten den Rechner oder ihre Abteilung/Firma verlassen'' bzw. ''kann die KI Schaden anrichten indem sie auf Ihrem Rechner unkontrolliert Code ausführt oder Daten manipuliert''".

Anmerkung: Wenn hohe Sicherheit gefordert ist (sensible Daten, Algorithmen, Workflows) muss Ihr Netzadmin durch geeignete Maßnahmen (Firewall, Router/Switch Konfiguration etc.) verhindern, dass Zugriffe sowohl ausgehend als auch eingehend zu/von außerhalb ihrer Domäne möglich sind.
Das "unsichtbar machen" entsprechender Einstellungsdialoge in expecco wäre hierzu nicht dienlich, da bei offenen Ports unzählige andere Möglichkeiten bestehen (curl, webbrowser, low-level Socket API etc.).

Zur Sicherheit ihrer eigenen Testsuite und möglichen Aktionen der KI lesen Sie bitte die unten aufgeführten Abschnitte zu [[#tool_use|"Tool Use"]].

=== Architektur ===

Im folgenden werden die Einstellungen und die zugehörigen Datenflüsse/kanäle beschrieben.

Mögliche Setups sind:

==== KI Firmenintern ====
* direkte Verbindung zu einer KI auf einem Rechner in ihrem lokalen Netzwerk, Firmennetz oder einem definiert sicheren Firmenanbieter. Sicherheit: '''Hoch''' (weder Daten noch Chat-Text gehen aus dem Haus)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:InhouseSetup1.png|Einstellung
Datei:ArchInhouseSetup1.png|Architektur
</gallery>
:expecco kommuniziert ausschließlich und direkt zu dieser URL; keine Applikation dazwischen. Insbesondere kein "<code>claude.exe</code>" oder ein anderes Command Line Interface (CLI) Programm. Ihre Eingaben im expecco Chat Fenster gehen direkt (verpackt als JSON) an die konfigurierte Adresse und deren Antwort erscheint (entpackt aus JSON) im expecco Chat Fenster. Nachrichten werden ausschließlich mit dem von Ihnen konfigurierten Host ausgetauscht.

::- wählen Sie dazu "inhouse" und geben hostname+port+URL zu diesem host ein; typischerweise haben diese die Form "<code>firmenAI:11434/v1/chat/completions</code>" oder auch 80 oder 8080 als port. Fragen Sie ihren Netzwerkadmin im Zweifel, auch ob ein API Key (= Zugangsschlüssel) erforderlich ist.

==== KI auf Ihrem eigenen Rechner ====

* direkte Verbindung zu einer lokalen KI auf ihrem eignen persönlichen Rechner Sicherheit: '''Sehr Hoch''' (weder Daten noch Chat verlassen ihren Rechner)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:LocalSetup2.png|Einstellung
Datei:ArchLocalSetup2.png|Architektur
</gallery>
:auch hier kommuniziert expecco ausschließlich und direkt zu diesem ihrem lokalen Rechner, auf der Sie selbst ein Modell installiert und am Laufen haben (ollama oder llama.cpp). Ob dies im einzelnen sinnvoll ist hängt von der Leistungsfähigkeit ihres eigenen Rechners ab (empfohlen wird eine oder mehrere leistungsfähige GPUs mit viel VRAM (>=32Gb), großer RAM Speicherausbau (>=64Gb) und ein leistungsfähiges Modell (mindestens 30B, besser 120B mit großem Kontext,da reichen aber 32GB VRAM nicht); eigene Erfahrungen haben wir unten in diesem Dokument zusammengetragen).
::- wählen Sie dazu "ollama" oder "llama.cpp" und geben als hostname "localhost" ein. Falls sie einen dedizierten Rechner in der Abteilung haben, kann natürlich auch dessen Hostname eingegeben werden.

==== KI von einem Cloudanbieter ====
* direkte Verbindung zu einem externen Anbieter (wie Anthropic, OpenAI etc.). Sicherheit: '''Fragwürdig''' (Sie müssen dem Anbieter und IP Verbindung vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup4.png|Einstellung
Datei:ArchExternalSetup3.png|Architektur
</gallery>
:Die Interaktion erfolgt lediglich mit der von Ihnen eingestellten URL über das expecco-interne chat Fenster. In sicherheitskritischem Umfeld ist jedoch davon abzuraten und ihre Netzadministrator wird diesen Zugang vermutlich auch nicht zulassen da (je nach URL) ihre Daten und ihr Chatverlauf an externe Rechner gehen, oder von fremden Geheimdiensten mitgelesen werden könnten). Prinzipiell sollte dies dem Netzadmin aber bekannt sein, und auf Netzwerkebene gesperrt sein, da ein solcher Zugriff auch anderen Programmen verwehrt werden muss (curl, Webbrowser etc.). Insofern ist ratsam, solche Verbindungen auf administrativer Ebene (Firewall, Router/Switch Konfiguration etc.) zu verhindern. Natürlich gilt diees nicht, falls sie eine eigenen firmeninterne cloud Infrastruktur besitzen, die vertrauenswürdig ist.
::- wählen Sie dazu "Anthropic, OpenAI, ..." und geben hostname+port+URL zu diesem host ein (wobei die Vorgabe im Eingabefeld typischerweise schon passt); typischerweise brauchen die Anbieter einen Zugangsschlüssel (sog. API key), den Sie bei der Registrierung vom Anbieter oder von ihrem Netzadmin erhalten. Achtung: verschiedene Anbieter (u.a. Anthropic) erlauben hier nur die Abrechnung über Ihr Token Budget, nicht über einen Pro/Max oder Enterprise plan. Es kann also hier zu erhöhten Kosten führen. Es ist uns weder technisch noch juristisch möglich, dies zu verhindern.

==== KI über CLI (eg. claude code); Bedienung über CLI ====
* indirekte Verbindung via CLI (z.B. ClaudeCode, Kiro, Tabnine, OpenCode, LMStudio etc.). Sicherheit: '''Unsicher''' (Sie müssen sowohl Anbieter und dem Modell vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup4.png|Einstellung
Datei:ArchExternalSetup1.png|Architektur
</gallery>
:Hier baut ein CLI Programm (z.B. "claude.exe") die Verbindung zum KI Modell auf (was natürlich seinerseits wiederum eine lokale in-house KI sein könnte). Dieses CLI Programm verbindet sich dann mit expecco und hat dort beschränkten Zugriff auf ihre Testsuite (über mcp). Die Interaktion erfolgt mit dem CLI Programm, die Bedienung des Modells erfolgt im CLI Programm. Das CLI hat kontrollieren Zugriff auf expecco über das sog. MCP Protokoll. Es ist zu beachten, dass die Konfiguration dem CLI Zugriff auf Dateien ermöglicht und es auch andere Aktionen auf Ihrem Rechner ausführen kann (shell/batch/powershell, Dateizugriffe etc.). Das Modell kann über das CLI Programm auch auf Ressourcen außerhalb expecco zugreifen. Und es könnte das System bzw. ihr Netz geziehlt ausspionieren oder manipulieren ohne daß expecco dies bemerkt oder verhindert. Sie müssen also sowohl dem Anbieter, der IP Verbindung als auch dem CLI Programm vertrauen.
::- sie müssen dem lokalen CLI Programm den Zugriff auf expecco erlauben. gehen Sie dazu in das "''Extras''" → "''Web-Dienste''" → "''MCP Zugriff erlauben (AI Coding)''". Die Konfiguration zum eigentlichen Modell erfolgt im CLI Programm Ihrer Wahl und ist nicht unter der Kontrolle von expecco; expecco erlaubt damit lediglich die Kontrolle von außerhalb über das MCP Protokoll. Eine Einstellung des Anbieters ist nicht notwendig; sie wird nicht benutzt, können daher beliebige Angaben machen.

==== KI über transparente CLI (nur claude code); Bedienung über ChatView ====
* indirekte Verbindung via unsichtbarer ClaudeCode CLI.
Sicherheit: '''Unsicher''' (Anbieter und Modell vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup5.png|Einstellung
Datei:ArchExternalCLIStdioSetup5.png|Architektur
</gallery>
:Auch hier erfolgt die Verbindung über das ClaudeCode CLI Programm, welches jedoch ohne Benutzeroberfläche den Verkehr lediglich weiter leitet (via stdin/stdout). Die Benutzerinteraktion erfolgt über das expecco-interne chat Fenster, der tatsächliche Modellzugriff vom CLI. Auch hier muss die Konfiguration des Modellzugriffs im CLI Programm erfolgen. Auch hier ist nicht technisch ausgeschlossen, daß das CLI Programm auf Daten außerhalb expecco zugreift. Falls das vom CLI technisch ermöglicht wird, könnte das Modell solche Zugriffe auslösen. Auch hier muß Modell, Verbindung und CLI Programm vertraut werden.

=== Tool Use ===

Der eigentlichen Mehrwert der KI besteht in der Möglichkeit dem Modell Zugriff auf das im expecco gezeigte Testprojekt zu gestatten. Es kann die Elemente des Baums lesen, Netzwerke analysieren und Ergebnisse (AktivityLogs) lesen.

Dazu sendet das Modell sog. "Tool Calls" zurück, die vom Empfänger im JSON Datenstrom erkannt und ausgeführt werden. Diese werden im folgenden "Tool Calls" genannt.

Ist ein CLI Programm (claude.exe, openCode.exe etc.) der Partner des Modells, erfolgt diese Erkennung dort, und die tools werden anhand des Toolnamens entweder im CLI selbst ausgeführt (Dateien lesen der schreiben, shell/batch scripts ausführen, etc.) oder über das sog. MCP Protokoll an Drittprogramme weiter geleitet.
In unserem Fall stellt expecco die unten beschriebenen MCP tools bereit. Neben diesen könnten aber auch andere Aktionen (geheim oder offen) vom CLI ausgeführt werden. Und sie können dem CLI auch andere MCP Zugänge zu anderen Programmen bereitstellen. Sie müssen in diesem Fall also unbedingt dem CLI Programm und dem Modell und der IP Verbindung zur Außenwelt vertrauen. Sollten sie im sicherheitskritischen Umfeld solch ein Setup wählen ist unbedingt geraten, diesen Rechner vom Rest ihres Netzwerks zu isolieren, keine sensiblen Daten auf diesem Rechner zu halten, und den Verkehr zur Außenwelt über einen separaten Kanal abzuwickeln.

Ist kein CLI Programm involviert (i.e. die Verbindung geht von expecco direkt zum Modell) erfolgt die Erkennung von tool calls innerhalb expecco, und es ist dem Modell nicht möglich, andere Aktionen als die unten aufgeführten Funktionen aufzurufen. Sie haben also volle Kontrolle darüber.

==== Tool Funktionen von expecco ====

Diese Funktionen dienen dazu, dem Modell lesend und/oder schreibend auf ihre Testsuite (das im Browser dargestellte Projekt) zuzugreifen. Wie bereits beschrieben sind dies auch Funktionen die über MCP einem CLI Programm zur Verfügung gestellt werden, falls ein CLI Programm involviert ist.

Die expecco tool Funktionen wurden von uns eingeteilt in sog. "Safe" und "Unsafe" tools. Als sicher gelten rein lesende, als unsafe solche welche ihre Suite manipulieren oder Aktionen ausführen können.

Sie können in den expecco Einstellungen festlegen, ob tools generell verboten werden, nur safe tools erlaubt werden, oder auch für jedes individuelle tool eine Erlaubnis gegeben wird. Außerdem können Sie bestimmen ob bei jedem individuellen call eine Nachfrage um Erlaubnis erfolgen soll.

===== Safe Tools =====
* Suche von Elementen im Projekt
* Lesen der Schritte, Verbindungen, Pins, etc. in einem Netzwerk
* Lesen des Quellcodes einer Elementaraktion
* Lesen des Aktivitylogs nach einer Ausführung
* Suchen und Lesen von Hilfsfunktionen im unterliegenden Framework (eg. Smalltalk Basisklassen)

===== Unsafe Tools =====
* Anlegen neuer Elemente
* Änderungen in einem Netzwerk (Schritten, Verbindungen etc.)
* Ausführen einer Aktion, eines Testfalls oder Testplans

==== Im ChatView ====

===== Tool Calls Generell verbieten/erlauben =====

Der "mcp" Button im Chatview bestimmt ob tool calls prinzipiell erlaubt oder verboten werden. Fall generell erlaubt werden die unten beschriebenen Einzeleinstellungen wirksam; falls generell verboten sind diese irrelevant. 
Ohne tool calls können Sie immer noch mit dem Modell interagieren und sich von diesem z.B. Vorschläge zu Quellcode geben lassen - Sie müssen diese dann aber von Hand aus dem Chatview übernehmen oder mit copy/paste in ihre Suite eintragen. Falls sie unsafe tools erlaubt haben, könnte das Modell so eine Änderung automatisch durchführen.

<gallery widths="200px" perrow="4" heights="160px" >
Datei:ChatViewMCP1.png|Enable/Disable Tools
</gallery>

===== Individuelle Toolrechte =====
Falls tools nicht generell verboten sind ("MCP erlaubt"), können die Rechte gruppenweise und/oder individuell eingestellt werden. Dazu dient das "Tools" Menu des ChatViews:
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ChatViewMCP2.png|Enable/Disable Individual Tools
</gallery>

Das Menu umfasst die Einträge:
* "MCP Tools verwenden"
:die selbe Funktion wie der "MCP" Toolbar Knopf
* "Alle Tools automatisch erlauben"
:unterdrückt die individuelle Erlaubnis Nachfrage; Achtung: der Titel dieser Menufunktion ist aktuell missverständlich (und wird in der nächsten Release geändert); es betrifft die Nachfrage der prinzipiell schon durch die Einstellungen erlaubten tools.
* "Planungsmodus"
:alle tool calls werden automatisch abgelehnt; damit kann man vorab testen, welche Aktionen das Modell durchführen würde
* "Tools Schnellmenu"
:wie im Bild gezeigt: gruppenweise safe/unsafe tools erlauben, gruppenweise Domäne (Expecco / Smalltalk Framework), individuell Rechte einstellen

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>.
Es gibt keinen eXept-seitigen Proxy oder Zwischenspeicher.

Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, dass die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind. Die Verbindung zu den KI-Providern wird aber immer über eine SSL/TLS 1.3 verschlüsselte Verbindung hergestellt (von expecco-Seite aus wird auch Post-Quanten-Kryptographie unterstützt).

Post-Quanten-Kryptographie wirkt allerdings nur, wenn '''beide''' Seiten sie beherrschen. expecco bietet die hybride Gruppe ''X25519MLKEM768'' (X25519 kombiniert mit ML-KEM-768, RFC 9697) an erster Stelle an; ob sie zum Einsatz kommt, entscheidet der Anbieter. Nachgemessen im August 2026 — es handelt sich um tatsächlich beobachtete Handshakes, nicht um Herstellerangaben — handeln diese voreingestellten Anbieter die Gruppe aus:

* '''Anthropic''' (''api.anthropic.com'')
* '''OpenAI''' (''api.openai.com'')
* '''Groq''' und '''Zen''' (''api.groq.com'')
* '''Mistral''' (''api.mistral.ai'')
* '''OpenRouter''' (''openrouter.ai'')

Bei lokal betriebenen Modellen (''ollama'', ''llama.cpp'') stellt sich die Frage nicht: die Verbindung läuft über die Loopback-Schnittstelle und verlässt den Rechner nicht. Bei den Zugängen '''Inhouse''' und '''Tabnine''' hängt es an Ihrem eigenen Server — dort können Sie es selbst prüfen, etwa mit <code>openssl s_client -connect ''host'':443 -groups X25519MLKEM768</code>; scheitert der Handshake, unterstützt der Server die Gruppe nicht.

Der praktische Nutzen liegt beim Angriffsmodell "''harvest now, decrypt later''": aufgezeichneter Verkehr lässt sich auch später, mit einem hinreichend leistungsfähigen Quantenrechner, nicht nachträglich entschlüsseln. Das ist genau dann relevant, wenn Quellcode Ihrer Testsuiten über die Leitung geht. '''Am Grundproblem ändert es nichts''': der Anbieter selbst sieht den Inhalt im Klartext — dagegen hilft nur die Anbieterwahl.

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Chat Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

Zusätzlich gibt es zwei Aktionen, die sich auf die ausgewählte '''Klasse'''
beziehen statt auf eine einzelne Methode ''(verfügbar ab expecco 26.2)''.
Es genügt, die Klasse auszuwählen; eine Methodenauswahl ist dafür nicht nötig:

* '''Explain Class''' — erklärt die Klasse als Ganzes: wofür sie zuständig ist, welche Rolle ihre Instanzvariablen spielen, wie ihre Protokolle zusammenwirken und worauf man beim Verwenden achten muss.
* '''Generate Class Documentation''' — schlägt einen Dokumentationstext für die Klasse vor; '''[Apply]''' trägt diesen in die Dokumentation der Klasse ein.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren nur mit vision-fähigen Modellen (bei OpenAI z.B. gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic, OpenAI etc. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.

* '''Claude Code (subscription)''' ''(verfügbar ab expecco 26.2)'' — dieser Anbieter verwendet nicht die API, sondern das lokal installierte Kommandozeilenprogramm ''Claude Code'' und damit Ihr vorhandenes Claude-Abonnement. Es wird kein API-Schlüssel benötigt, und es fallen keine tokenbasierten API-Kosten an. Die Felder '''API Key''', '''API URL''' und '''Proxy''' werden für diesen Anbieter ausgeblendet, da sie hier keine Bedeutung haben; als Authentifizierung erscheint "Subscription (external login)". Voraussetzung ist, dass ''Claude Code'' installiert ist und einmalig angemeldet wurde — dazu <code>claude</code> in einer Konsole starten und die Anmeldung abschließen. Das Modell kann als Stufen-Alias (''sonnet'', ''opus'', ''haiku'' — jeweils das aktuelle Modell dieser Stufe) oder als fester Modellname angegeben werden.

* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.

* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.

* '''Max output tokens''' — maximale Antwortlänge.

* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).
* Ollama/llama.cpp: kein API Key erforderlich
* Inhouse: fragen Sie ihren Admin

== Coding Assistenten (CLI Programm) ==

Beim Start der MCP-Server-Anbindung trägt expecco die nötigen Konfigurationseinträge automatisch in die Config-Dateien der unterstützten Coding-Assistenten ein. Die folgenden Abschnitte beschreiben Ort und Format der jeweiligen Einträge — zur Information bzw. falls Sie sie manuell ergänzen oder kontrollieren möchten.

=== Claude Code ===
: Anm.: Dieser Abschnitt beschreibt den umgekehrten Weg — ein extern laufendes ''Claude Code'' greift auf expecco zu. Wenn Sie ''Claude Code'' umgekehrt als KI-Anbieter ''innerhalb'' von expecco nutzen möchten, siehe den Anbieter '''Claude Code (subscription)''' im Abschnitt [[#Einstellungen (AI Coding)|Einstellungen]] ''(ab expecco 26.2)''.

Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"mcp": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls typischerweise im Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollte diese aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Dieser Abschnitt ist veraltet; die unten aufgeführten Aufgaben könnnen
nun 1:1 auch so im Chatfenster ausgeführt werden.

Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

=== Erfahrungen und Tipps für die Arbeit ===

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen weg - es sei denn sie dienen der Entscheidung. Tatsächlich erhöhen sie lediglich den Tokenverbrauch.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (ollama) ==

Bitte vorwärts scrollen zu LLaMa.cpp Versuch.

Erste Versuche waren eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation (ollama) ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Zusammenfassung (lokale AI mit kleinen Modellen) ==

Man sollte sich keinen Illusionen hingeben: eine lokale AI mit ein paar Milliarden floats (oder gar 4bit quantized) kann nicht im geringsten mit
einem Modell mit Billionen Werten mithalten (i.e. Claude oder ChatGPT oder einem hauseigenen großen Rechenzentrum mit ein paar 10000 NVidia GPUs).

Hier ein chat mit lokalem llama3.2:3b (3 Milliarden floats, bf16); wichtig anzumerken, dass dieses Modell kein instruct Modell ist, es also nicht trainiert wurde, tool calls zu emittieren; was unten klar wird:
--- user ---
how ´would you open an expecco app using mcp

''ich frage wie er unsere mcp Anbindung aufrufen würde (große Modelle von Anthropic oder OpenAI würden hier korrekt antworten)''

```
MCP.openApp("type://com.expeccotech.app.name", null);
```

Replace `"type://com.expeccotech.app.name"` with the specific type identifier for your app. This might be a URI or a project handle.

This command will open the Expecco app using MCP, and it may prompt you to authenticate or authorize if necessary.

Here's an example of how you could use this method in Python:

```python
import mcpsys

app = mcpsys.MCP()
app.openApp("type://com.expeccotech.app.name", None)
```

In JavaScript, you can also use this method with the following code:

```javascript
var app = new MCP();
app.openApp("type://com.expeccotech.app.name", null);
```

''das ist natürlich völliger Unsinn; man könnte sagen: er saugt sich das aus den Fingern; sagen wir ihm das:''

--- user ---
you just made this all up. you are wrong. do not hallucinate. what mcp tools do you really have at hand

--- assistant ---
I got a bit carried away with my imagination.

To be honest, I don't actually have any MCP (Model Computing Platform) tools or knowledge at hand. I'm an AI trained on general knowledge and can only provide information based on my training data.

MCP is a specific framework developed by the University of Michigan, and it seems that I was not properly informed about its capabilities and tools. If you'd like to correct me or provide more information about MCP, I'll do my best to learn from it!

''aha - er gibt es zu!''

== LLaMa.cpp ==

Installation siehe Webseite von llama.

Kommando:
llama-server.exe -hf unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:Q4_K_M --cts-size XXXX

Hinweise
:hier wird ein instruct Modell geladen; es sollte also tool calls beherrschen.
:per default verwendet llama.cpp nur ein Kontextfenster von 4096 Tokens. Das ist zu wenig für sinnvolle Aufgaben. Starten Sie llama.cpp mit --ctx-size 8192, 16384, 32768 oder 65536. Die unterstützte Größe hängt vom Modell ab. Ein großer Kontext hat natürlich Einfluss auf Speicherbedarf (VRAM in GPU, RAM in CPU) und Antwortzeit. Wenn Sie genug CPU VRAM bzw. RAM haben, ist es in jedem Fall besser, eine größere Kontextsize zu setzen (bedenken Sie, dass die großen Modelle von Anthropic oder ChatGPT Kontexte von 200k oder 1Mio haben).

Das Modell läuft auf der lokalen CPU (Laptop, ohne GPU), und zeigt dabei durchaus gute Antworten (wenn man Geduld hat). Zugegeben, wir haben auch einiges an Wissen in den Speicher vorgepackt.

Im expecco Chat Fenster:
open an exepcco browser on a new project
macht er!
create a python action to compute the area from given radius
er legt eine korrekte Pythonscript Aktion an. Chapeau. Sogar die Behandlung der Ein- und Ausgangspins, die bei Scriptaktionen etwas umständlich ist, hat er gemeistert.

again, as Smalltalk action
braucht etwas, aber er reagiert auf Syntaxfehler, korrigiert sich. Danach führt er die Aktion zur Verifikation aus. Ausgabe: 
''Verified: for `radius = 5.0`, `area = 78.5398163397448` — same result as the Python version.''

Die Frage wie man einen String (z.B. 'helloworld') zerlegt geht er systematisch an - er sucht im laufenden expecco nach Stringfunktionen. Das dauert



== Wahl der Modellgrösse ==

=== Übersetzung ===
Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In keinem Fall sollte man der KI "blind" vertrauen.

=== Arbeit mit Expecco ===
Um das Modell tatsächlich Code oder Aktionen erzeugen zu lassen reichen die
einfachsten Modell NICHT;
Hier eine vorläufige Liste unserer Resultate:

* qwen2.5-coder:3b definitiv zu dumm
* qwen2.5-coder:7b nach einigen Verbesserungen an den initialen Anweisungen zum Gebrauch der expecco tools kann das Model: Browser öffnen, Projekt anlegen. Achtung: benötigt contextSize=8192; mit 4096 ist es zu vergesslich
*
[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

KI Coding Plugin

2026-08-06T08:35:31Z

Sv: Datenschutz: welche voreingestellten Anbieter Post-Quanten-Schluesselaustausch (X25519MLKEM768) tatsaechlich aushandeln

{{Languages|KI Coding Plugin|label=Deutsch}}

= KI Coding Plugin =

Die hier beschriebenen KI-Funktionen sind Teil des Lizenz-Features '''AI Coding'''. Ist dieses Feature in Ihrer Lizenz nicht enthalten, erscheinen die ''Ask AI''-Menüeinträge zwar weiterhin sichtbar in den Editor-Toolbars, sind aber deaktiviert (Tooltip: "''Install the AI coding plugin to enable''").

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic (aka Claude)''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI (i.e. ChatGPT)''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
* '''llama.cpp''' lokal oder remote
* '''Groq''', '''Zen''', '''LLaMa''', '''Tabnine''' etc.
* '''Claude Code (subscription)''' — nutzt Ihr vorhandenes Claude-Abonnement statt eines API-Schlüssels ''(verfügbar ab expecco 26.2)''
* '''Inhouse''' — ihre eigene in-house (in-Firma) KI.

Wichtig: 
Der zusätzliche Eintrag '''Inhouse''' ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern oder einer anderen fimeninternen KI chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Lizenzierung ==

Die KI-Funktionen sind auf '''zwei getrennte Lizenz-Features''' aufgeteilt. Die Trennung verläuft genau entlang der Grenze zwischen ''lesen'' und ''verändern'':

* '''KI Coding''' (im Lizenzfile: ''AI Coding'') — die Grundlizenz. Sie lädt das Plugin überhaupt erst und schaltet Chat-Fenster, Anbieterauswahl und die lesenden (''safe'') Werkzeuge frei.
* '''KI Advanced Coding''' (im Lizenzfile: ''AI Advanced Coding'') — ein eigenes, zusätzlich zu erwerbendes Feature. Es setzt ''KI Coding'' voraus und schaltet die schreibenden (''unsafe'') Werkzeuge frei.

=== KI Coding ===

Ohne dieses Feature ist das Plugin nicht geladen: die ''Ask AI''-Einträge bleiben in den Editor-Toolbars sichtbar, sind aber deaktiviert (Tooltip: "''Install the AI coding plugin to enable''").

Mit ''KI Coding'' können Sie in vollem Umfang mit dem Modell arbeiten, solange es dabei bleibt, Ihr Projekt zu ''lesen'': Elemente suchen, Netzwerke und Quellcode analysieren, Aktivitylogs auswerten, Dokumentation entwerfen, Fehlerursachen erklären lassen. Vorschläge des Modells — etwa neuer Quellcode für eine Elementaraktion — erscheinen im Chat-Fenster und werden von Ihnen bewusst übernommen (''Apply''-Knopf oder copy/paste). Die Entscheidung, ob eine Änderung in die Suite gelangt, liegt in jedem Einzelfall bei Ihnen.

=== KI Advanced Coding ===

Dieses Feature schaltet die Werkzeuge frei, mit denen das Modell Ihr Projekt und Ihre Arbeitsumgebung '''selbst verändern''' kann — im Wesentlichen die im Abschnitt [[#Unsafe Tools|Unsafe Tools]] aufgeführten Funktionen: Elemente anlegen, Netzwerke ändern, Methoden und Klassen definieren, Aktionen und Testfälle ausführen sowie Änderungen in die Versionsverwaltung einchecken.

Fehlt das Feature, stehen diese Werkzeuge '''auch dann nicht zur Verfügung, wenn sie im ChatView ausdrücklich erlaubt wurden'''. Das Modell erhält in diesem Fall eine Fehlermeldung statt der Ausführung; die Sitzung läuft normal weiter.

=== Sicherheitsaspekte ===

Die Lizenz ist die '''äußere''' von zwei voneinander unabhängigen Schutzschichten. Beide müssen eine Aktion erlauben, damit sie ausgeführt wird:

* '''Lizenz-Ebene''' (''KI Advanced Coding'') — organisatorisch, gilt für die gesamte Installation und ist '''vom Anwender nicht umschaltbar'''. Sie hängt an der signierten Lizenzdatei und lässt sich nicht über eine Einstellung, eine Umgebungsvariable oder eine Konfigurationsdatei aktivieren.
* '''Laufzeit-Ebene''' (''MCP''-Knopf, Tools-Menü, Planungsmodus) — situativ, gilt für die einzelne Chat-Sitzung und ist vom Anwender jederzeit umschaltbar. Siehe [[#Individuelle Toolrechte|Individuelle Toolrechte]].

Daraus ergeben sich die praktisch wichtigen Eigenschaften:

* '''Eine Organisation kann verbindlich festlegen, dass die KI grundsätzlich nur lesend arbeitet.''' Wird ''KI Advanced Coding'' nicht lizenziert, bleibt es dabei — unabhängig davon, was einzelne Anwender in ihrem ChatView einstellen, und unabhängig davon, ob jemand versehentlich "Alle Tools automatisch erlauben" aktiviert.
* '''Grundsatz der geringsten Rechte.''' Der Auslieferungszustand ist lesend; Schreibrechte müssen bewusst erworben werden und sind damit auch eine dokumentierte Entscheidung, kein Nebeneffekt einer Voreinstellung.
* '''Die Prüfung gilt auch für den Zugriff von außen.''' Greift ein externes CLI-Programm (''claude code'', ''cursor'', ''zed'', ''tabnine'') über das MCP-Protokoll auf expecco zu, unterliegen die schreibenden Werkzeuge derselben Prüfung. Ein externes Programm kann sie nicht umgehen — es erhält dieselbe Fehlermeldung wie das Modell im internen Chat.
* '''Der Prüfpunkt liegt bei der Ausführung, nicht in der Oberfläche.''' Die Werkzeuge werden nicht lediglich im Menü ausgeblendet; der Aufruf selbst wird abgewiesen. Ein ausgeblendeter Menüeintrag wäre keine Sicherheitsmaßnahme.

Ebenso wichtig ist, was die Lizenz '''nicht''' leistet:

* Sie begrenzt, '''was die KI in expecco tun darf''' — nicht, '''welche Daten das Haus verlassen'''. Welcher Anbieter Ihren Quellcode zu sehen bekommt, entscheidet allein die Anbieterwahl; siehe [[#Datenschutz / Datenfluss|Datenschutz / Datenfluss]]. Auch mit reinem ''KI Coding'' wird beim Einsatz eines Cloud-Anbieters Projektinhalt übertragen.
* Sie ersetzt nicht die Prüfung dessen, was das Modell vorschlägt. Auch eine lizenzierte Änderung ist eine Änderung eines Modells und gehört wie jeder fremde Beitrag reviewt.
* Sie schützt nicht vor einem kompromittierten CLI-Programm auf demselben Rechner. Für sicherheitskritische Umgebungen gelten weiterhin die Hinweise im Abschnitt [[#Tool Use|Tool Use]] zur Isolation solcher Rechner.

Für eine sicherheitskritische Umgebung ergibt sich daraus die restriktivste sinnvolle Konfiguration: ''KI Coding'' ohne ''KI Advanced Coding'', kombiniert mit einem lokal betriebenen Modell (''ollama'' oder ''llama.cpp''). Dann verlässt kein Projektinhalt Ihr Netz, und die KI kann ausschließlich lesen und vorschlagen.

== Architektur und Sicherheit ==

Mit "''Sicherheit''" ist hier gemeint: "''können die Daten den Rechner oder ihre Abteilung/Firma verlassen'' bzw. ''kann die KI Schaden anrichten indem sie auf Ihrem Rechner unkontrolliert Code ausführt oder Daten manipuliert''".

Anmerkung: Wenn hohe Sicherheit gefordert ist (sensible Daten, Algorithmen, Workflows) muss Ihr Netzadmin durch geeignete Maßnahmen (Firewall, Router/Switch Konfiguration etc.) verhindern, dass Zugriffe sowohl ausgehend als auch eingehend zu/von außerhalb ihrer Domäne möglich sind.
Das "unsichtbar machen" entsprechender Einstellungsdialoge in expecco wäre hierzu nicht dienlich, da bei offenen Ports unzählige andere Möglichkeiten bestehen (curl, webbrowser, low-level Socket API etc.).

Zur Sicherheit ihrer eigenen Testsuite und möglichen Aktionen der KI lesen Sie bitte die unten aufgeführten Abschnitte zu [[#tool_use|"Tool Use"]].

=== Architektur ===

Im folgenden werden die Einstellungen und die zugehörigen Datenflüsse/kanäle beschrieben.

Mögliche Setups sind:

==== KI Firmenintern ====
* direkte Verbindung zu einer KI auf einem Rechner in ihrem lokalen Netzwerk, Firmennetz oder einem definiert sicheren Firmenanbieter. Sicherheit: '''Hoch''' (weder Daten noch Chat-Text gehen aus dem Haus)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:InhouseSetup1.png|Einstellung
Datei:ArchInhouseSetup1.png|Architektur
</gallery>
:expecco kommuniziert ausschließlich und direkt zu dieser URL; keine Applikation dazwischen. Insbesondere kein "<code>claude.exe</code>" oder ein anderes Command Line Interface (CLI) Programm. Ihre Eingaben im expecco Chat Fenster gehen direkt (verpackt als JSON) an die konfigurierte Adresse und deren Antwort erscheint (entpackt aus JSON) im expecco Chat Fenster. Nachrichten werden ausschließlich mit dem von Ihnen konfigurierten Host ausgetauscht.

::- wählen Sie dazu "inhouse" und geben hostname+port+URL zu diesem host ein; typischerweise haben diese die Form "<code>firmenAI:11434/v1/chat/completions</code>" oder auch 80 oder 8080 als port. Fragen Sie ihren Netzwerkadmin im Zweifel, auch ob ein API Key (= Zugangsschlüssel) erforderlich ist.

==== KI auf Ihrem eigenen Rechner ====

* direkte Verbindung zu einer lokalen KI auf ihrem eignen persönlichen Rechner Sicherheit: '''Sehr Hoch''' (weder Daten noch Chat verlassen ihren Rechner)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:LocalSetup2.png|Einstellung
Datei:ArchLocalSetup2.png|Architektur
</gallery>
:auch hier kommuniziert expecco ausschließlich und direkt zu diesem ihrem lokalen Rechner, auf der Sie selbst ein Modell installiert und am Laufen haben (ollama oder llama.cpp). Ob dies im einzelnen sinnvoll ist hängt von der Leistungsfähigkeit ihres eigenen Rechners ab (empfohlen wird eine oder mehrere leistungsfähige GPUs mit viel VRAM (>=32Gb), großer RAM Speicherausbau (>=64Gb) und ein leistungsfähiges Modell (mindestens 30B, besser 120B mit großem Kontext,da reichen aber 32GB VRAM nicht); eigene Erfahrungen haben wir unten in diesem Dokument zusammengetragen).
::- wählen Sie dazu "ollama" oder "llama.cpp" und geben als hostname "localhost" ein. Falls sie einen dedizierten Rechner in der Abteilung haben, kann natürlich auch dessen Hostname eingegeben werden.

==== KI von einem Cloudanbieter ====
* direkte Verbindung zu einem externen Anbieter (wie Anthropic, OpenAI etc.). Sicherheit: '''Fragwürdig''' (Sie müssen dem Anbieter und IP Verbindung vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup4.png|Einstellung
Datei:ArchExternalSetup3.png|Architektur
</gallery>
:Die Interaktion erfolgt lediglich mit der von Ihnen eingestellten URL über das expecco-interne chat Fenster. In sicherheitskritischem Umfeld ist jedoch davon abzuraten und ihre Netzadministrator wird diesen Zugang vermutlich auch nicht zulassen da (je nach URL) ihre Daten und ihr Chatverlauf an externe Rechner gehen, oder von fremden Geheimdiensten mitgelesen werden könnten). Prinzipiell sollte dies dem Netzadmin aber bekannt sein, und auf Netzwerkebene gesperrt sein, da ein solcher Zugriff auch anderen Programmen verwehrt werden muss (curl, Webbrowser etc.). Insofern ist ratsam, solche Verbindungen auf administrativer Ebene (Firewall, Router/Switch Konfiguration etc.) zu verhindern. Natürlich gilt diees nicht, falls sie eine eigenen firmeninterne cloud Infrastruktur besitzen, die vertrauenswürdig ist.
::- wählen Sie dazu "Anthropic, OpenAI, ..." und geben hostname+port+URL zu diesem host ein (wobei die Vorgabe im Eingabefeld typischerweise schon passt); typischerweise brauchen die Anbieter einen Zugangsschlüssel (sog. API key), den Sie bei der Registrierung vom Anbieter oder von ihrem Netzadmin erhalten. Achtung: verschiedene Anbieter (u.a. Anthropic) erlauben hier nur die Abrechnung über Ihr Token Budget, nicht über einen Pro/Max oder Enterprise plan. Es kann also hier zu erhöhten Kosten führen. Es ist uns weder technisch noch juristisch möglich, dies zu verhindern.

==== KI über CLI (eg. claude code); Bedienung über CLI ====
* indirekte Verbindung via CLI (z.B. ClaudeCode, Kiro, Tabnine, OpenCode, LMStudio etc.). Sicherheit: '''Unsicher''' (Sie müssen sowohl Anbieter und dem Modell vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup4.png|Einstellung
Datei:ArchExternalSetup1.png|Architektur
</gallery>
:Hier baut ein CLI Programm (z.B. "claude.exe") die Verbindung zum KI Modell auf (was natürlich seinerseits wiederum eine lokale in-house KI sein könnte). Dieses CLI Programm verbindet sich dann mit expecco und hat dort beschränkten Zugriff auf ihre Testsuite (über mcp). Die Interaktion erfolgt mit dem CLI Programm, die Bedienung des Modells erfolgt im CLI Programm. Das CLI hat kontrollieren Zugriff auf expecco über das sog. MCP Protokoll. Es ist zu beachten, dass die Konfiguration dem CLI Zugriff auf Dateien ermöglicht und es auch andere Aktionen auf Ihrem Rechner ausführen kann (shell/batch/powershell, Dateizugriffe etc.). Das Modell kann über das CLI Programm auch auf Ressourcen außerhalb expecco zugreifen. Und es könnte das System bzw. ihr Netz geziehlt ausspionieren oder manipulieren ohne daß expecco dies bemerkt oder verhindert. Sie müssen also sowohl dem Anbieter, der IP Verbindung als auch dem CLI Programm vertrauen.
::- sie müssen dem lokalen CLI Programm den Zugriff auf expecco erlauben. gehen Sie dazu in das "''Extras''" → "''Web-Dienste''" → "''MCP Zugriff erlauben (AI Coding)''". Die Konfiguration zum eigentlichen Modell erfolgt im CLI Programm Ihrer Wahl und ist nicht unter der Kontrolle von expecco; expecco erlaubt damit lediglich die Kontrolle von außerhalb über das MCP Protokoll. Eine Einstellung des Anbieters ist nicht notwendig; sie wird nicht benutzt, können daher beliebige Angaben machen.

==== KI über transparente CLI (nur claude code); Bedienung über ChatView ====
* indirekte Verbindung via unsichtbarer ClaudeCode CLI.
Sicherheit: '''Unsicher''' (Anbieter und Modell vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup5.png|Einstellung
Datei:ArchExternalCLIStdioSetup5.png|Architektur
</gallery>
:Auch hier erfolgt die Verbindung über das ClaudeCode CLI Programm, welches jedoch ohne Benutzeroberfläche den Verkehr lediglich weiter leitet (via stdin/stdout). Die Benutzerinteraktion erfolgt über das expecco-interne chat Fenster, der tatsächliche Modellzugriff vom CLI. Auch hier muss die Konfiguration des Modellzugriffs im CLI Programm erfolgen. Auch hier ist nicht technisch ausgeschlossen, daß das CLI Programm auf Daten außerhalb expecco zugreift. Falls das vom CLI technisch ermöglicht wird, könnte das Modell solche Zugriffe auslösen. Auch hier muß Modell, Verbindung und CLI Programm vertraut werden.

=== Tool Use ===

Der eigentlichen Mehrwert der KI besteht in der Möglichkeit dem Modell Zugriff auf das im expecco gezeigte Testprojekt zu gestatten. Es kann die Elemente des Baums lesen, Netzwerke analysieren und Ergebnisse (AktivityLogs) lesen.

Dazu sendet das Modell sog. "Tool Calls" zurück, die vom Empfänger im JSON Datenstrom erkannt und ausgeführt werden. Diese werden im folgenden "Tool Calls" genannt.

Ist ein CLI Programm (claude.exe, openCode.exe etc.) der Partner des Modells, erfolgt diese Erkennung dort, und die tools werden anhand des Toolnamens entweder im CLI selbst ausgeführt (Dateien lesen der schreiben, shell/batch scripts ausführen, etc.) oder über das sog. MCP Protokoll an Drittprogramme weiter geleitet.
In unserem Fall stellt expecco die unten beschriebenen MCP tools bereit. Neben diesen könnten aber auch andere Aktionen (geheim oder offen) vom CLI ausgeführt werden. Und sie können dem CLI auch andere MCP Zugänge zu anderen Programmen bereitstellen. Sie müssen in diesem Fall also unbedingt dem CLI Programm und dem Modell und der IP Verbindung zur Außenwelt vertrauen. Sollten sie im sicherheitskritischen Umfeld solch ein Setup wählen ist unbedingt geraten, diesen Rechner vom Rest ihres Netzwerks zu isolieren, keine sensiblen Daten auf diesem Rechner zu halten, und den Verkehr zur Außenwelt über einen separaten Kanal abzuwickeln.

Ist kein CLI Programm involviert (i.e. die Verbindung geht von expecco direkt zum Modell) erfolgt die Erkennung von tool calls innerhalb expecco, und es ist dem Modell nicht möglich, andere Aktionen als die unten aufgeführten Funktionen aufzurufen. Sie haben also volle Kontrolle darüber.

==== Tool Funktionen von expecco ====

Diese Funktionen dienen dazu, dem Modell lesend und/oder schreibend auf ihre Testsuite (das im Browser dargestellte Projekt) zuzugreifen. Wie bereits beschrieben sind dies auch Funktionen die über MCP einem CLI Programm zur Verfügung gestellt werden, falls ein CLI Programm involviert ist.

Die expecco tool Funktionen wurden von uns eingeteilt in sog. "Safe" und "Unsafe" tools. Als sicher gelten rein lesende, als unsafe solche welche ihre Suite manipulieren oder Aktionen ausführen können.

Sie können in den expecco Einstellungen festlegen, ob tools generell verboten werden, nur safe tools erlaubt werden, oder auch für jedes individuelle tool eine Erlaubnis gegeben wird. Außerdem können Sie bestimmen ob bei jedem individuellen call eine Nachfrage um Erlaubnis erfolgen soll.

===== Safe Tools =====
* Suche von Elementen im Projekt
* Lesen der Schritte, Verbindungen, Pins, etc. in einem Netzwerk
* Lesen des Quellcodes einer Elementaraktion
* Lesen des Aktivitylogs nach einer Ausführung
* Suchen und Lesen von Hilfsfunktionen im unterliegenden Framework (eg. Smalltalk Basisklassen)

===== Unsafe Tools =====
* Anlegen neuer Elemente
* Änderungen in einem Netzwerk (Schritten, Verbindungen etc.)
* Ausführen einer Aktion, eines Testfalls oder Testplans

==== Im ChatView ====

===== Tool Calls Generell verbieten/erlauben =====

Der "mcp" Button im Chatview bestimmt ob tool calls prinzipiell erlaubt oder verboten werden. Fall generell erlaubt werden die unten beschriebenen Einzeleinstellungen wirksam; falls generell verboten sind diese irrelevant. 
Ohne tool calls können Sie immer noch mit dem Modell interagieren und sich von diesem z.B. Vorschläge zu Quellcode geben lassen - Sie müssen diese dann aber von Hand aus dem Chatview übernehmen oder mit copy/paste in ihre Suite eintragen. Falls sie unsafe tools erlaubt haben, könnte das Modell so eine Änderung automatisch durchführen.

<gallery widths="200px" perrow="4" heights="160px" >
Datei:ChatViewMCP1.png|Enable/Disable Tools
</gallery>

===== Individuelle Toolrechte =====
Falls tools nicht generell verboten sind ("MCP erlaubt"), können die Rechte gruppenweise und/oder individuell eingestellt werden. Dazu dient das "Tools" Menu des ChatViews:
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ChatViewMCP2.png|Enable/Disable Individual Tools
</gallery>

Das Menu umfasst die Einträge:
* "MCP Tools verwenden"
:die selbe Funktionwie der "MCP" Toolbar Knopf
* "Alle Tools automatisch erlauben"
:unterdrückt die individuelle Erlaubnis Nachfrage; achtung: der Titel dieser Menufunktion ist aktuell mißverständlich (und wird in der nächsten Release geändert); es betrifft die Nachfrage der prinzipiell schon durch die Einstellungen erlaubten tools.
* "Planungsmodus"
:alle tool calls werden automatisch abgelehnt; damit kann man vorab testen, welche Aktionen das Modell durchführen würde
* "Tools Schnellmenu"
:wie im Bild gezeigt: gruppenweise safe/unsafe tools erlauben, gruppenweise Domäne (Expecco / Smalltalk Framework), individuell Rechte einstellen

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>.
Es gibt keinen eXept-seitigen Proxy oder Zwischenspeicher.

Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, dass die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind. Die Verbindung zu den KI-Providern wird aber immer über eine SSL/TLS 1.3 verschlüsselte Verbindung hergestellt (von expecco-Seite aus wird auch Post-Quanten-Kryptographie unterstützt).

Post-Quanten-Kryptographie wirkt allerdings nur, wenn '''beide''' Seiten sie beherrschen. expecco bietet die hybride Gruppe ''X25519MLKEM768'' (X25519 kombiniert mit ML-KEM-768, RFC 9697) an erster Stelle an; ob sie zum Einsatz kommt, entscheidet der Anbieter. Nachgemessen im August 2026 — es handelt sich um tatsächlich beobachtete Handshakes, nicht um Herstellerangaben — handeln diese voreingestellten Anbieter die Gruppe aus:

* '''Anthropic''' (''api.anthropic.com'')
* '''OpenAI''' (''api.openai.com'')
* '''Groq''' und '''Zen''' (''api.groq.com'')
* '''Mistral''' (''api.mistral.ai'')
* '''OpenRouter''' (''openrouter.ai'')

Bei lokal betriebenen Modellen (''ollama'', ''llama.cpp'') stellt sich die Frage nicht: die Verbindung läuft über die Loopback-Schnittstelle und verlässt den Rechner nicht. Bei den Zugängen '''Inhouse''' und '''Tabnine''' hängt es an Ihrem eigenen Server — dort können Sie es selbst prüfen, etwa mit <code>openssl s_client -connect ''host'':443 -groups X25519MLKEM768</code>; scheitert der Handshake, unterstützt der Server die Gruppe nicht.

Der praktische Nutzen liegt beim Angriffsmodell "''harvest now, decrypt later''": aufgezeichneter Verkehr lässt sich auch später, mit einem hinreichend leistungsfähigen Quantenrechner, nicht nachträglich entschlüsseln. Das ist genau dann relevant, wenn Quellcode Ihrer Testsuiten über die Leitung geht. '''Am Grundproblem ändert es nichts''': der Anbieter selbst sieht den Inhalt im Klartext — dagegen hilft nur die Anbieterwahl.

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Chat Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

Zusätzlich gibt es zwei Aktionen, die sich auf die ausgewählte '''Klasse'''
beziehen statt auf eine einzelne Methode ''(verfügbar ab expecco 26.2)''.
Es genügt, die Klasse auszuwählen; eine Methodenauswahl ist dafür nicht nötig:

* '''Explain Class''' — erklärt die Klasse als Ganzes: wofür sie zuständig ist, welche Rolle ihre Instanzvariablen spielen, wie ihre Protokolle zusammenwirken und worauf man beim Verwenden achten muss.
* '''Generate Class Documentation''' — schlägt einen Dokumentationstext für die Klasse vor; '''[Apply]''' trägt diesen in die Dokumentation der Klasse ein.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren nur mit vision-fähigen Modellen (bei OpenAI z.B. gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic, OpenAI etc. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.

* '''Claude Code (subscription)''' ''(verfügbar ab expecco 26.2)'' — dieser Anbieter verwendet nicht die API, sondern das lokal installierte Kommandozeilenprogramm ''Claude Code'' und damit Ihr vorhandenes Claude-Abonnement. Es wird kein API-Schlüssel benötigt, und es fallen keine tokenbasierten API-Kosten an. Die Felder '''API Key''', '''API URL''' und '''Proxy''' werden für diesen Anbieter ausgeblendet, da sie hier keine Bedeutung haben; als Authentifizierung erscheint "Subscription (external login)". Voraussetzung ist, dass ''Claude Code'' installiert ist und einmalig angemeldet wurde — dazu <code>claude</code> in einer Konsole starten und die Anmeldung abschließen. Das Modell kann als Stufen-Alias (''sonnet'', ''opus'', ''haiku'' — jeweils das aktuelle Modell dieser Stufe) oder als fester Modellname angegeben werden.

* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.

* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.

* '''Max output tokens''' — maximale Antwortlänge.

* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).
* Ollama/llama.cpp: kein API Key erforderlich
* Inhouse: fragen Sie ihren Admin

== Coding Assistenten (CLI Programm) ==

Beim Start der MCP-Server-Anbindung trägt expecco die nötigen Konfigurationseinträge automatisch in die Config-Dateien der unterstützten Coding-Assistenten ein. Die folgenden Abschnitte beschreiben Ort und Format der jeweiligen Einträge — zur Information bzw. falls Sie sie manuell ergänzen oder kontrollieren möchten.

=== Claude Code ===
: Anm.: Dieser Abschnitt beschreibt den umgekehrten Weg — ein extern laufendes ''Claude Code'' greift auf expecco zu. Wenn Sie ''Claude Code'' umgekehrt als KI-Anbieter ''innerhalb'' von expecco nutzen möchten, siehe den Anbieter '''Claude Code (subscription)''' im Abschnitt [[#Einstellungen (AI Coding)|Einstellungen]] ''(ab expecco 26.2)''.

Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"mcp": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls typischerweise im Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollte diese aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Dieser Abschnitt ist veraltet; die unten aufgeführten Aufgaben könnnen
nun 1:1 auch so im Chatfenster ausgeführt werden.

Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

=== Erfahrungen und Tipps für die Arbeit ===

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen weg - es sei denn sie dienen der Entscheidung. Tatsächlich erhöhen sie lediglich den Tokenverbrauch.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (ollama) ==

Bitte vorwärts scrollen zu LLaMa.cpp Versuch.

Erste Versuche waren eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation (ollama) ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Zusammenfassung (lokale AI mit kleinen Modellen) ==

Man sollte sich keinen Illusionen hingeben: eine lokale AI mit ein paar Milliarden floats (oder gar 4bit quantized) kann nicht im geringsten mit
einem Modell mit Billionen Werten mithalten (i.e. Claude oder ChatGPT oder einem hauseigenen großen Rechenzentrum mit ein paar 10000 NVidia GPUs).

Hier ein chat mit lokalem llama3.2:3b (3 Milliarden floats, bf16); wichtig anzumerken, dass dieses Modell kein instruct Modell ist, es also nicht trainiert wurde, tool calls zu emittieren; was unten klar wird:
--- user ---
how ´would you open an expecco app using mcp

''ich frage wie er unsere mcp Anbindung aufrufen würde (große Modelle von Anthropic oder OpenAI würden hier korrekt antworten)''

```
MCP.openApp("type://com.expeccotech.app.name", null);
```

Replace `"type://com.expeccotech.app.name"` with the specific type identifier for your app. This might be a URI or a project handle.

This command will open the Expecco app using MCP, and it may prompt you to authenticate or authorize if necessary.

Here's an example of how you could use this method in Python:

```python
import mcpsys

app = mcpsys.MCP()
app.openApp("type://com.expeccotech.app.name", None)
```

In JavaScript, you can also use this method with the following code:

```javascript
var app = new MCP();
app.openApp("type://com.expeccotech.app.name", null);
```

''das ist natürlich völliger Unsinn; man könnte sagen: er saugt sich das aus den Fingern; sagen wir ihm das:''

--- user ---
you just made this all up. you are wrong. do not hallucinate. what mcp tools do you really have at hand

--- assistant ---
I got a bit carried away with my imagination.

To be honest, I don't actually have any MCP (Model Computing Platform) tools or knowledge at hand. I'm an AI trained on general knowledge and can only provide information based on my training data.

MCP is a specific framework developed by the University of Michigan, and it seems that I was not properly informed about its capabilities and tools. If you'd like to correct me or provide more information about MCP, I'll do my best to learn from it!

''aha - er gibt es zu!''

== LLaMa.cpp ==

Installation siehe Webseite von llama.

Kommando:
llama-server.exe -hf unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:Q4_K_M --cts-size XXXX

Hinweise
:hier wird ein instruct Modell geladen; es sollte also tool calls beherrschen.
:per default verwendet llama.cpp nur ein Kontextfenster von 4096 Tokens. Das ist zu wenig für sinnvolle Aufgaben. Starten Sie llama.cpp mit --ctx-size 8192, 16384, 32768 oder 65536. Die unterstützte Größe hängt vom Modell ab. Ein großer Kontext hat natürlich Einfluss auf Speicherbedarf (VRAM in GPU, RAM in CPU) und Antwortzeit. Wenn Sie genug CPU VRAM bzw. RAM haben, ist es in jedem Fall besser, eine größere Kontextsize zu setzen (bedenken Sie, dass die großen Modelle von Anthropic oder ChatGPT Kontexte von 200k oder 1Mio haben).

Das Modell läuft auf der lokalen CPU (Laptop, ohne GPU), und zeigt dabei durchaus gute Antworten (wenn man Geduld hat). Zugegeben, wir haben auch einiges an Wissen in den Speicher vorgepackt.

Im expecco Chat Fenster:
open an exepcco browser on a new project
macht er!
create a python action to compute the area from given radius
er legt eine korrekte Pythonscript Aktion an. Chapeau. Sogar die Behandlung der Ein- und Ausgangspins, die bei Scriptaktionen etwas umständlich ist, hat er gemeistert.

again, as Smalltalk action
braucht etwas, aber er reagiert auf Syntaxfehler, korrigiert sich. Danach führt er die Aktion zur Verifikation aus. Ausgabe: 
''Verified: for `radius = 5.0`, `area = 78.5398163397448` — same result as the Python version.''

Die Frage wie man einen String (z.B. 'helloworld') zerlegt geht er systematisch an - er sucht im laufenden expecco nach Stringfunktionen. Das dauert



== Wahl der Modellgrösse ==

=== Übersetzung ===
Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In keinem Fall sollte man der KI "blind" vertrauen.

=== Arbeit mit Expecco ===
Um das Modell tatsächlich Code oder Aktionen erzeugen zu lassen reichen die
einfachsten Modell NICHT;
Hier eine vorläufige Liste unserer Resultate:

* qwen2.5-coder:3b definitiv zu dumm
* qwen2.5-coder:7b nach einigen Verbesserungen an den initialen Anweisungen zum Gebrauch der expecco tools kann das Model: Browser öffnen, Projekt anlegen. Achtung: benötigt contextSize=8192; mit 4096 ist es zu vergesslich
*
[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

KI Coding Plugin

2026-08-06T08:28:06Z

Sv: /* Datenschutz / Datenfluss */

{{Languages|KI Coding Plugin|label=Deutsch}}

= KI Coding Plugin =

Die hier beschriebenen KI-Funktionen sind Teil des Lizenz-Features '''AI Coding'''. Ist dieses Feature in Ihrer Lizenz nicht enthalten, erscheinen die ''Ask AI''-Menüeinträge zwar weiterhin sichtbar in den Editor-Toolbars, sind aber deaktiviert (Tooltip: "''Install the AI coding plugin to enable''").

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic (aka Claude)''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI (i.e. ChatGPT)''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
* '''llama.cpp''' lokal oder remote
* '''Groq''', '''Zen''', '''LLaMa''', '''Tabnine''' etc.
* '''Claude Code (subscription)''' — nutzt Ihr vorhandenes Claude-Abonnement statt eines API-Schlüssels ''(verfügbar ab expecco 26.2)''
* '''Inhouse''' — ihre eigene in-house (in-Firma) KI.

Wichtig: 
Der zusätzliche Eintrag '''Inhouse''' ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern oder einer anderen fimeninternen KI chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Lizenzierung ==

Die KI-Funktionen sind auf '''zwei getrennte Lizenz-Features''' aufgeteilt. Die Trennung verläuft genau entlang der Grenze zwischen ''lesen'' und ''verändern'':

* '''KI Coding''' (im Lizenzfile: ''AI Coding'') — die Grundlizenz. Sie lädt das Plugin überhaupt erst und schaltet Chat-Fenster, Anbieterauswahl und die lesenden (''safe'') Werkzeuge frei.
* '''KI Advanced Coding''' (im Lizenzfile: ''AI Advanced Coding'') — ein eigenes, zusätzlich zu erwerbendes Feature. Es setzt ''KI Coding'' voraus und schaltet die schreibenden (''unsafe'') Werkzeuge frei.

=== KI Coding ===

Ohne dieses Feature ist das Plugin nicht geladen: die ''Ask AI''-Einträge bleiben in den Editor-Toolbars sichtbar, sind aber deaktiviert (Tooltip: "''Install the AI coding plugin to enable''").

Mit ''KI Coding'' können Sie in vollem Umfang mit dem Modell arbeiten, solange es dabei bleibt, Ihr Projekt zu ''lesen'': Elemente suchen, Netzwerke und Quellcode analysieren, Aktivitylogs auswerten, Dokumentation entwerfen, Fehlerursachen erklären lassen. Vorschläge des Modells — etwa neuer Quellcode für eine Elementaraktion — erscheinen im Chat-Fenster und werden von Ihnen bewusst übernommen (''Apply''-Knopf oder copy/paste). Die Entscheidung, ob eine Änderung in die Suite gelangt, liegt in jedem Einzelfall bei Ihnen.

=== KI Advanced Coding ===

Dieses Feature schaltet die Werkzeuge frei, mit denen das Modell Ihr Projekt und Ihre Arbeitsumgebung '''selbst verändern''' kann — im Wesentlichen die im Abschnitt [[#Unsafe Tools|Unsafe Tools]] aufgeführten Funktionen: Elemente anlegen, Netzwerke ändern, Methoden und Klassen definieren, Aktionen und Testfälle ausführen sowie Änderungen in die Versionsverwaltung einchecken.

Fehlt das Feature, stehen diese Werkzeuge '''auch dann nicht zur Verfügung, wenn sie im ChatView ausdrücklich erlaubt wurden'''. Das Modell erhält in diesem Fall eine Fehlermeldung statt der Ausführung; die Sitzung läuft normal weiter.

=== Sicherheitsaspekte ===

Die Lizenz ist die '''äußere''' von zwei voneinander unabhängigen Schutzschichten. Beide müssen eine Aktion erlauben, damit sie ausgeführt wird:

* '''Lizenz-Ebene''' (''KI Advanced Coding'') — organisatorisch, gilt für die gesamte Installation und ist '''vom Anwender nicht umschaltbar'''. Sie hängt an der signierten Lizenzdatei und lässt sich nicht über eine Einstellung, eine Umgebungsvariable oder eine Konfigurationsdatei aktivieren.
* '''Laufzeit-Ebene''' (''MCP''-Knopf, Tools-Menü, Planungsmodus) — situativ, gilt für die einzelne Chat-Sitzung und ist vom Anwender jederzeit umschaltbar. Siehe [[#Individuelle Toolrechte|Individuelle Toolrechte]].

Daraus ergeben sich die praktisch wichtigen Eigenschaften:

* '''Eine Organisation kann verbindlich festlegen, dass die KI grundsätzlich nur lesend arbeitet.''' Wird ''KI Advanced Coding'' nicht lizenziert, bleibt es dabei — unabhängig davon, was einzelne Anwender in ihrem ChatView einstellen, und unabhängig davon, ob jemand versehentlich "Alle Tools automatisch erlauben" aktiviert.
* '''Grundsatz der geringsten Rechte.''' Der Auslieferungszustand ist lesend; Schreibrechte müssen bewusst erworben werden und sind damit auch eine dokumentierte Entscheidung, kein Nebeneffekt einer Voreinstellung.
* '''Die Prüfung gilt auch für den Zugriff von außen.''' Greift ein externes CLI-Programm (''claude code'', ''cursor'', ''zed'', ''tabnine'') über das MCP-Protokoll auf expecco zu, unterliegen die schreibenden Werkzeuge derselben Prüfung. Ein externes Programm kann sie nicht umgehen — es erhält dieselbe Fehlermeldung wie das Modell im internen Chat.
* '''Der Prüfpunkt liegt bei der Ausführung, nicht in der Oberfläche.''' Die Werkzeuge werden nicht lediglich im Menü ausgeblendet; der Aufruf selbst wird abgewiesen. Ein ausgeblendeter Menüeintrag wäre keine Sicherheitsmaßnahme.

Ebenso wichtig ist, was die Lizenz '''nicht''' leistet:

* Sie begrenzt, '''was die KI in expecco tun darf''' — nicht, '''welche Daten das Haus verlassen'''. Welcher Anbieter Ihren Quellcode zu sehen bekommt, entscheidet allein die Anbieterwahl; siehe [[#Datenschutz / Datenfluss|Datenschutz / Datenfluss]]. Auch mit reinem ''KI Coding'' wird beim Einsatz eines Cloud-Anbieters Projektinhalt übertragen.
* Sie ersetzt nicht die Prüfung dessen, was das Modell vorschlägt. Auch eine lizenzierte Änderung ist eine Änderung eines Modells und gehört wie jeder fremde Beitrag reviewt.
* Sie schützt nicht vor einem kompromittierten CLI-Programm auf demselben Rechner. Für sicherheitskritische Umgebungen gelten weiterhin die Hinweise im Abschnitt [[#Tool Use|Tool Use]] zur Isolation solcher Rechner.

Für eine sicherheitskritische Umgebung ergibt sich daraus die restriktivste sinnvolle Konfiguration: ''KI Coding'' ohne ''KI Advanced Coding'', kombiniert mit einem lokal betriebenen Modell (''ollama'' oder ''llama.cpp''). Dann verlässt kein Projektinhalt Ihr Netz, und die KI kann ausschließlich lesen und vorschlagen.

== Architektur und Sicherheit ==

Mit "''Sicherheit''" ist hier gemeint: "''können die Daten den Rechner oder ihre Abteilung/Firma verlassen'' bzw. ''kann die KI Schaden anrichten indem sie auf Ihrem Rechner unkontrolliert Code ausführt oder Daten manipuliert''".

Anmerkung: Wenn hohe Sicherheit gefordert ist (sensible Daten, Algorithmen, Workflows) muss Ihr Netzadmin durch geeignete Maßnahmen (Firewall, Router/Switch Konfiguration etc.) verhindern, dass Zugriffe sowohl ausgehend als auch eingehend zu/von außerhalb ihrer Domäne möglich sind.
Das "unsichtbar machen" entsprechender Einstellungsdialoge in expecco wäre hierzu nicht dienlich, da bei offenen Ports unzählige andere Möglichkeiten bestehen (curl, webbrowser, low-level Socket API etc.).

Zur Sicherheit ihrer eigenen Testsuite und möglichen Aktionen der KI lesen Sie bitte die unten aufgeführten Abschnitte zu [[#tool_use|"Tool Use"]].

=== Architektur ===

Im folgenden werden die Einstellungen und die zugehörigen Datenflüsse/kanäle beschrieben.

Mögliche Setups sind:

==== KI Firmenintern ====
* direkte Verbindung zu einer KI auf einem Rechner in ihrem lokalen Netzwerk, Firmennetz oder einem definiert sicheren Firmenanbieter. Sicherheit: '''Hoch''' (weder Daten noch Chat-Text gehen aus dem Haus)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:InhouseSetup1.png|Einstellung
Datei:ArchInhouseSetup1.png|Architektur
</gallery>
:expecco kommuniziert ausschließlich und direkt zu dieser URL; keine Applikation dazwischen. Insbesondere kein "<code>claude.exe</code>" oder ein anderes Command Line Interface (CLI) Programm. Ihre Eingaben im expecco Chat Fenster gehen direkt (verpackt als JSON) an die konfigurierte Adresse und deren Antwort erscheint (entpackt aus JSON) im expecco Chat Fenster. Nachrichten werden ausschließlich mit dem von Ihnen konfigurierten Host ausgetauscht.

::- wählen Sie dazu "inhouse" und geben hostname+port+URL zu diesem host ein; typischerweise haben diese die Form "<code>firmenAI:11434/v1/chat/completions</code>" oder auch 80 oder 8080 als port. Fragen Sie ihren Netzwerkadmin im Zweifel, auch ob ein API Key (= Zugangsschlüssel) erforderlich ist.

==== KI auf Ihrem eigenen Rechner ====

* direkte Verbindung zu einer lokalen KI auf ihrem eignen persönlichen Rechner Sicherheit: '''Sehr Hoch''' (weder Daten noch Chat verlassen ihren Rechner)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:LocalSetup2.png|Einstellung
Datei:ArchLocalSetup2.png|Architektur
</gallery>
:auch hier kommuniziert expecco ausschließlich und direkt zu diesem ihrem lokalen Rechner, auf der Sie selbst ein Modell installiert und am Laufen haben (ollama oder llama.cpp). Ob dies im einzelnen sinnvoll ist hängt von der Leistungsfähigkeit ihres eigenen Rechners ab (empfohlen wird eine oder mehrere leistungsfähige GPUs mit viel VRAM (>=32Gb), großer RAM Speicherausbau (>=64Gb) und ein leistungsfähiges Modell (mindestens 30B, besser 120B mit großem Kontext,da reichen aber 32GB VRAM nicht); eigene Erfahrungen haben wir unten in diesem Dokument zusammengetragen).
::- wählen Sie dazu "ollama" oder "llama.cpp" und geben als hostname "localhost" ein. Falls sie einen dedizierten Rechner in der Abteilung haben, kann natürlich auch dessen Hostname eingegeben werden.

==== KI von einem Cloudanbieter ====
* direkte Verbindung zu einem externen Anbieter (wie Anthropic, OpenAI etc.). Sicherheit: '''Fragwürdig''' (Sie müssen dem Anbieter und IP Verbindung vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup4.png|Einstellung
Datei:ArchExternalSetup3.png|Architektur
</gallery>
:Die Interaktion erfolgt lediglich mit der von Ihnen eingestellten URL über das expecco-interne chat Fenster. In sicherheitskritischem Umfeld ist jedoch davon abzuraten und ihre Netzadministrator wird diesen Zugang vermutlich auch nicht zulassen da (je nach URL) ihre Daten und ihr Chatverlauf an externe Rechner gehen, oder von fremden Geheimdiensten mitgelesen werden könnten). Prinzipiell sollte dies dem Netzadmin aber bekannt sein, und auf Netzwerkebene gesperrt sein, da ein solcher Zugriff auch anderen Programmen verwehrt werden muss (curl, Webbrowser etc.). Insofern ist ratsam, solche Verbindungen auf administrativer Ebene (Firewall, Router/Switch Konfiguration etc.) zu verhindern. Natürlich gilt diees nicht, falls sie eine eigenen firmeninterne cloud Infrastruktur besitzen, die vertrauenswürdig ist.
::- wählen Sie dazu "Anthropic, OpenAI, ..." und geben hostname+port+URL zu diesem host ein (wobei die Vorgabe im Eingabefeld typischerweise schon passt); typischerweise brauchen die Anbieter einen Zugangsschlüssel (sog. API key), den Sie bei der Registrierung vom Anbieter oder von ihrem Netzadmin erhalten. Achtung: verschiedene Anbieter (u.a. Anthropic) erlauben hier nur die Abrechnung über Ihr Token Budget, nicht über einen Pro/Max oder Enterprise plan. Es kann also hier zu erhöhten Kosten führen. Es ist uns weder technisch noch juristisch möglich, dies zu verhindern.

==== KI über CLI (eg. claude code); Bedienung über CLI ====
* indirekte Verbindung via CLI (z.B. ClaudeCode, Kiro, Tabnine, OpenCode, LMStudio etc.). Sicherheit: '''Unsicher''' (Sie müssen sowohl Anbieter und dem Modell vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup4.png|Einstellung
Datei:ArchExternalSetup1.png|Architektur
</gallery>
:Hier baut ein CLI Programm (z.B. "claude.exe") die Verbindung zum KI Modell auf (was natürlich seinerseits wiederum eine lokale in-house KI sein könnte). Dieses CLI Programm verbindet sich dann mit expecco und hat dort beschränkten Zugriff auf ihre Testsuite (über mcp). Die Interaktion erfolgt mit dem CLI Programm, die Bedienung des Modells erfolgt im CLI Programm. Das CLI hat kontrollieren Zugriff auf expecco über das sog. MCP Protokoll. Es ist zu beachten, dass die Konfiguration dem CLI Zugriff auf Dateien ermöglicht und es auch andere Aktionen auf Ihrem Rechner ausführen kann (shell/batch/powershell, Dateizugriffe etc.). Das Modell kann über das CLI Programm auch auf Ressourcen außerhalb expecco zugreifen. Und es könnte das System bzw. ihr Netz geziehlt ausspionieren oder manipulieren ohne daß expecco dies bemerkt oder verhindert. Sie müssen also sowohl dem Anbieter, der IP Verbindung als auch dem CLI Programm vertrauen.
::- sie müssen dem lokalen CLI Programm den Zugriff auf expecco erlauben. gehen Sie dazu in das "''Extras''" → "''Web-Dienste''" → "''MCP Zugriff erlauben (AI Coding)''". Die Konfiguration zum eigentlichen Modell erfolgt im CLI Programm Ihrer Wahl und ist nicht unter der Kontrolle von expecco; expecco erlaubt damit lediglich die Kontrolle von außerhalb über das MCP Protokoll. Eine Einstellung des Anbieters ist nicht notwendig; sie wird nicht benutzt, können daher beliebige Angaben machen.

==== KI über transparente CLI (nur claude code); Bedienung über ChatView ====
* indirekte Verbindung via unsichtbarer ClaudeCode CLI.
Sicherheit: '''Unsicher''' (Anbieter und Modell vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup5.png|Einstellung
Datei:ArchExternalCLIStdioSetup5.png|Architektur
</gallery>
:Auch hier erfolgt die Verbindung über das ClaudeCode CLI Programm, welches jedoch ohne Benutzeroberfläche den Verkehr lediglich weiter leitet (via stdin/stdout). Die Benutzerinteraktion erfolgt über das expecco-interne chat Fenster, der tatsächliche Modellzugriff vom CLI. Auch hier muss die Konfiguration des Modellzugriffs im CLI Programm erfolgen. Auch hier ist nicht technisch ausgeschlossen, daß das CLI Programm auf Daten außerhalb expecco zugreift. Falls das vom CLI technisch ermöglicht wird, könnte das Modell solche Zugriffe auslösen. Auch hier muß Modell, Verbindung und CLI Programm vertraut werden.

=== Tool Use ===

Der eigentlichen Mehrwert der KI besteht in der Möglichkeit dem Modell Zugriff auf das im expecco gezeigte Testprojekt zu gestatten. Es kann die Elemente des Baums lesen, Netzwerke analysieren und Ergebnisse (AktivityLogs) lesen.

Dazu sendet das Modell sog. "Tool Calls" zurück, die vom Empfänger im JSON Datenstrom erkannt und ausgeführt werden. Diese werden im folgenden "Tool Calls" genannt.

Ist ein CLI Programm (claude.exe, openCode.exe etc.) der Partner des Modells, erfolgt diese Erkennung dort, und die tools werden anhand des Toolmamens entweder im CLI selbst ausgeführt (Dateien lesen der schreiben, shwll/batch scripts ausführen, etc.) oder über das sog. MCP Protokoll an Drittprogramme weiter geleitet.
In unserem Fall stellt expecco die unten beschriebenen MCP tools bereit. Neben diesen könnten aber auch andere Aktionen (geheim oder offen) vom CLI ausgeführt werden. Und sie können dem CLI auch andere MCP Zugänge zu anderen Programmen bereitstellen. Sie müssen in diesem Fall also unbedingt dem CLI Programm und dem Modell und der IP Verbindung zur Außenwelt vertrauen. Sollten sie im sicherheitskritischen Umfeld solch ein Setup wählen ist unbedingt geraten, diesen Rechner vom Rest ihres Netzwerks zu isolieren, keine sensiblen Daten auf diesem Rechner zu halten, und den Verkehr zur Außenwelt über einen separaten Kanal abzuwickeln.

Ist kein CLI Programm involviert (i.e. die Verbindung geht von expecco direkt zum Modell) erfolgt die Erkennung von tool calls innerhalb expecco, und es ist dem Modell nicht möglich, andere Aktionen als die unten aufgeführten Funktionen aufzurufen. Sie haben also volle Kontrolle darüber.

==== Tool Funktionen von expecco ====

Diese Funktionen dienen dazu, dem Modell lesend und/oder schreibend auf ihre Testsuite (das im Browser dargestellte Projekt) zuzugreifen. Wie bereits beschrieben sind dies auch Funktionen die über MCP einem CLI Programm zur Verfügung gestellt werden, falls ein CLI Programm involviert ist.

Die expecco tool Funktionen wurden von uns eingeteilt in sog. "Safe" und "Unsafe" tools. Als sicher gelten rein lesende, als unsafe solche welche ihre Suite manipulieren oder Aktionen ausführen können.

Sie können in den expecco Einstellungen festlegen, ob tools generell verboten werden, nur safe tools erlaubt werden, oder auch für jedes individuelle tool eine Erlaubnis gegeben wird. Außerdem können Sie bestimmen ob bei jedem individuellen call eine Nachfrage um Erlaubnis erfolgen soll.

===== Safe Tools =====
* Suche von Elementen im Projekt
* Lesen der Schritte, Verbindungen, Pins, etc. in einem Netzwerk
* Lesen des Quellcodes einer Elementaraktion
* Lesen des Aktivitylogs nach einer Ausführung
* Suchen und Lesen von Hilfsfunktionen im unterliegenden Framework (eg. Smalltalk Basisklassen)

===== Unsafe Tools =====
* Anlegen neuer Elemente
* Änderungen in einem Netzwerk (Schritten, Verbindungen etc.)
* Ausführen einer Aktion, eines Testfalls oder Testplans

==== Im ChatView ====

===== Tool Calls Generell verbieten/erlauben =====

Der "mcp" Button im Chatview bestimmt ob tool calls prinzipiell erlaubt oder verboten werden. Fall generell erlaubt werden die unten beschriebenen Einzeleinstellungen wirksam; falls generell verboten sind diese irrelevant. 
Ohne tool calls können Sie immer noch mit dem Modell interagieren und sich von diesem z.B. Vorschläge zu Quellcode geben lassen - Sie müssen diese dann aber von Hand aus dem Chatview übernehmen oder mit copy/paste in ihre Suite eintragen. Falls sie unsafe tools erlaubt haben, könnte das Modell so eine Änderung automatisch durchführen.

<gallery widths="200px" perrow="4" heights="160px" >
Datei:ChatViewMCP1.png|Enable/Disable Tools
</gallery>

===== Individuelle Toolrechte =====
Falls tools nicht generell verboten sind ("MCP erlaubt"), können die Rechte gruppenweise und/oder individuell eingestellt werden. Dazu dient das "Tools" Menu des ChatViews:
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ChatViewMCP2.png|Enable/Disable Individual Tools
</gallery>

Das Menu umfasst die Einträge:
* "MCP Tools verwenden"
:die selbe Funktionwie der "MCP" Toolbar Knopf
* "Alle Tools automatisch erlauben"
:unterdrückt die individuelle Erlaubnis Nachfrage; achtung: der Titel dieser Menufunktion ist aktuell mißverständlich (und wird in der nächsten Release geändert); es betrifft die Nachfrage der prinzipiell schon durch die Einstellungen erlaubten tools.
* "Planungsmodus"
:alle tool calls werden automatisch abgelehnt; damit kann man vorab testen, welche Aktionen das Modell durchführen würde
* "Tools Schnellmenu"
:wie im Bild gezeigt: gruppenweise safe/unsafe tools erlauben, gruppenweise Domäne (Expecco / Smalltalk Framework), individuell Rechte einstellen

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>.
Es gibt keinen eXept-seitigen Proxy oder Zwischenspeicher.

Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, dass die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind. Die Verbindung zu den KI-Providern wird aber immer über eine SSL/TLS 1.3 verschlüsselte Verbindung hergestellt (von expecco-Seite aus wird auch Post-Quanten-Kryptographie unterstützt).

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Chat Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

Zusätzlich gibt es zwei Aktionen, die sich auf die ausgewählte '''Klasse'''
beziehen statt auf eine einzelne Methode ''(verfügbar ab expecco 26.2)''.
Es genügt, die Klasse auszuwählen; eine Methodenauswahl ist dafür nicht nötig:

* '''Explain Class''' — erklärt die Klasse als Ganzes: wofür sie zuständig ist, welche Rolle ihre Instanzvariablen spielen, wie ihre Protokolle zusammenwirken und worauf man beim Verwenden achten muss.
* '''Generate Class Documentation''' — schlägt einen Dokumentationstext für die Klasse vor; '''[Apply]''' trägt diesen in die Dokumentation der Klasse ein.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren nur mit vision-fähigen Modellen (bei OpenAI z.B. gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic, OpenAI etc. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.

* '''Claude Code (subscription)''' ''(verfügbar ab expecco 26.2)'' — dieser Anbieter verwendet nicht die API, sondern das lokal installierte Kommandozeilenprogramm ''Claude Code'' und damit Ihr vorhandenes Claude-Abonnement. Es wird kein API-Schlüssel benötigt, und es fallen keine tokenbasierten API-Kosten an. Die Felder '''API Key''', '''API URL''' und '''Proxy''' werden für diesen Anbieter ausgeblendet, da sie hier keine Bedeutung haben; als Authentifizierung erscheint "Subscription (external login)". Voraussetzung ist, dass ''Claude Code'' installiert ist und einmalig angemeldet wurde — dazu <code>claude</code> in einer Konsole starten und die Anmeldung abschließen. Das Modell kann als Stufen-Alias (''sonnet'', ''opus'', ''haiku'' — jeweils das aktuelle Modell dieser Stufe) oder als fester Modellname angegeben werden.

* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.

* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.

* '''Max output tokens''' — maximale Antwortlänge.

* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).
* Ollama/llama.cpp: kein API Key erforderlich
* Inhouse: fragen Sie ihren Admin

== Coding Assistenten (CLI Programm) ==

Beim Start der MCP-Server-Anbindung trägt expecco die nötigen Konfigurationseinträge automatisch in die Config-Dateien der unterstützten Coding-Assistenten ein. Die folgenden Abschnitte beschreiben Ort und Format der jeweiligen Einträge — zur Information bzw. falls Sie sie manuell ergänzen oder kontrollieren möchten.

=== Claude Code ===
: Anm.: Dieser Abschnitt beschreibt den umgekehrten Weg — ein extern laufendes ''Claude Code'' greift auf expecco zu. Wenn Sie ''Claude Code'' umgekehrt als KI-Anbieter ''innerhalb'' von expecco nutzen möchten, siehe den Anbieter '''Claude Code (subscription)''' im Abschnitt [[#Einstellungen (AI Coding)|Einstellungen]] ''(ab expecco 26.2)''.

Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"mcp": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls typischerweise im Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollte diese aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Dieser Abschnitt ist veraltet; die unten aufgeführten Aufgaben könnnen
nun 1:1 auch so im Chatfenster ausgeführt werden.

Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

=== Erfahrungen und Tipps für die Arbeit ===

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen weg - es sei denn sie dienen der Entscheidung. Tatsächlich erhöhen sie lediglich den Tokenverbrauch.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (ollama) ==

Bitte vorwärts scrollen zu LLaMa.cpp Versuch.

Erste Versuche waren eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation (ollama) ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Zusammenfassung (lokale AI mit kleinen Modellen) ==

Man sollte sich keinen Illusionen hingeben: eine lokale AI mit ein paar Milliarden floats (oder gar 4bit quantized) kann nicht im geringsten mit
einem Modell mit Billionen Werten mithalten (i.e. Claude oder ChatGPT oder einem hauseigenen großen Rechenzentrum mit ein paar 10000 NVidia GPUs).

Hier ein chat mit lokalem llama3.2:3b (3 Milliarden floats, bf16); wichtig anzumerken, dass dieses Modell kein instruct Modell ist, es also nicht trainiert wurde, tool calls zu emittieren; was unten klar wird:
--- user ---
how ´would you open an expecco app using mcp

''ich frage wie er unsere mcp Anbindung aufrufen würde (große Modelle von Anthropic oder OpenAI würden hier korrekt antworten)''

```
MCP.openApp("type://com.expeccotech.app.name", null);
```

Replace `"type://com.expeccotech.app.name"` with the specific type identifier for your app. This might be a URI or a project handle.

This command will open the Expecco app using MCP, and it may prompt you to authenticate or authorize if necessary.

Here's an example of how you could use this method in Python:

```python
import mcpsys

app = mcpsys.MCP()
app.openApp("type://com.expeccotech.app.name", None)
```

In JavaScript, you can also use this method with the following code:

```javascript
var app = new MCP();
app.openApp("type://com.expeccotech.app.name", null);
```

''das ist natürlich völliger Unsinn; man könnte sagen: er saugt sich das aus den Fingern; sagen wir ihm das:''

--- user ---
you just made this all up. you are wrong. do not hallucinate. what mcp tools do you really have at hand

--- assistant ---
I got a bit carried away with my imagination.

To be honest, I don't actually have any MCP (Model Computing Platform) tools or knowledge at hand. I'm an AI trained on general knowledge and can only provide information based on my training data.

MCP is a specific framework developed by the University of Michigan, and it seems that I was not properly informed about its capabilities and tools. If you'd like to correct me or provide more information about MCP, I'll do my best to learn from it!

''aha - er gibt es zu!''

== LLaMa.cpp ==

Installation siehe Webseite von llama.

Kommando:
llama-server.exe -hf unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:Q4_K_M --cts-size XXXX

Hinweise
:hier wird ein instruct Modell geladen; es sollte also tool calls beherrschen.
:per default verwendet llama.cpp nur ein Kontextfenster von 4096 Tokens. Das ist zu wenig für sinnvolle Aufgaben. Starten Sie llama.cpp mit --ctx-size 8192, 16384, 32768 oder 65536. Die unterstützte Größe hängt vom Modell ab. Ein großer Kontext hat natürlich Einfluss auf Speicherbedarf (VRAM in GPU, RAM in CPU) und Antwortzeit. Wenn Sie genug CPU VRAM bzw. RAM haben, ist es in jedem Fall besser, eine größere Kontextsize zu setzen (bedenken Sie, dass die großen Modelle von Anthropic oder ChatGPT Kontexte von 200k oder 1Mio haben).

Das Modell läuft auf der lokalen CPU (Laptop, ohne GPU), und zeigt dabei durchaus gute Antworten (wenn man Geduld hat). Zugegeben, wir haben auch einiges an Wissen in den Speicher vorgepackt.

Im expecco Chat Fenster:
open an exepcco browser on a new project
macht er!
create a python action to compute the area from given radius
er legt eine korrekte Pythonscript Aktion an. Chapeau. Sogar die Behandlung der Ein- und Ausgangspins, die bei Scriptaktionen etwas umständlich ist, hat er gemeistert.

again, as Smalltalk action
braucht etwas, aber er reagiert auf Syntaxfehler, korrigiert sich. Danach führt er die Aktion zur Verifikation aus. Ausgabe: 
''Verified: for `radius = 5.0`, `area = 78.5398163397448` — same result as the Python version.''

Die Frage wie man einen String (z.B. 'helloworld') zerlegt geht er systematisch an - er sucht im laufenden expecco nach Stringfunktionen. Das dauert



== Wahl der Modellgrösse ==

=== Übersetzung ===
Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In keinem Fall sollte man der KI "blind" vertrauen.

=== Arbeit mit Expecco ===
Um das Modell tatsächlich Code oder Aktionen erzeugen zu lassen reichen die
einfachsten Modell NICHT;
Hier eine vorläufige Liste unserer Resultate:

* qwen2.5-coder:3b definitiv zu dumm
* qwen2.5-coder:7b nach einigen Verbesserungen an den initialen Anweisungen zum Gebrauch der expecco tools kann das Model: Browser öffnen, Projekt anlegen. Achtung: benötigt contextSize=8192; mit 4096 ist es zu vergesslich
*
[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

KI Coding Plugin

2026-08-06T08:19:43Z

Sv: Abschnitt Lizenzierung: KI Coding vs KI Advanced Coding, mit Sicherheitsaspekten

{{Languages|KI Coding Plugin|label=Deutsch}}

= KI Coding Plugin =

Die hier beschriebenen KI-Funktionen sind Teil des Lizenz-Features '''AI Coding'''. Ist dieses Feature in Ihrer Lizenz nicht enthalten, erscheinen die ''Ask AI''-Menüeinträge zwar weiterhin sichtbar in den Editor-Toolbars, sind aber deaktiviert (Tooltip: "''Install the AI coding plugin to enable''").

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic (aka Claude)''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI (i.e. ChatGPT)''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
* '''llama.cpp''' lokal oder remote
* '''Groq''', '''Zen''', '''LLaMa''', '''Tabnine''' etc.
* '''Claude Code (subscription)''' — nutzt Ihr vorhandenes Claude-Abonnement statt eines API-Schlüssels ''(verfügbar ab expecco 26.2)''
* '''Inhouse''' — ihre eigene in-house (in-Firma) KI.

Wichtig: 
Der zusätzliche Eintrag '''Inhouse''' ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern oder einer anderen fimeninternen KI chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Lizenzierung ==

Die KI-Funktionen sind auf '''zwei getrennte Lizenz-Features''' aufgeteilt. Die Trennung verläuft genau entlang der Grenze zwischen ''lesen'' und ''verändern'':

* '''KI Coding''' (im Lizenzfile: ''AI Coding'') — die Grundlizenz. Sie lädt das Plugin überhaupt erst und schaltet Chat-Fenster, Anbieterauswahl und die lesenden (''safe'') Werkzeuge frei.
* '''KI Advanced Coding''' (im Lizenzfile: ''AI Advanced Coding'') — ein eigenes, zusätzlich zu erwerbendes Feature. Es setzt ''KI Coding'' voraus und schaltet die schreibenden (''unsafe'') Werkzeuge frei.

=== KI Coding ===

Ohne dieses Feature ist das Plugin nicht geladen: die ''Ask AI''-Einträge bleiben in den Editor-Toolbars sichtbar, sind aber deaktiviert (Tooltip: "''Install the AI coding plugin to enable''").

Mit ''KI Coding'' können Sie in vollem Umfang mit dem Modell arbeiten, solange es dabei bleibt, Ihr Projekt zu ''lesen'': Elemente suchen, Netzwerke und Quellcode analysieren, Aktivitylogs auswerten, Dokumentation entwerfen, Fehlerursachen erklären lassen. Vorschläge des Modells — etwa neuer Quellcode für eine Elementaraktion — erscheinen im Chat-Fenster und werden von Ihnen bewusst übernommen (''Apply''-Knopf oder copy/paste). Die Entscheidung, ob eine Änderung in die Suite gelangt, liegt in jedem Einzelfall bei Ihnen.

=== KI Advanced Coding ===

Dieses Feature schaltet die Werkzeuge frei, mit denen das Modell Ihr Projekt und Ihre Arbeitsumgebung '''selbst verändern''' kann — im Wesentlichen die im Abschnitt [[#Unsafe Tools|Unsafe Tools]] aufgeführten Funktionen: Elemente anlegen, Netzwerke ändern, Methoden und Klassen definieren, Aktionen und Testfälle ausführen sowie Änderungen in die Versionsverwaltung einchecken.

Fehlt das Feature, stehen diese Werkzeuge '''auch dann nicht zur Verfügung, wenn sie im ChatView ausdrücklich erlaubt wurden'''. Das Modell erhält in diesem Fall eine Fehlermeldung statt der Ausführung; die Sitzung läuft normal weiter.

=== Sicherheitsaspekte ===

Die Lizenz ist die '''äußere''' von zwei voneinander unabhängigen Schutzschichten. Beide müssen eine Aktion erlauben, damit sie ausgeführt wird:

* '''Lizenz-Ebene''' (''KI Advanced Coding'') — organisatorisch, gilt für die gesamte Installation und ist '''vom Anwender nicht umschaltbar'''. Sie hängt an der signierten Lizenzdatei und lässt sich nicht über eine Einstellung, eine Umgebungsvariable oder eine Konfigurationsdatei aktivieren.
* '''Laufzeit-Ebene''' (''MCP''-Knopf, Tools-Menü, Planungsmodus) — situativ, gilt für die einzelne Chat-Sitzung und ist vom Anwender jederzeit umschaltbar. Siehe [[#Individuelle Toolrechte|Individuelle Toolrechte]].

Daraus ergeben sich die praktisch wichtigen Eigenschaften:

* '''Eine Organisation kann verbindlich festlegen, dass die KI grundsätzlich nur lesend arbeitet.''' Wird ''KI Advanced Coding'' nicht lizenziert, bleibt es dabei — unabhängig davon, was einzelne Anwender in ihrem ChatView einstellen, und unabhängig davon, ob jemand versehentlich "Alle Tools automatisch erlauben" aktiviert.
* '''Grundsatz der geringsten Rechte.''' Der Auslieferungszustand ist lesend; Schreibrechte müssen bewusst erworben werden und sind damit auch eine dokumentierte Entscheidung, kein Nebeneffekt einer Voreinstellung.
* '''Die Prüfung gilt auch für den Zugriff von außen.''' Greift ein externes CLI-Programm (''claude code'', ''cursor'', ''zed'', ''tabnine'') über das MCP-Protokoll auf expecco zu, unterliegen die schreibenden Werkzeuge derselben Prüfung. Ein externes Programm kann sie nicht umgehen — es erhält dieselbe Fehlermeldung wie das Modell im internen Chat.
* '''Der Prüfpunkt liegt bei der Ausführung, nicht in der Oberfläche.''' Die Werkzeuge werden nicht lediglich im Menü ausgeblendet; der Aufruf selbst wird abgewiesen. Ein ausgeblendeter Menüeintrag wäre keine Sicherheitsmaßnahme.

Ebenso wichtig ist, was die Lizenz '''nicht''' leistet:

* Sie begrenzt, '''was die KI in expecco tun darf''' — nicht, '''welche Daten das Haus verlassen'''. Welcher Anbieter Ihren Quellcode zu sehen bekommt, entscheidet allein die Anbieterwahl; siehe [[#Datenschutz / Datenfluss|Datenschutz / Datenfluss]]. Auch mit reinem ''KI Coding'' wird beim Einsatz eines Cloud-Anbieters Projektinhalt übertragen.
* Sie ersetzt nicht die Prüfung dessen, was das Modell vorschlägt. Auch eine lizenzierte Änderung ist eine Änderung eines Modells und gehört wie jeder fremde Beitrag reviewt.
* Sie schützt nicht vor einem kompromittierten CLI-Programm auf demselben Rechner. Für sicherheitskritische Umgebungen gelten weiterhin die Hinweise im Abschnitt [[#Tool Use|Tool Use]] zur Isolation solcher Rechner.

Für eine sicherheitskritische Umgebung ergibt sich daraus die restriktivste sinnvolle Konfiguration: ''KI Coding'' ohne ''KI Advanced Coding'', kombiniert mit einem lokal betriebenen Modell (''ollama'' oder ''llama.cpp''). Dann verlässt kein Projektinhalt Ihr Netz, und die KI kann ausschließlich lesen und vorschlagen.

== Architektur und Sicherheit ==

Mit "''Sicherheit''" ist hier gemeint: "''können die Daten den Rechner oder ihre Abteilung/Firma verlassen'' bzw. ''kann die KI Schaden anrichten indem sie auf Ihrem Rechner unkontrolliert Code ausführt oder Daten manipuliert''".

Anmerkung: Wenn hohe Sicherheit gefordert ist (sensible Daten, Algorithmen, Workflows) muss Ihr Netzadmin durch geeignete Maßnahmen (Firewall, Router/Switch Konfiguration etc.) verhindern, dass Zugriffe sowohl ausgehend als auch eingehend zu/von außerhalb ihrer Domäne möglich sind.
Das "unsichtbar machen" entsprechender Einstellungsdialoge in expecco wäre hierzu nicht dienlich, da bei offenen Ports unzählige andere Möglichkeiten bestehen (curl, webbrowser, low-level Socket API etc.).

Zur Sicherheit ihrer eigenen Testsuite und möglichen Aktionen der KI lesen Sie bitte die unten aufgeführten Abschnitte zu [[#tool_use|"Tool Use"]].

=== Architektur ===

Im folgenden werden die Einstellungen und die zugehörigen Datenflüsse/kanäle beschrieben.

Mögliche Setups sind:

==== KI Firmenintern ====
* direkte Verbindung zu einer KI auf einem Rechner in ihrem lokalen Netzwerk, Firmennetz oder einem definiert sicheren Firmenanbieter. Sicherheit: '''Hoch''' (weder Daten noch Chat-Text gehen aus dem Haus)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:InhouseSetup1.png|Einstellung
Datei:ArchInhouseSetup1.png|Architektur
</gallery>
:expecco kommuniziert ausschließlich und direkt zu dieser URL; keine Applikation dazwischen. Insbesondere kein "<code>claude.exe</code>" oder ein anderes Command Line Interface (CLI) Programm. Ihre Eingaben im expecco Chat Fenster gehen direkt (verpackt als JSON) an die konfigurierte Adresse und deren Antwort erscheint (entpackt aus JSON) im expecco Chat Fenster. Nachrichten werden ausschließlich mit dem von Ihnen konfigurierten Host ausgetauscht.

::- wählen Sie dazu "inhouse" und geben hostname+port+URL zu diesem host ein; typischerweise haben diese die Form "<code>firmenAI:11434/v1/chat/completions</code>" oder auch 80 oder 8080 als port. Fragen Sie ihren Netzwerkadmin im Zweifel, auch ob ein API Key (= Zugangsschlüssel) erforderlich ist.

==== KI auf Ihrem eigenen Rechner ====

* direkte Verbindung zu einer lokalen KI auf ihrem eignen persönlichen Rechner Sicherheit: '''Sehr Hoch''' (weder Daten noch Chat verlassen ihren Rechner)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:LocalSetup2.png|Einstellung
Datei:ArchLocalSetup2.png|Architektur
</gallery>
:auch hier kommuniziert expecco ausschließlich und direkt zu diesem ihrem lokalen Rechner, auf der Sie selbst ein Modell installiert und am Laufen haben (ollama oder llama.cpp). Ob dies im einzelnen sinnvoll ist hängt von der Leistungsfähigkeit ihres eigenen Rechners ab (empfohlen wird eine oder mehrere leistungsfähige GPUs mit viel VRAM (>=32Gb), großer RAM Speicherausbau (>=64Gb) und ein leistungsfähiges Modell (mindestens 30B, besser 120B mit großem Kontext,da reichen aber 32GB VRAM nicht); eigene Erfahrungen haben wir unten in diesem Dokument zusammengetragen).
::- wählen Sie dazu "ollama" oder "llama.cpp" und geben als hostname "localhost" ein. Falls sie einen dedizierten Rechner in der Abteilung haben, kann natürlich auch dessen Hostname eingegeben werden.

==== KI von einem Cloudanbieter ====
* direkte Verbindung zu einem externen Anbieter (wie Anthropic, OpenAI etc.). Sicherheit: '''Fragwürdig''' (Sie müssen dem Anbieter und IP Verbindung vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup4.png|Einstellung
Datei:ArchExternalSetup3.png|Architektur
</gallery>
:Die Interaktion erfolgt lediglich mit der von Ihnen eingestellten URL über das expecco-interne chat Fenster. In sicherheitskritischem Umfeld ist jedoch davon abzuraten und ihre Netzadministrator wird diesen Zugang vermutlich auch nicht zulassen da (je nach URL) ihre Daten und ihr Chatverlauf an externe Rechner gehen, oder von fremden Geheimdiensten mitgelesen werden könnten). Prinzipiell sollte dies dem Netzadmin aber bekannt sein, und auf Netzwerkebene gesperrt sein, da ein solcher Zugriff auch anderen Programmen verwehrt werden muss (curl, Webbrowser etc.). Insofern ist ratsam, solche Verbindungen auf administrativer Ebene (Firewall, Router/Switch Konfiguration etc.) zu verhindern. Natürlich gilt diees nicht, falls sie eine eigenen firmeninterne cloud Infrastruktur besitzen, die vertrauenswürdig ist.
::- wählen Sie dazu "Anthropic, OpenAI, ..." und geben hostname+port+URL zu diesem host ein (wobei die Vorgabe im Eingabefeld typischerweise schon passt); typischerweise brauchen die Anbieter einen Zugangsschlüssel (sog. API key), den Sie bei der Registrierung vom Anbieter oder von ihrem Netzadmin erhalten. Achtung: verschiedene Anbieter (u.a. Anthropic) erlauben hier nur die Abrechnung über Ihr Token Budget, nicht über einen Pro/Max oder Enterprise plan. Es kann also hier zu erhöhten Kosten führen. Es ist uns weder technisch noch juristisch möglich, dies zu verhindern.

==== KI über CLI (eg. claude code); Bedienung über CLI ====
* indirekte Verbindung via CLI (z.B. ClaudeCode, Kiro, Tabnine, OpenCode, LMStudio etc.). Sicherheit: '''Unsicher''' (Sie müssen sowohl Anbieter und dem Modell vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup4.png|Einstellung
Datei:ArchExternalSetup1.png|Architektur
</gallery>
:Hier baut ein CLI Programm (z.B. "claude.exe") die Verbindung zum KI Modell auf (was natürlich seinerseits wiederum eine lokale in-house KI sein könnte). Dieses CLI Programm verbindet sich dann mit expecco und hat dort beschränkten Zugriff auf ihre Testsuite (über mcp). Die Interaktion erfolgt mit dem CLI Programm, die Bedienung des Modells erfolgt im CLI Programm. Das CLI hat kontrollieren Zugriff auf expecco über das sog. MCP Protokoll. Es ist zu beachten, dass die Konfiguration dem CLI Zugriff auf Dateien ermöglicht und es auch andere Aktionen auf Ihrem Rechner ausführen kann (shell/batch/powershell, Dateizugriffe etc.). Das Modell kann über das CLI Programm auch auf Ressourcen außerhalb expecco zugreifen. Und es könnte das System bzw. ihr Netz geziehlt ausspionieren oder manipulieren ohne daß expecco dies bemerkt oder verhindert. Sie müssen also sowohl dem Anbieter, der IP Verbindung als auch dem CLI Programm vertrauen.
::- sie müssen dem lokalen CLI Programm den Zugriff auf expecco erlauben. gehen Sie dazu in das "''Extras''" → "''Web-Dienste''" → "''MCP Zugriff erlauben (AI Coding)''". Die Konfiguration zum eigentlichen Modell erfolgt im CLI Programm Ihrer Wahl und ist nicht unter der Kontrolle von expecco; expecco erlaubt damit lediglich die Kontrolle von außerhalb über das MCP Protokoll. Eine Einstellung des Anbieters ist nicht notwendig; sie wird nicht benutzt, können daher beliebige Angaben machen.

==== KI über transparente CLI (nur claude code); Bedienung über ChatView ====
* indirekte Verbindung via unsichtbarer ClaudeCode CLI.
Sicherheit: '''Unsicher''' (Anbieter und Modell vertrauen)
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ExternalSetup5.png|Einstellung
Datei:ArchExternalCLIStdioSetup5.png|Architektur
</gallery>
:Auch hier erfolgt die Verbindung über das ClaudeCode CLI Programm, welches jedoch ohne Benutzeroberfläche den Verkehr lediglich weiter leitet (via stdin/stdout). Die Benutzerinteraktion erfolgt über das expecco-interne chat Fenster, der tatsächliche Modellzugriff vom CLI. Auch hier muss die Konfiguration des Modellzugriffs im CLI Programm erfolgen. Auch hier ist nicht technisch ausgeschlossen, daß das CLI Programm auf Daten außerhalb expecco zugreift. Falls das vom CLI technisch ermöglicht wird, könnte das Modell solche Zugriffe auslösen. Auch hier muß Modell, Verbindung und CLI Programm vertraut werden.

=== Tool Use ===

Der eigentlichen Mehrwert der KI besteht in der Möglichkeit dem Modell Zugriff auf das im expecco gezeigte Testprojekt zu gestatten. Es kann die Elemente des Baums lesen, Netzwerke analysieren und Ergebnisse (AktivityLogs) lesen.

Dazu sendet das Modell sog. "Tool Calls" zurück, die vom Empfänger im JSON Datenstrom erkannt und ausgeführt werden. Diese werden im folgenden "Tool Calls" genannt.

Ist ein CLI Programm (claude.exe, openCode.exe etc.) der Partner des Modells, erfolgt diese Erkennung dort, und die tools werden anhand des Toolmamens entweder im CLI selbst ausgeführt (Dateien lesen der schreiben, shwll/batch scripts ausführen, etc.) oder über das sog. MCP Protokoll an Drittprogramme weiter geleitet.
In unserem Fall stellt expecco die unten beschriebenen MCP tools bereit. Neben diesen könnten aber auch andere Aktionen (geheim oder offen) vom CLI ausgeführt werden. Und sie können dem CLI auch andere MCP Zugänge zu anderen Programmen bereitstellen. Sie müssen in diesem Fall also unbedingt dem CLI Programm und dem Modell und der IP Verbindung zur Außenwelt vertrauen. Sollten sie im sicherheitskritischen Umfeld solch ein Setup wählen ist unbedingt geraten, diesen Rechner vom Rest ihres Netzwerks zu isolieren, keine sensiblen Daten auf diesem Rechner zu halten, und den Verkehr zur Außenwelt über einen separaten Kanal abzuwickeln.

Ist kein CLI Programm involviert (i.e. die Verbindung geht von expecco direkt zum Modell) erfolgt die Erkennung von tool calls innerhalb expecco, und es ist dem Modell nicht möglich, andere Aktionen als die unten aufgeführten Funktionen aufzurufen. Sie haben also volle Kontrolle darüber.

==== Tool Funktionen von expecco ====

Diese Funktionen dienen dazu, dem Modell lesend und/oder schreibend auf ihre Testsuite (das im Browser dargestellte Projekt) zuzugreifen. Wie bereits beschrieben sind dies auch Funktionen die über MCP einem CLI Programm zur Verfügung gestellt werden, falls ein CLI Programm involviert ist.

Die expecco tool Funktionen wurden von uns eingeteilt in sog. "Safe" und "Unsafe" tools. Als sicher gelten rein lesende, als unsafe solche welche ihre Suite manipulieren oder Aktionen ausführen können.

Sie können in den expecco Einstellungen festlegen, ob tools generell verboten werden, nur safe tools erlaubt werden, oder auch für jedes individuelle tool eine Erlaubnis gegeben wird. Außerdem können Sie bestimmen ob bei jedem individuellen call eine Nachfrage um Erlaubnis erfolgen soll.

===== Safe Tools =====
* Suche von Elementen im Projekt
* Lesen der Schritte, Verbindungen, Pins, etc. in einem Netzwerk
* Lesen des Quellcodes einer Elementaraktion
* Lesen des Aktivitylogs nach einer Ausführung
* Suchen und Lesen von Hilfsfunktionen im unterliegenden Framework (eg. Smalltalk Basisklassen)

===== Unsafe Tools =====
* Anlegen neuer Elemente
* Änderungen in einem Netzwerk (Schritten, Verbindungen etc.)
* Ausführen einer Aktion, eines Testfalls oder Testplans

==== Im ChatView ====

===== Tool Calls Generell verbieten/erlauben =====

Der "mcp" Button im Chatview bestimmt ob tool calls prinzipiell erlaubt oder verboten werden. Fall generell erlaubt werden die unten beschriebenen Einzeleinstellungen wirksam; falls generell verboten sind diese irrelevant. 
Ohne tool calls können Sie immer noch mit dem Modell interagieren und sich von diesem z.B. Vorschläge zu Quellcode geben lassen - Sie müssen diese dann aber von Hand aus dem Chatview übernehmen oder mit copy/paste in ihre Suite eintragen. Falls sie unsafe tools erlaubt haben, könnte das Modell so eine Änderung automatisch durchführen.

<gallery widths="200px" perrow="4" heights="160px" >
Datei:ChatViewMCP1.png|Enable/Disable Tools
</gallery>

===== Individuelle Toolrechte =====
Falls tools nicht generell verboten sind ("MCP erlaubt"), können die Rechte gruppenweise und/oder individuell eingestellt werden. Dazu dient das "Tools" Menu des ChatViews:
<gallery widths="200px" perrow="4" heights="160px" >
Datei:ChatViewMCP2.png|Enable/Disable Individual Tools
</gallery>

Das Menu umfasst die Einträge:
* "MCP Tools verwenden"
:die selbe Funktionwie der "MCP" Toolbar Knopf
* "Alle Tools automatisch erlauben"
:unterdrückt die individuelle Erlaubnis Nachfrage; achtung: der Titel dieser Menufunktion ist aktuell mißverständlich (und wird in der nächsten Release geändert); es betrifft die Nachfrage der prinzipiell schon durch die Einstellungen erlaubten tools.
* "Planungsmodus"
:alle tool calls werden automatisch abgelehnt; damit kann man vorab testen, welche Aktionen das Modell durchführen würde
* "Tools Schnellmenu"
:wie im Bild gezeigt: gruppenweise safe/unsafe tools erlauben, gruppenweise Domäne (Expecco / Smalltalk Framework), individuell Rechte einstellen

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>.
Es gibt keinen eXept-seitigen Proxy oder Zwischenspeicher.

Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, daß die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind.

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Chat Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

Zusätzlich gibt es zwei Aktionen, die sich auf die ausgewählte '''Klasse'''
beziehen statt auf eine einzelne Methode ''(verfügbar ab expecco 26.2)''.
Es genügt, die Klasse auszuwählen; eine Methodenauswahl ist dafür nicht nötig:

* '''Explain Class''' — erklärt die Klasse als Ganzes: wofür sie zuständig ist, welche Rolle ihre Instanzvariablen spielen, wie ihre Protokolle zusammenwirken und worauf man beim Verwenden achten muss.
* '''Generate Class Documentation''' — schlägt einen Dokumentationstext für die Klasse vor; '''[Apply]''' trägt diesen in die Dokumentation der Klasse ein.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren nur mit vision-fähigen Modellen (bei OpenAI z.B. gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic, OpenAI etc. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.

* '''Claude Code (subscription)''' ''(verfügbar ab expecco 26.2)'' — dieser Anbieter verwendet nicht die API, sondern das lokal installierte Kommandozeilenprogramm ''Claude Code'' und damit Ihr vorhandenes Claude-Abonnement. Es wird kein API-Schlüssel benötigt, und es fallen keine tokenbasierten API-Kosten an. Die Felder '''API Key''', '''API URL''' und '''Proxy''' werden für diesen Anbieter ausgeblendet, da sie hier keine Bedeutung haben; als Authentifizierung erscheint "Subscription (external login)". Voraussetzung ist, dass ''Claude Code'' installiert ist und einmalig angemeldet wurde — dazu <code>claude</code> in einer Konsole starten und die Anmeldung abschließen. Das Modell kann als Stufen-Alias (''sonnet'', ''opus'', ''haiku'' — jeweils das aktuelle Modell dieser Stufe) oder als fester Modellname angegeben werden.

* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.

* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.

* '''Max output tokens''' — maximale Antwortlänge.

* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).
* Ollama/llama.cpp: kein API Key erforderlich
* Inhouse: fragen Sie ihren Admin

== Coding Assistenten (CLI Programm) ==

Beim Start der MCP-Server-Anbindung trägt expecco die nötigen Konfigurationseinträge automatisch in die Config-Dateien der unterstützten Coding-Assistenten ein. Die folgenden Abschnitte beschreiben Ort und Format der jeweiligen Einträge — zur Information bzw. falls Sie sie manuell ergänzen oder kontrollieren möchten.

=== Claude Code ===
: Anm.: Dieser Abschnitt beschreibt den umgekehrten Weg — ein extern laufendes ''Claude Code'' greift auf expecco zu. Wenn Sie ''Claude Code'' umgekehrt als KI-Anbieter ''innerhalb'' von expecco nutzen möchten, siehe den Anbieter '''Claude Code (subscription)''' im Abschnitt [[#Einstellungen (AI Coding)|Einstellungen]] ''(ab expecco 26.2)''.

Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"mcp": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls typischerweise im Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollte diese aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Dieser Abschnitt ist veraltet; die unten aufgeführten Aufgaben könnnen
nun 1:1 auch so im Chatfenster ausgeführt werden.

Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

=== Erfahrungen und Tipps für die Arbeit ===

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen weg - es sei denn sie dienen der Entscheidung. Tatsächlich erhöhen sie lediglich den Tokenverbrauch.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (ollama) ==

Bitte vorwärts scrollen zu LLaMa.cpp Versuch.

Erste Versuche waren eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation (ollama) ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Zusammenfassung (lokale AI mit kleinen Modellen) ==

Man sollte sich keinen Illusionen hingeben: eine lokale AI mit ein paar Milliarden floats (oder gar 4bit quantized) kann nicht im geringsten mit
einem Modell mit Billionen Werten mithalten (i.e. Claude oder ChatGPT oder einem hauseigenen großen Rechenzentrum mit ein paar 10000 NVidia GPUs).

Hier ein chat mit lokalem llama3.2:3b (3 Milliarden floats, bf16); wichtig anzumerken, dass dieses Modell kein instruct Modell ist, es also nicht trainiert wurde, tool calls zu emittieren; was unten klar wird:
--- user ---
how ´would you open an expecco app using mcp

''ich frage wie er unsere mcp Anbindung aufrufen würde (große Modelle von Anthropic oder OpenAI würden hier korrekt antworten)''

```
MCP.openApp("type://com.expeccotech.app.name", null);
```

Replace `"type://com.expeccotech.app.name"` with the specific type identifier for your app. This might be a URI or a project handle.

This command will open the Expecco app using MCP, and it may prompt you to authenticate or authorize if necessary.

Here's an example of how you could use this method in Python:

```python
import mcpsys

app = mcpsys.MCP()
app.openApp("type://com.expeccotech.app.name", None)
```

In JavaScript, you can also use this method with the following code:

```javascript
var app = new MCP();
app.openApp("type://com.expeccotech.app.name", null);
```

''das ist natürlich völliger Unsinn; man könnte sagen: er saugt sich das aus den Fingern; sagen wir ihm das:''

--- user ---
you just made this all up. you are wrong. do not hallucinate. what mcp tools do you really have at hand

--- assistant ---
I got a bit carried away with my imagination.

To be honest, I don't actually have any MCP (Model Computing Platform) tools or knowledge at hand. I'm an AI trained on general knowledge and can only provide information based on my training data.

MCP is a specific framework developed by the University of Michigan, and it seems that I was not properly informed about its capabilities and tools. If you'd like to correct me or provide more information about MCP, I'll do my best to learn from it!

''aha - er gibt es zu!''

== LLaMa.cpp ==

Installation siehe Webseite von llama.

Kommando:
llama-server.exe -hf unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:Q4_K_M --cts-size XXXX

Hinweise
:hier wird ein instruct Modell geladen; es sollte also tool calls beherrschen.
:per default verwendet llama.cpp nur ein Kontextfenster von 4096 Tokens. Das ist zu wenig für sinnvolle Aufgaben. Starten Sie llama.cpp mit --ctx-size 8192, 16384, 32768 oder 65536. Die unterstützte Größe hängt vom Modell ab. Ein großer Kontext hat natürlich Einfluss auf Speicherbedarf (VRAM in GPU, RAM in CPU) und Antwortzeit. Wenn Sie genug CPU VRAM bzw. RAM haben, ist es in jedem Fall besser, eine größere Kontextsize zu setzen (bedenken Sie, dass die großen Modelle von Anthropic oder ChatGPT Kontexte von 200k oder 1Mio haben).

Das Modell läuft auf der lokalen CPU (Laptop, ohne GPU), und zeigt dabei durchaus gute Antworten (wenn man Geduld hat). Zugegeben, wir haben auch einiges an Wissen in den Speicher vorgepackt.

Im expecco Chat Fenster:
open an exepcco browser on a new project
macht er!
create a python action to compute the area from given radius
er legt eine korrekte Pythonscript Aktion an. Chapeau. Sogar die Behandlung der Ein- und Ausgangspins, die bei Scriptaktionen etwas umständlich ist, hat er gemeistert.

again, as Smalltalk action
braucht etwas, aber er reagiert auf Syntaxfehler, korrigiert sich. Danach führt er die Aktion zur Verifikation aus. Ausgabe: 
''Verified: for `radius = 5.0`, `area = 78.5398163397448` — same result as the Python version.''

Die Frage wie man einen String (z.B. 'helloworld') zerlegt geht er systematisch an - er sucht im laufenden expecco nach Stringfunktionen. Das dauert



== Wahl der Modellgrösse ==

=== Übersetzung ===
Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In keinem Fall sollte man der KI "blind" vertrauen.

=== Arbeit mit Expecco ===
Um das Modell tatsächlich Code oder Aktionen erzeugen zu lassen reichen die
einfachsten Modell NICHT;
Hier eine vorläufige Liste unserer Resultate:

* qwen2.5-coder:3b definitiv zu dumm
* qwen2.5-coder:7b nach einigen Verbesserungen an den initialen Anweisungen zum Gebrauch der expecco tools kann das Model: Browser öffnen, Projekt anlegen. Achtung: benötigt contextSize=8192; mit 4096 ist es zu vergesslich
*
[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

Release Notes 26.x

2026-07-31T12:39:10Z

Sv: 26.2: add HTTP/2 (h2) support in the embedded web server

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==
* Feature: bridged Scheme (currently only Racket Scheme) action blocks
* Feature: bridged Octave/Matlab action blocks
* Feature: bridged C# action blocks
* Feature: '''NEW''' AI Coding provider "'''Claude Code (subscription)'''" — uses your existing Claude subscription via the locally installed ''Claude Code'' command line program instead of an API key, so no key has to be entered and no per-token API charges are billed. Choose it like any other provider in the settings dialog (Plugins → AI Coding); the API key, endpoint URL and proxy fields are hidden for it because they do not apply, and the authentication method reads "Subscription (external login)". It requires ''Claude Code'' to be installed and logged in once (run <code>claude</code> in a terminal and complete the login). The model is selectable either as a tier alias (''sonnet'', ''opus'', ''haiku'' — always the current model of that tier) or as a pinned model id.
* Feature: two new AI actions that work on the selected '''class''' rather than on a single method, reachable from the '''AI''' menu of the class browser: "'''Explain Class'''" explains the class as a whole — what it is responsible for, what its instance variables hold and how its protocols fit together — and "'''Generate Class Documentation'''" proposes a class documentation text which the "[Apply]" button installs into the class' documentation.
* Feature: HTTP/2 (h2) support in the embedded web server, negotiated via TLS ALPN, with HPACK header compression and request multiplexing over a single connection. Implemented in pure Smalltalk, so no external library is required. This is the server side only — the HTTP client (''HTTPInterface'') continues to speak HTTP/1.1. A server configured without a certificate stays on HTTP/1.1, because h2 is negotiated during the TLS handshake; the offer can be turned off with <code>HTTPServer http2Enabled:false</code>.

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports '''Anthropic Claude''', '''OpenAI ChatGPT''', '''ollama''' and others as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via [[Tools_FileBrowser/en|FileBrowser]])
* Feature: public/private keypair generation via a [[Tools_FileBrowser/en|FileBrowser]] menu (for easy SSH setup)
* Improvement: Bundled python3 installer updated to version 3.13.14
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed the [[Number_API_Functions|Number]] stack (see also in [[Numeric_Limits/en| Numeric Limits]]):
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. and type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan). Now all test cases produce a result within the precision limits of their type
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]]
* UI: '''Ctrl-Return''' now accepts the default action in every modal dialog — both the modern SimpleDialog-based ones (check-in log message, search dialogs, ...) and old-style DialogBox-based ones (EnterBox, OptionBox, InfoBox, ...). Unlike plain Return, Ctrl-Return submits the dialog even when the focus is on a multi-line text editor (which normally keeps Return as a newline), so there is no need to tab off the editor first.
* UI: Transcript (the console) always appends text at end.
* UI: Transcript does not scroll to end on incoming text while moving the scrollbar
* Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
* Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
* Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Performance: speedup of cryptographic algorithms (affects key generation and other)
* Performance: tuned loading of stored ets/elf files (30-40% speedup)
* Performance: further speedup when loading test-result archives that embed large execution logs — typical load is roughly a third faster again

Lizenzserver expecco ALM

2026-07-29T09:17:10Z

Sv: /* Native TLS-Verschlüsselung */

==Übersicht==

Der expecco Lizenzserver dient der zentralen Verwaltung von expecco Lizenzen. Durch den Lizenzserver kann expecco auf verschiedenen Rechnern (sowohl Entwicklungs- als auch reine Testausführungsrechner) ohne Dongle und lokale Lizenzdatei auf allen erreichbaren Rechnern im Netz installiert und ausgeführt werden.

Lizenzen werden dabei von den expecco-Rechnern vom Lizenzserver angefordert, im Lizenzserver reserviert,
und nach der Sitzung bzw. Testlauf wieder zurückgegeben. Damit können mehr Nutzer (allerdings nicht gleichzeitig) mit expecco arbeiten als Lizenzen erworben wurden.

Lizenzen sind kryptographisch gesicherte Dateien, welche nur in Verbindung mit einem von eXept gelieferten Lizenzserver-Dongle gelesen bzw. genutzt werden können. Lizenzen sind Dongle-spezifisch. Es ist also nicht notwendig, Maßnahmen zum Schutz vor Diebstahl oder Kopieren von Lizenzdateien zu ergreifen. Allerdings ist ein Verlust des Dongles aus nahe liegenden Gründen zu vermeiden.

{{SEITENTITEL:Lizenzservice Installation}}

== Voraussetzungen ==
Wir empfehlen, expecco ALM auf einem durchgehend verfügbaren Server mit Windows Server 2012 / Windows 10 oder höher zu installieren. Die Installation auf anderen Betriebssystemen (wie z.B. Linux) ist auch möglich. Ebenso ist die Installation in einer Cloud möglich, dort ist der Betrieb ohne nur mit Node-Locked Lizenzdatei ohne Dongle möglich.

Damit expecco ALM flüssig arbeiten kann, werden folgende Hardware-Anforderungen an den Server gestellt:

* ein "dezidierter" Prozessor mit mindestens 2 GHz
* mindestens 1 GB Arbeitsspeicher (ausschließlich für expecco ALM)
* mindestens 10 GB Festplattenspeicher (je nach Größe der Daten die expecco ALM verwalten soll)

Stellen Sie sicher, dass dieser Server für alle Clients erreichbar ist. Clients sind alle Rechner der expecco ALM Benutzer, Rechner die expecco ALM zur Testausführung dienen und Rechner mit "Floating" lizenziertem expecco. Bei Problemen bezüglich der Erreichbarkeit wenden Sie sich bitte an Ihren Netzwerkadministrator.

== Installation ==

Bitte halten Sie Ihre Lizenzdatei und ggfs. den Dongle für die Installation von expecco ALM bereit. 
Für die Installation in der Cloud benötigen Sie keinen Dongle; wir liefern dann eine Lizenzdatei, die an die MAC-Adresse des Servers gebunden ist. Falls sich der Server und damit dessen MAC-Adresse ändert, erhalten Sie eine neue angepasste Lizenzdatei von uns.

Ihre Lizenzdatei und eine Verknüpfung zum aktuellen expecco ALM Setup haben wir Ihnen per E-Mail zu kommen lassen. Der Installer hat folgenden Namen "expecco ALM 24.2.0 Setup.exe", wobei die Versionsnummer abweichen kann. Den Dongle haben wir per Post an Sie versendet (es sei denn Sie evaluieren expecco ALM oder nutzen die Cloud Variante mit der MAC-Adressen-Bindung).

Gehen Sie bitte wie folgt vor:
* Laden Sie den expecco ALM Installer auf dem Server, auf dem expecco ALM künftig laufen soll, herunter
* Legen Sie Ihre Lizenzdatei ebenfalls auf dem Server ab
* Verbinden Sie Ihren Dongle mit dem Server (Wenn Sie expecco ALM evaluieren oder die Cloud Variante mit der MAC-Adressen-Bindung nutzen, überspringen Sie diesen Schritt)
* Führen Sie den expecco ALM Installer ("expecco ALM ?.?.?.? Setup.exe" bzw. unter Linux "expecco ALM ?.?.?.? Setup.package") aus

Für Linux werden zusätzliche Pakete der Linux-Distribution benötigt. Diese sind [[Installation#Installation_von_expecco_auf_Linux|hier]] aufgeführt.

Nachdem der Installer erfolgreich ausgeführt wurde, läuft expecco ALM bereits als Service. Auf Ihrem Desktop wurde eine Verknüpfung zu expecco ALM angelegt. Es wurde auch ein Ordner für expecco ALM in Ihrem Startmenü erstellt. Dort können Sie unter "Konfiguration" den Port ändern (Standard ist Port 8081) oder über die "Logdatei" eventuelle Probleme feststellen.

[[Datei:InstallAlmLicense.png|mini|Anhang 1]]
Über die Verknüpfung auf Ihrem Desktop lässt sich expecco ALM mit Ihrem Standardbrowser öffnen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei (die Sie bereits auf dem Server abgelegt haben) auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen. Wenn bereits eine gültige Lizenz installiert ist, wird stattdessen die Anmeldeseite angezeigt. Falls es sich bei Ihnen um eine Erstinstallation handelt, können Sie sich mit Anmeldenamen "admin" und Kennwort "admin" anmelden.

Falls eine leere Seite oder eine Fehlerseite angezeigt wird, probieren Sie einen anderen Port aus und/oder schauen Sie in der Logdatei nach Fehlermeldungen.

== SSL-Verschlüsselung / Proxy-Server ==
Ab Version 26.1 unterstützen expecco ALM (bzw. AIDYMO) TLS/HTTPS direkt – ein vorgeschalteter Proxy-Server ist dafür nicht mehr zwingend erforderlich. Für den Betrieb in einer bestehenden Umgebung, in der sich mehrere Dienste einen Port teilen, wird der Proxy-Weg weiterhin unterstützt (siehe unten).

=== Native TLS-Verschlüsselung ===
Um HTTPS direkt zu aktivieren, legen Sie das Server-Zertifikat und den privaten Schlüssel im PEM-Format in das Datenverzeichnis des Servers. Der Server erkennt die Dateien beim Start automatisch und bedient denselben Port dann per HTTPS statt HTTP. Es sind keine weiteren Einstellungen nötig.

Erkannte Dateinamen (die erste vorhandene Kombination gewinnt):
{| class="wikitable"
! Variante !! Dateien
|-
| Kombiniert || <code>server.pem</code> (Zertifikat + privater Schlüssel in einer Datei)
|-
| Let's Encrypt || <code>fullchain.pem</code> + <code>privkey.pem</code>
|-
| Klassisch getrennt || <code>cert.pem</code> + <code>key.pem</code>
|}

Ablageort der PEM-Dateien:
* Windows (64-Bit): <code>C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM</code>
* oder das mit der Kommandozeilenoption <code>--workDir <Verzeichnis></code> angegebene Verzeichnis

Der Server-Hostname wird automatisch aus dem Zertifikat übernommen (erster SAN-dNSName, ersatzweise der CN). Falls mehrere Zertifikate bzw. ein Wildcard-Zertifikat in der Zertifikatsdatei enthalten sind, kann in expeccoALM ein beliebiger Rechnername konfiguriert werden, der von den Zertifikaten unterstützt wird.

Sind keine dieser Dateien vorhanden, startet der Server wie bisher unverschlüsselt (HTTP).

=== Eigene IP-Adresse bei Port-Konflikt ===
Läuft auf demselben Rechner bereits ein anderer Webserver auf dem gleichen Port (z.B. ein Apache auf Port 443), so muss expecco ALM (bzw. AIDYMO) an eine eigene, separate IP-Adresse gebunden werden – zwei Dienste können sich denselben Port auf derselben IP-Adresse nicht teilen.

Binden Sie den Server dazu mit der Kommandozeilenoption <code>--listen</code> an eine bestimmte Adresse:
expeccoALM --listen 192.168.1.50 --port 443
oder alternativ:
AIDYMO --listen 192.168.1.50 --port 443

<code>--listen</code> kann mehrfach angegeben werden und akzeptiert IPv4- und IPv6-Adressen (z.B. <code>192.168.1.50</code>, <code>::1</code>, <code>[::1]:443</code>). Ohne eingebettete Portangabe gilt <code>--port</code> bzw. der Standardport. Ohne <code>--listen</code> lauscht der Server auf allen Adressen des Rechners (INADDR_ANY); das ist nur dann ein Problem, wenn der Port bereits von einem anderen Dienst belegt ist.

=== Proxy-Server (bestehende Umgebung, gemeinsamer Port ohne eigene IP-Adresse) ===
Wird expecco ALM (bzw. AIDYMO) in eine bestehende Umgebung integriert, in der bereits ein Webserver den Port 443 belegt und ''keine'' separate IP-Adresse zur Verfügung steht, kann der Port nicht direkt geteilt werden. In diesem Fall betreiben Sie expecco ALM weiterhin auf einem internen Port und stellen einen vorgeschalteten Proxy-Server (z.B. Apache) davor, der die TLS-Verschlüsselung übernimmt. Da sich nicht mehrere Prozesse gleichzeitig an denselben Port (443) auf derselben IP-Adresse binden können, ist dieser Weg hier erforderlich.

Eine Apache2 VirtualHost-Konfiguration würde entsprechend so aussehen (angenommen expecco ALM läuft mit Port 8465 - erforderliche Anpassung für ihre Konfiguration fett):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

Die SSL-Parameter mit dem Pfaden zu Ihren Zertifkaten uns Schlüsseln würden in diesem Konfigurations-Beispiel in der Apache-globalen Datei /etc/letsencrypt/ssl-xyz.de.conf liegen.

== Hinweise zur Lizenzierung ==
Wenn Sie expecco ALM erworben haben, erhalten Sie einen Dongle und eine Lizenzdatei. Falls Sie expecco ALM evaluieren, erhalten Sie ausschließlich die Lizenzdatei. Die Lizenzdatei beinhaltet eine für Sie individuelle expecco ALM Lizenz. So sind zum Beispiel: Der Name Ihrer Firma, für Sie freigeschaltete Module oder die Gültigkeitsdauer in der Lizenz hinterlegt. Der Dongle muss (insofern Sie expecco ALM erworben haben) ständig mit dem Server, auf dem expecco ALM ausgeführt wird, verbunden sein. Falls Sie den Dongle während des Betriebs abziehen, wird expecco ALM seinen Dienst einstellen.

== Lizenz wechseln ==
[[Datei:ChangeAlmLicense.png|mini|Anhang 2]]
Falls Sie eine aktuelle expecco ALM Version haben, können Sie eine neue Lizenzdatei "expecco ALM Lizenz *.lic" über das Webinterface von expecco ALM einspielen. Betrachten Sie dazu den angehängten Screenshot (Anhang 2).

Fall Sie eine ältere expecco ALM Version haben, müssen Sie folgendermaßen vorgehen:
 - Da Sie expecco ALM später neustarten müssen, tätigen Sie entsprechende Vorsorgemaßnahmen (Bspw. Benutzer abmelden, Datenbank sichern usw.)
 - Melden Sie sich auf dem Computer, der expecco ALM betreibt an
 - Begeben Sie sich in folgendes Verzeichnis "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM" oder falls es sich um ein 32Bit Betriebssystem handelt "C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM" und löschen Sie die Datei "expecco_ALM.lic"
 - Starten Sie den expecco ALM Service über den Windows-Service-Manager neu oder beenden Sie über den Windows-Task-Manager den Prozess "expecco_ALM.exe", in letzterem Fall wird der Windows-Service-Manager expecco ALM automatisch neustarten.
 - Nun können Sie das expecco ALM Webinterface aufrufen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei. auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen.

== Einbringen von expecco Floating-Lizenzen ==
Der Lizenzservice von expecco ALM vergibt verfügbare expecco Floating-Lizenzen aus einem bestimmten Pool. 
In diesen zunächst leeren Pool können von eXept erworbene expecco Floating-Lizenzen eingebracht werden.
 
Diese expecco Floating-Lizenzen erhalten Sie als Lizenzdatei(en) üblicherweise per E-Mail. 
Eine Lizenzdatei kann eine oder mehrere expecco Floating-Lizenzen auch für verschiedene Komponenten (Basissystem, Plugins und Erweiterungen) enthalten. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.
 
expecco Floating-Lizenzen werden immer spezifisch für eine expecco ALM Lizenz erstellt und sind nur mit dieser und deren Dongle nutzbar. 
Es ist also nicht notwendig solche Lizenzdateien unter Verschluss zu halten oder über eine sichere Verbindung auszutauschen. 
Allerdings sollten Sie den Dongle sicher aufbewahren bzw. Diebstahl vorbeugen.
 
Zur Einbringen einer expecco Floating-Lizenz öffnen Sie expecco ALM und melden Sie sich an. 
Jetzt navigieren Sie über die obere Hauptnavigationsleiste zum "Lizenzservice" Modul.
 
Sie befinden sich nun im Lizenzservice und Ihnen wird die Liste der installierten expecco Floating-Lizenzen angezeigt. 
Wechseln Sie zur Registerkarte "expecco Lizenzdateien". 
Navigieren Sie mithilfe des Navigationsmenüs auf der linken Seite zu "Hochladen/Upload". 
Hier können Sie nun durch ein einfaches Hochladen Ihrer expecco Floating-Lizenzen selbige in den Pool einbringen. 
In der zuvor genannte Liste werden nun die eben hochgeladenen expecco Floating-Lizenzen anzeigt. 
Diese sind von nun an auch von entfernten expecco Clients abrufbar. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.

== Lizenz Übersicht ==
Welche einzelnen expecco Floating-Lizenzen verfügbar oder vergeben sind, 
erfahren Sie indem Sie zur Registerkarte "expecco Lizenzen" wechseln. 
Insbesondere ist hieraus ersichtlich, welcher Rechner/Benutzer welche expecco Floating-Lizenz aktuell nutzt. 
Dies ist beispielsweise sinnvoll, wenn ein expecco Client seine Sitzung versehentlich nicht beendet hat, 
und andere Nutzer eine entsprechende Lizenz benötigen.

Lizenzserver expecco ALM

2026-07-29T09:11:55Z

Sv: /* Voraussetzungen */

==Übersicht==

Der expecco Lizenzserver dient der zentralen Verwaltung von expecco Lizenzen. Durch den Lizenzserver kann expecco auf verschiedenen Rechnern (sowohl Entwicklungs- als auch reine Testausführungsrechner) ohne Dongle und lokale Lizenzdatei auf allen erreichbaren Rechnern im Netz installiert und ausgeführt werden.

Lizenzen werden dabei von den expecco-Rechnern vom Lizenzserver angefordert, im Lizenzserver reserviert,
und nach der Sitzung bzw. Testlauf wieder zurückgegeben. Damit können mehr Nutzer (allerdings nicht gleichzeitig) mit expecco arbeiten als Lizenzen erworben wurden.

Lizenzen sind kryptographisch gesicherte Dateien, welche nur in Verbindung mit einem von eXept gelieferten Lizenzserver-Dongle gelesen bzw. genutzt werden können. Lizenzen sind Dongle-spezifisch. Es ist also nicht notwendig, Maßnahmen zum Schutz vor Diebstahl oder Kopieren von Lizenzdateien zu ergreifen. Allerdings ist ein Verlust des Dongles aus nahe liegenden Gründen zu vermeiden.

{{SEITENTITEL:Lizenzservice Installation}}

== Voraussetzungen ==
Wir empfehlen, expecco ALM auf einem durchgehend verfügbaren Server mit Windows Server 2012 / Windows 10 oder höher zu installieren. Die Installation auf anderen Betriebssystemen (wie z.B. Linux) ist auch möglich. Ebenso ist die Installation in einer Cloud möglich, dort ist der Betrieb ohne nur mit Node-Locked Lizenzdatei ohne Dongle möglich.

Damit expecco ALM flüssig arbeiten kann, werden folgende Hardware-Anforderungen an den Server gestellt:

* ein "dezidierter" Prozessor mit mindestens 2 GHz
* mindestens 1 GB Arbeitsspeicher (ausschließlich für expecco ALM)
* mindestens 10 GB Festplattenspeicher (je nach Größe der Daten die expecco ALM verwalten soll)

Stellen Sie sicher, dass dieser Server für alle Clients erreichbar ist. Clients sind alle Rechner der expecco ALM Benutzer, Rechner die expecco ALM zur Testausführung dienen und Rechner mit "Floating" lizenziertem expecco. Bei Problemen bezüglich der Erreichbarkeit wenden Sie sich bitte an Ihren Netzwerkadministrator.

== Installation ==

Bitte halten Sie Ihre Lizenzdatei und ggfs. den Dongle für die Installation von expecco ALM bereit. 
Für die Installation in der Cloud benötigen Sie keinen Dongle; wir liefern dann eine Lizenzdatei, die an die MAC-Adresse des Servers gebunden ist. Falls sich der Server und damit dessen MAC-Adresse ändert, erhalten Sie eine neue angepasste Lizenzdatei von uns.

Ihre Lizenzdatei und eine Verknüpfung zum aktuellen expecco ALM Setup haben wir Ihnen per E-Mail zu kommen lassen. Der Installer hat folgenden Namen "expecco ALM 24.2.0 Setup.exe", wobei die Versionsnummer abweichen kann. Den Dongle haben wir per Post an Sie versendet (es sei denn Sie evaluieren expecco ALM oder nutzen die Cloud Variante mit der MAC-Adressen-Bindung).

Gehen Sie bitte wie folgt vor:
* Laden Sie den expecco ALM Installer auf dem Server, auf dem expecco ALM künftig laufen soll, herunter
* Legen Sie Ihre Lizenzdatei ebenfalls auf dem Server ab
* Verbinden Sie Ihren Dongle mit dem Server (Wenn Sie expecco ALM evaluieren oder die Cloud Variante mit der MAC-Adressen-Bindung nutzen, überspringen Sie diesen Schritt)
* Führen Sie den expecco ALM Installer ("expecco ALM ?.?.?.? Setup.exe" bzw. unter Linux "expecco ALM ?.?.?.? Setup.package") aus

Für Linux werden zusätzliche Pakete der Linux-Distribution benötigt. Diese sind [[Installation#Installation_von_expecco_auf_Linux|hier]] aufgeführt.

Nachdem der Installer erfolgreich ausgeführt wurde, läuft expecco ALM bereits als Service. Auf Ihrem Desktop wurde eine Verknüpfung zu expecco ALM angelegt. Es wurde auch ein Ordner für expecco ALM in Ihrem Startmenü erstellt. Dort können Sie unter "Konfiguration" den Port ändern (Standard ist Port 8081) oder über die "Logdatei" eventuelle Probleme feststellen.

[[Datei:InstallAlmLicense.png|mini|Anhang 1]]
Über die Verknüpfung auf Ihrem Desktop lässt sich expecco ALM mit Ihrem Standardbrowser öffnen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei (die Sie bereits auf dem Server abgelegt haben) auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen. Wenn bereits eine gültige Lizenz installiert ist, wird stattdessen die Anmeldeseite angezeigt. Falls es sich bei Ihnen um eine Erstinstallation handelt, können Sie sich mit Anmeldenamen "admin" und Kennwort "admin" anmelden.

Falls eine leere Seite oder eine Fehlerseite angezeigt wird, probieren Sie einen anderen Port aus und/oder schauen Sie in der Logdatei nach Fehlermeldungen.

== SSL-Verschlüsselung / Proxy-Server ==
Ab Version 26.1 unterstützen expecco ALM (bzw. AIDYMO) TLS/HTTPS direkt – ein vorgeschalteter Proxy-Server ist dafür nicht mehr zwingend erforderlich. Für den Betrieb in einer bestehenden Umgebung, in der sich mehrere Dienste einen Port teilen, wird der Proxy-Weg weiterhin unterstützt (siehe unten).

=== Native TLS-Verschlüsselung ===
Um HTTPS direkt zu aktivieren, legen Sie das Server-Zertifikat und den privaten Schlüssel im PEM-Format in das Datenverzeichnis des Servers. Der Server erkennt die Dateien beim Start automatisch und bedient denselben Port dann per HTTPS statt HTTP. Es sind keine weiteren Einstellungen nötig.

Erkannte Dateinamen (die erste vorhandene Kombination gewinnt):
{| class="wikitable"
! Variante !! Dateien
|-
| Kombiniert || <code>server.pem</code> (Zertifikat + privater Schlüssel in einer Datei)
|-
| Let's Encrypt || <code>fullchain.pem</code> + <code>privkey.pem</code>
|-
| Klassisch getrennt || <code>cert.pem</code> + <code>key.pem</code>
|}

Ablageort der PEM-Dateien:
* Windows (64-Bit): <code>C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM</code>
* oder das mit der Kommandozeilenoption <code>--workDir <Verzeichnis></code> angegebene Verzeichnis

Sind keine dieser Dateien vorhanden, startet der Server wie bisher unverschlüsselt (HTTP). Der Server-Hostname wird automatisch aus dem Zertifikat übernommen (erster SAN-dNSName, ersatzweise der CN).

=== Eigene IP-Adresse bei Port-Konflikt ===
Läuft auf demselben Rechner bereits ein anderer Webserver auf dem gleichen Port (z.B. ein Apache auf Port 443), so muss expecco ALM (bzw. AIDYMO) an eine eigene, separate IP-Adresse gebunden werden – zwei Dienste können sich denselben Port auf derselben IP-Adresse nicht teilen.

Binden Sie den Server dazu mit der Kommandozeilenoption <code>--listen</code> an eine bestimmte Adresse:
expeccoALM --listen 192.168.1.50 --port 443
oder alternativ:
AIDYMO --listen 192.168.1.50 --port 443

<code>--listen</code> kann mehrfach angegeben werden und akzeptiert IPv4- und IPv6-Adressen (z.B. <code>192.168.1.50</code>, <code>::1</code>, <code>[::1]:443</code>). Ohne eingebettete Portangabe gilt <code>--port</code> bzw. der Standardport. Ohne <code>--listen</code> lauscht der Server auf allen Adressen des Rechners (INADDR_ANY); das ist nur dann ein Problem, wenn der Port bereits von einem anderen Dienst belegt ist.

=== Proxy-Server (bestehende Umgebung, gemeinsamer Port ohne eigene IP-Adresse) ===
Wird expecco ALM (bzw. AIDYMO) in eine bestehende Umgebung integriert, in der bereits ein Webserver den Port 443 belegt und ''keine'' separate IP-Adresse zur Verfügung steht, kann der Port nicht direkt geteilt werden. In diesem Fall betreiben Sie expecco ALM weiterhin auf einem internen Port und stellen einen vorgeschalteten Proxy-Server (z.B. Apache) davor, der die TLS-Verschlüsselung übernimmt. Da sich nicht mehrere Prozesse gleichzeitig an denselben Port (443) auf derselben IP-Adresse binden können, ist dieser Weg hier erforderlich.

Eine Apache2 VirtualHost-Konfiguration würde entsprechend so aussehen (angenommen expecco ALM läuft mit Port 8465 - erforderliche Anpassung für ihre Konfiguration fett):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

Die SSL-Parameter mit dem Pfaden zu Ihren Zertifkaten uns Schlüsseln würden in diesem Konfigurations-Beispiel in der Apache-globalen Datei /etc/letsencrypt/ssl-xyz.de.conf liegen.

== Hinweise zur Lizenzierung ==
Wenn Sie expecco ALM erworben haben, erhalten Sie einen Dongle und eine Lizenzdatei. Falls Sie expecco ALM evaluieren, erhalten Sie ausschließlich die Lizenzdatei. Die Lizenzdatei beinhaltet eine für Sie individuelle expecco ALM Lizenz. So sind zum Beispiel: Der Name Ihrer Firma, für Sie freigeschaltete Module oder die Gültigkeitsdauer in der Lizenz hinterlegt. Der Dongle muss (insofern Sie expecco ALM erworben haben) ständig mit dem Server, auf dem expecco ALM ausgeführt wird, verbunden sein. Falls Sie den Dongle während des Betriebs abziehen, wird expecco ALM seinen Dienst einstellen.

== Lizenz wechseln ==
[[Datei:ChangeAlmLicense.png|mini|Anhang 2]]
Falls Sie eine aktuelle expecco ALM Version haben, können Sie eine neue Lizenzdatei "expecco ALM Lizenz *.lic" über das Webinterface von expecco ALM einspielen. Betrachten Sie dazu den angehängten Screenshot (Anhang 2).

Fall Sie eine ältere expecco ALM Version haben, müssen Sie folgendermaßen vorgehen:
 - Da Sie expecco ALM später neustarten müssen, tätigen Sie entsprechende Vorsorgemaßnahmen (Bspw. Benutzer abmelden, Datenbank sichern usw.)
 - Melden Sie sich auf dem Computer, der expecco ALM betreibt an
 - Begeben Sie sich in folgendes Verzeichnis "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM" oder falls es sich um ein 32Bit Betriebssystem handelt "C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM" und löschen Sie die Datei "expecco_ALM.lic"
 - Starten Sie den expecco ALM Service über den Windows-Service-Manager neu oder beenden Sie über den Windows-Task-Manager den Prozess "expecco_ALM.exe", in letzterem Fall wird der Windows-Service-Manager expecco ALM automatisch neustarten.
 - Nun können Sie das expecco ALM Webinterface aufrufen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei. auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen.

== Einbringen von expecco Floating-Lizenzen ==
Der Lizenzservice von expecco ALM vergibt verfügbare expecco Floating-Lizenzen aus einem bestimmten Pool. 
In diesen zunächst leeren Pool können von eXept erworbene expecco Floating-Lizenzen eingebracht werden.
 
Diese expecco Floating-Lizenzen erhalten Sie als Lizenzdatei(en) üblicherweise per E-Mail. 
Eine Lizenzdatei kann eine oder mehrere expecco Floating-Lizenzen auch für verschiedene Komponenten (Basissystem, Plugins und Erweiterungen) enthalten. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.
 
expecco Floating-Lizenzen werden immer spezifisch für eine expecco ALM Lizenz erstellt und sind nur mit dieser und deren Dongle nutzbar. 
Es ist also nicht notwendig solche Lizenzdateien unter Verschluss zu halten oder über eine sichere Verbindung auszutauschen. 
Allerdings sollten Sie den Dongle sicher aufbewahren bzw. Diebstahl vorbeugen.
 
Zur Einbringen einer expecco Floating-Lizenz öffnen Sie expecco ALM und melden Sie sich an. 
Jetzt navigieren Sie über die obere Hauptnavigationsleiste zum "Lizenzservice" Modul.
 
Sie befinden sich nun im Lizenzservice und Ihnen wird die Liste der installierten expecco Floating-Lizenzen angezeigt. 
Wechseln Sie zur Registerkarte "expecco Lizenzdateien". 
Navigieren Sie mithilfe des Navigationsmenüs auf der linken Seite zu "Hochladen/Upload". 
Hier können Sie nun durch ein einfaches Hochladen Ihrer expecco Floating-Lizenzen selbige in den Pool einbringen. 
In der zuvor genannte Liste werden nun die eben hochgeladenen expecco Floating-Lizenzen anzeigt. 
Diese sind von nun an auch von entfernten expecco Clients abrufbar. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.

== Lizenz Übersicht ==
Welche einzelnen expecco Floating-Lizenzen verfügbar oder vergeben sind, 
erfahren Sie indem Sie zur Registerkarte "expecco Lizenzen" wechseln. 
Insbesondere ist hieraus ersichtlich, welcher Rechner/Benutzer welche expecco Floating-Lizenz aktuell nutzt. 
Dies ist beispielsweise sinnvoll, wenn ein expecco Client seine Sitzung versehentlich nicht beendet hat, 
und andere Nutzer eine entsprechende Lizenz benötigen.

Lizenzserver expecco ALM/en

2026-07-29T08:32:54Z

Sv: Fix Linux install list: fold indented commands into bullets as <code> (was breaking the list into stray <pre> boxes)

==Overview==

The expecco license server is used for the central administration of expecco licenses. The license server allows expecco to be installed and executed on various computers (both development and pure test execution computers) without a dongle and local license file on all accessible computers in the network.

Licenses are requested by the expecco computers from the license server, reserved in the license server,
and returned after the session or test run. This means that more users can work with expecco (but not simultaneously) than the number of licenses purchased.

Licenses are cryptographically secured files that can only be read or used in conjunction with a license server dongle supplied by eXept. Licenses are dongle-specific. It is therefore not necessary to take measures to protect against theft or copying of license files. However, loss of the dongle should be avoided for obvious reasons.

{{SEITENTITEL:Lizenzservice Installation}}

== Requirements ==
We recommend installing expecco ALM on a continuously available server with Windows Server 2012 / Windows 10 or higher. Installation on other operating systems (e.g. Linux) would also be possible if required.
It is also possible to install the program in a cloud, where it can be operated without a dongle.

To ensure that expecco ALM can run smoothly, the following hardware requirements apply to the server:
 - a “dedicated” processor with at least 2 GHz
 - at least 1 GB of RAM (exclusively for expecco ALM)
 - at least 10 GB hard disk space (depending on the size of the data that expecco ALM is to manage)

Make sure that this server is accessible to all clients. Clients are all computers of expecco ALM users, computers that are used to run expecco ALM tests and computers with “floating” licensed expecco. If you have any problems with accessibility, please contact your network administrator.

== Installation ==

Please have your license file and dongle ready for the installation of expecco ALM. 
Alternatetivly, for the installation in the cloud without dongle, we provide a license file node-locked to a MAC address.
We have sent you your license file and a link to the current expecco ALM setup by e-mail.

=== Windows ===

The installer has the following name: “expecco ALM 25.1.0.1 Setup.exe”, although the version number may differ. We have sent you your dongle by mail (unless you are evaluating expecco ALM or using the cloud version with the Mac address binding).

Please proceed as follows:
* Download the expecco ALM installer to the server on which expecco ALM is to run in the future
* Place your license file on the server as well
* Connect your dongle to the server (if you are evaluating expecco ALM or using the cloud version with the Mac address binding, skip this step)
* Run the expecco ALM installer (“expecco ALM?..?..?.. Setup.exe”)

Once the installer has been successfully executed, expecco ALM is already running as a service. A shortcut to expecco ALM has been created on your desktop. A folder for expecco ALM has also been created in your start menu. There you can change the port under “Configuration” (the default is port 8081) or use the “Logfile” to identify any problems.

[[File:InstallAlmLicense.png|mini|Attachment 1]]
You can open expecco ALM with your default browser via the shortcut on your desktop. A page for installing your expecco ALM license will be displayed (Appendix 1). You can select your license file (which you have already stored on the server) via “Install license file”. After expecco ALM has accepted your license file, you can remove it. If a valid license is already installed, the login page will be displayed instead. If this is your first installation, you can log in with the username “admin” and password “admin”.

If you get a blank page or an error page, try a different port and/or check the log file for error messages.

=== Linux ===

For '''Redhat''' resp. '''Oracle Linux''' you need the linux packages: libXinerama libXft libXrandr unixODBC libusb libusbx bzip2 ncurses gettext isomd5sum
Install them with
dnf install libXinerama libXft libXrandr unixODBC libusb libusbx bzip2 ncurses gettext isomd5sum

For '''Ubuntu''' resp. '''Debian'''
Install the required packages:
apt-get update
apt-get install libxinerama1 libxft2 libxrandr2 unixodbc odbcinst libusb-1.0.0 libusb-0.1-4 coreutils \
bzip2 libglib2.0-0 software-properties-common

The installer has the following name: “expeccoALM-25.1.0.2989.package”, although the version number may differ. We have sent you your dongle by mail (unless you are evaluating expecco ALM or using the cloud version with the Mac address binding).

Please proceed as follows:

* Download the expecco ALM installer to the server on which expecco ALM is to run in the future
* Dowload the autopackage software from [https://download.exept.de/download/autopackage.tar.bz2 https://download.exept.de/download/autopackage.tar.bz2] to the same directory
* Place your license file on the server resp. the client running the browser.
* Connect your dongle to the server (if you are evaluating expecco ALM or using the cloud version with the Mac address binding, skip this step)
* Run the expecco ALM installer: <code>bash ./expeccoALM-25.1.0.2989.package</code>
* Choose a unused TCP port number. You use this port number to connect to the expeccoALM web page and fetch your expecco licenses. The default port number is 8659.
* For automatic start with ''systemd'' use /opt/expecco_ALM/expeccoALM.service as a template. Change the ''USER'' parameter to the linux user the service should run under. Change the ''port'' option parameter to the port number.
* Enable the expecco ALM service with: <code>systemctl enable ./expeccoALM.service</code>
* expecco ALM will be started automatically when the server is booted. When you don't want to reboot the server now, start the expecco ALM service with: <code>systemctl start expeccoALM</code>
* Alternatevely, when you don't want to use autoa-start with systemd you can start expecco ALM manually: <code>/opt/expecco_ALM/bin/expecco_ALM -p <port number></code>

You can open expecco ALM with your default browser by connecting to http://<server>:<port>. A page for installing your expecco ALM license will be displayed (Appendix 1). You can select your license file (which you have already stored on the server) via “Install license file”. After expecco ALM has accepted your license file, you can remove it. If a valid license is already installed, the login page will be displayed instead. If this is your first installation, you can log in with the username “admin” and password “admin”.

If you get a blank page or an error page, try a different port and/or check the log file for error messages.

== SSL encryption / proxy server ==
Starting with version 26.1, expecco ALM (or AIDYMO) supports TLS/HTTPS natively – an upstream proxy server is no longer strictly required for this. For running in an existing setup where several services share a port, the proxy route remains supported (see below).

=== Native TLS encryption ===
To enable HTTPS directly, place the server certificate and private key in PEM format into the server's data directory. The server detects these files automatically at startup and then serves the same port over HTTPS instead of HTTP. No further configuration is needed.

Recognised file names (the first matching combination wins):
{| class="wikitable"
! Variant !! Files
|-
| Combined || <code>server.pem</code> (certificate + private key in one file)
|-
| Let's Encrypt || <code>fullchain.pem</code> + <code>privkey.pem</code>
|-
| Classic split || <code>cert.pem</code> + <code>key.pem</code>
|}

Where to place the PEM files:
* Windows (64-bit): <code>C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM</code>
* or the directory given with the command-line option <code>--workDir <directory></code>

If none of these files is present, the server starts unencrypted (HTTP) as before. The server host name is taken automatically from the certificate (first SAN dNSName, otherwise the CN).

=== Separate IP address on a port conflict ===
If another web server is already running on the same machine and the same port (e.g. an Apache on port 443), expecco ALM (or AIDYMO) must be bound to its own, separate IP address – two services cannot share the same port on the same IP address.

Bind the server to a specific address with the <code>--listen</code> command-line option:
expeccoALM --listen 192.168.1.50 --port 443
or alternatively:
AIDYMO --listen 192.168.1.50 --port 443

<code>--listen</code> may be given more than once and accepts IPv4 and IPv6 addresses (e.g. <code>192.168.1.50</code>, <code>::1</code>, <code>[::1]:443</code>). Without an embedded port, <code>--port</code> (or the default port) applies. Without <code>--listen</code> the server listens on all addresses of the machine (INADDR_ANY); this is only a problem when the port is already in use by another service.

=== Proxy server (existing setup, shared port without a separate IP address) ===
When expecco ALM (or AIDYMO) is integrated into an existing setup where a web server already occupies port 443 and ''no'' separate IP address is available, the port cannot be shared directly. In this case keep running expecco ALM on an internal port and put an upstream proxy server (e.g. Apache) in front of it to handle the TLS encryption. As multiple processes cannot bind to the same port (443) on the same IP address at the same time, this route is required here.

An Apache2 VirtualHost configuration would look like this (assuming expecco ALM is running on port 8465 - the necessary changes for your configuration are in bold):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

In this configuration example, the SSL parameters with the paths to your certificates and keys would be located in the Apache global file /etc/letsencrypt/ssl-xyz.de.conf.

== Notes on licensing ==
If you have purchased expecco ALM, you will receive a dongle and a license file. If you are evaluating expecco ALM, you will only receive the license file. The license file contains an individual expecco ALM license for you. For example, the name of your company, the modules activated for you or the validity period are stored in the license. The dongle (if you have purchased expecco ALM) must be permanently connected to the server on which expecco ALM is running. If you disconnect the dongle during operation, expecco ALM will stop working.

== Change license ==
[[File:ChangeAlmLicense.png|mini|Attachment 2]]
If you have a current expecco ALM version, you can import a new license file “expecco ALM license *.lic” via the expecco ALM web interface. Please refer to the attached screenshot (Appendix 2).

If you have an older version of expecco ALM, you must proceed as follows:
 - Since you will have to restart expecco ALM later, take the appropriate precautions (e.g. log off users, back up the database, etc.)
 - Log on to the computer running expecco ALM
 - Go to the following directory “C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM” or, if you are using a 32-bit operating system, “C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM” and delete the file “expecco_ALM.lic”
 - Restart the expecco ALM service via the Windows Service Manager or end the “expecco_ALM.exe” process via the Windows Task Manager. In the latter case, the Windows Service Manager will automatically restart expecco ALM.
 - Now you can access the expecco ALM web interface. A page for installing your expecco ALM license will be displayed (Appendix 1). You can select your license file via “Install license file”. After expecco ALM has accepted your license file, you can remove it.

== Importing expecco floating licenses ==
The license service of expecco ALM allocates available expecco floating licenses from a certain pool. 
Expecco floating licenses purchased from eXept can be added to this initially empty pool.
 
You will receive these expecco floating licenses as license file(s) usually by e-mail. 
A license file can contain one or more expecco floating licenses, even for different components (basic system, plug-ins and extensions). 
You can also purchase additional expecco floating licenses at any time and add them to the pool.
 
expecco floating licenses are always created specifically for an expecco ALM license and can only be used with this license and its dongle. 
It is therefore not necessary to keep such license files under lock and key or to exchange them via a secure connection. 
However, you should keep the dongle in a safe place and prevent theft.
 
To install an expecco floating license, open expecco ALM and log in. 
Now navigate to the “License Service” module using the top main navigation bar.
 
You are now in the license service and the list of installed expecco floating licenses is displayed. 
Switch to the “expecco license files” tab.
Use the navigation menu on the left to navigate to “Upload”. 
Here you can now upload your expecco floating licenses to the pool by simply uploading them. 
The expecco floating licenses you have just uploaded will now be displayed in the list mentioned above. 
From now on, these can also be accessed by remote expecco clients. 
You can also purchase additional expecco floating licenses and add them to the pool at any time.

== License Overview ==
To find out which individual expecco floating licenses are available or assigned, 
by switching to the “expecco licenses” tab. 
In particular, it is possible to see which computer/user is currently using which expecco floating license. 
This is useful, for example, if an expecco client has accidentally not ended its session, 
and other users need a corresponding license.

Lizenzserver expecco ALM/en

2026-07-29T08:17:37Z

Sv: Native TLS/HTTPS documented (since 26.1): PEM drop-in, --listen for separate IP on port conflict; proxy kept for shared-port/no-separate-IP setups

==Overview==

The expecco license server is used for the central administration of expecco licenses. The license server allows expecco to be installed and executed on various computers (both development and pure test execution computers) without a dongle and local license file on all accessible computers in the network.

Licenses are requested by the expecco computers from the license server, reserved in the license server,
and returned after the session or test run. This means that more users can work with expecco (but not simultaneously) than the number of licenses purchased.

Licenses are cryptographically secured files that can only be read or used in conjunction with a license server dongle supplied by eXept. Licenses are dongle-specific. It is therefore not necessary to take measures to protect against theft or copying of license files. However, loss of the dongle should be avoided for obvious reasons.

{{SEITENTITEL:Lizenzservice Installation}}

== Requirements ==
We recommend installing expecco ALM on a continuously available server with Windows Server 2012 / Windows 10 or higher. Installation on other operating systems (e.g. Linux) would also be possible if required.
It is also possible to install the program in a cloud, where it can be operated without a dongle.

To ensure that expecco ALM can run smoothly, the following hardware requirements apply to the server:
 - a “dedicated” processor with at least 2 GHz
 - at least 1 GB of RAM (exclusively for expecco ALM)
 - at least 10 GB hard disk space (depending on the size of the data that expecco ALM is to manage)

Make sure that this server is accessible to all clients. Clients are all computers of expecco ALM users, computers that are used to run expecco ALM tests and computers with “floating” licensed expecco. If you have any problems with accessibility, please contact your network administrator.

== Installation ==

Please have your license file and dongle ready for the installation of expecco ALM. 
Alternatetivly, for the installation in the cloud without dongle, we provide a license file node-locked to a MAC address.
We have sent you your license file and a link to the current expecco ALM setup by e-mail.

=== Windows ===

The installer has the following name: “expecco ALM 25.1.0.1 Setup.exe”, although the version number may differ. We have sent you your dongle by mail (unless you are evaluating expecco ALM or using the cloud version with the Mac address binding).

Please proceed as follows:
* Download the expecco ALM installer to the server on which expecco ALM is to run in the future
* Place your license file on the server as well
* Connect your dongle to the server (if you are evaluating expecco ALM or using the cloud version with the Mac address binding, skip this step)
* Run the expecco ALM installer (“expecco ALM?..?..?.. Setup.exe”)

Once the installer has been successfully executed, expecco ALM is already running as a service. A shortcut to expecco ALM has been created on your desktop. A folder for expecco ALM has also been created in your start menu. There you can change the port under “Configuration” (the default is port 8081) or use the “Logfile” to identify any problems.

[[File:InstallAlmLicense.png|mini|Attachment 1]]
You can open expecco ALM with your default browser via the shortcut on your desktop. A page for installing your expecco ALM license will be displayed (Appendix 1). You can select your license file (which you have already stored on the server) via “Install license file”. After expecco ALM has accepted your license file, you can remove it. If a valid license is already installed, the login page will be displayed instead. If this is your first installation, you can log in with the username “admin” and password “admin”.

If you get a blank page or an error page, try a different port and/or check the log file for error messages.

=== Linux ===

For '''Redhat''' resp. '''Oracle Linux''' you need the linux packages: libXinerama libXft libXrandr unixODBC libusb libusbx bzip2 ncurses gettext isomd5sum
Install them with
dnf install libXinerama libXft libXrandr unixODBC libusb libusbx bzip2 ncurses gettext isomd5sum

For '''Ubuntu''' resp. '''Debian'''
Install the required packages:
apt-get update
apt-get install libxinerama1 libxft2 libxrandr2 unixodbc odbcinst libusb-1.0.0 libusb-0.1-4 coreutils \
bzip2 libglib2.0-0 software-properties-common

The installer has the following name: “expeccoALM-25.1.0.2989.package”, although the version number may differ. We have sent you your dongle by mail (unless you are evaluating expecco ALM or using the cloud version with the Mac address binding).

Please proceed as follows:

* Download the expecco ALM installer to the server on which expecco ALM is to run in the future
* Dowload the autopackage software from [https://download.exept.de/download/autopackage.tar.bz2 https://download.exept.de/download/autopackage.tar.bz2] to the same directory
* Place your license file on the server resp. the client running the browser.
* Connect your dongle to the server (if you are evaluating expecco ALM or using the cloud version with the Mac address binding, skip this step)
* Run the expecco ALM installer:
bash ./expeccoALM-25.1.0.2989.package
* Choose a unused TCP port number. You use this port number to connect to the expeccoALM web page and fetch your expecco licenses. The default port number is 8659.
* For automatic start with ''systemd'' use /opt/expecco_ALM/expeccoALM.service as a template. Change the ''USER'' parameter to the linux user the service should run under. Change the ''port'' option parameter to the port number.
* Enable the expecco ALM service with:
systemctl enable ./expeccoALM.service
* expecco ALM will be started automatically when the server is booted. When you don't want to reboot the server now, start the expecco ALM service with:
systemctl start expeccoALM
* Alternatevely, when you don't want to use autoa-start with systemd you can start expecco ALM manually:
/opt/expecco_ALM/bin/expecco_ALM -p <port number>

You can open expecco ALM with your default browser by connecting to http://<server>:<port>. A page for installing your expecco ALM license will be displayed (Appendix 1). You can select your license file (which you have already stored on the server) via “Install license file”. After expecco ALM has accepted your license file, you can remove it. If a valid license is already installed, the login page will be displayed instead. If this is your first installation, you can log in with the username “admin” and password “admin”.

If you get a blank page or an error page, try a different port and/or check the log file for error messages.

== SSL encryption / proxy server ==
Starting with version 26.1, expecco ALM (or AIDYMO) supports TLS/HTTPS natively – an upstream proxy server is no longer strictly required for this. For running in an existing setup where several services share a port, the proxy route remains supported (see below).

=== Native TLS encryption ===
To enable HTTPS directly, place the server certificate and private key in PEM format into the server's data directory. The server detects these files automatically at startup and then serves the same port over HTTPS instead of HTTP. No further configuration is needed.

Recognised file names (the first matching combination wins):
{| class="wikitable"
! Variant !! Files
|-
| Combined || <code>server.pem</code> (certificate + private key in one file)
|-
| Let's Encrypt || <code>fullchain.pem</code> + <code>privkey.pem</code>
|-
| Classic split || <code>cert.pem</code> + <code>key.pem</code>
|}

Where to place the PEM files:
* Windows (64-bit): <code>C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM</code>
* or the directory given with the command-line option <code>--workDir <directory></code>

If none of these files is present, the server starts unencrypted (HTTP) as before. The server host name is taken automatically from the certificate (first SAN dNSName, otherwise the CN).

=== Separate IP address on a port conflict ===
If another web server is already running on the same machine and the same port (e.g. an Apache on port 443), expecco ALM (or AIDYMO) must be bound to its own, separate IP address – two services cannot share the same port on the same IP address.

Bind the server to a specific address with the <code>--listen</code> command-line option:
expeccoALM --listen 192.168.1.50 --port 443
or alternatively:
AIDYMO --listen 192.168.1.50 --port 443

<code>--listen</code> may be given more than once and accepts IPv4 and IPv6 addresses (e.g. <code>192.168.1.50</code>, <code>::1</code>, <code>[::1]:443</code>). Without an embedded port, <code>--port</code> (or the default port) applies. Without <code>--listen</code> the server listens on all addresses of the machine (INADDR_ANY); this is only a problem when the port is already in use by another service.

=== Proxy server (existing setup, shared port without a separate IP address) ===
When expecco ALM (or AIDYMO) is integrated into an existing setup where a web server already occupies port 443 and ''no'' separate IP address is available, the port cannot be shared directly. In this case keep running expecco ALM on an internal port and put an upstream proxy server (e.g. Apache) in front of it to handle the TLS encryption. As multiple processes cannot bind to the same port (443) on the same IP address at the same time, this route is required here.

An Apache2 VirtualHost configuration would look like this (assuming expecco ALM is running on port 8465 - the necessary changes for your configuration are in bold):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

In this configuration example, the SSL parameters with the paths to your certificates and keys would be located in the Apache global file /etc/letsencrypt/ssl-xyz.de.conf.

== Notes on licensing ==
If you have purchased expecco ALM, you will receive a dongle and a license file. If you are evaluating expecco ALM, you will only receive the license file. The license file contains an individual expecco ALM license for you. For example, the name of your company, the modules activated for you or the validity period are stored in the license. The dongle (if you have purchased expecco ALM) must be permanently connected to the server on which expecco ALM is running. If you disconnect the dongle during operation, expecco ALM will stop working.

== Change license ==
[[File:ChangeAlmLicense.png|mini|Attachment 2]]
If you have a current expecco ALM version, you can import a new license file “expecco ALM license *.lic” via the expecco ALM web interface. Please refer to the attached screenshot (Appendix 2).

If you have an older version of expecco ALM, you must proceed as follows:
 - Since you will have to restart expecco ALM later, take the appropriate precautions (e.g. log off users, back up the database, etc.)
 - Log on to the computer running expecco ALM
 - Go to the following directory “C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM” or, if you are using a 32-bit operating system, “C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM” and delete the file “expecco_ALM.lic”
 - Restart the expecco ALM service via the Windows Service Manager or end the “expecco_ALM.exe” process via the Windows Task Manager. In the latter case, the Windows Service Manager will automatically restart expecco ALM.
 - Now you can access the expecco ALM web interface. A page for installing your expecco ALM license will be displayed (Appendix 1). You can select your license file via “Install license file”. After expecco ALM has accepted your license file, you can remove it.

== Importing expecco floating licenses ==
The license service of expecco ALM allocates available expecco floating licenses from a certain pool. 
Expecco floating licenses purchased from eXept can be added to this initially empty pool.
 
You will receive these expecco floating licenses as license file(s) usually by e-mail. 
A license file can contain one or more expecco floating licenses, even for different components (basic system, plug-ins and extensions). 
You can also purchase additional expecco floating licenses at any time and add them to the pool.
 
expecco floating licenses are always created specifically for an expecco ALM license and can only be used with this license and its dongle. 
It is therefore not necessary to keep such license files under lock and key or to exchange them via a secure connection. 
However, you should keep the dongle in a safe place and prevent theft.
 
To install an expecco floating license, open expecco ALM and log in. 
Now navigate to the “License Service” module using the top main navigation bar.
 
You are now in the license service and the list of installed expecco floating licenses is displayed. 
Switch to the “expecco license files” tab.
Use the navigation menu on the left to navigate to “Upload”. 
Here you can now upload your expecco floating licenses to the pool by simply uploading them. 
The expecco floating licenses you have just uploaded will now be displayed in the list mentioned above. 
From now on, these can also be accessed by remote expecco clients. 
You can also purchase additional expecco floating licenses and add them to the pool at any time.

== License Overview ==
To find out which individual expecco floating licenses are available or assigned, 
by switching to the “expecco licenses” tab. 
In particular, it is possible to see which computer/user is currently using which expecco floating license. 
This is useful, for example, if an expecco client has accidentally not ended its session, 
and other users need a corresponding license.

Lizenzserver expecco ALM

2026-07-29T08:17:27Z

Sv: Native TLS/HTTPS documented (since 26.1): PEM drop-in, --listen for separate IP on port conflict; proxy kept for shared-port/no-separate-IP setups

==Übersicht==

Der expecco Lizenzserver dient der zentralen Verwaltung von expecco Lizenzen. Durch den Lizenzserver kann expecco auf verschiedenen Rechnern (sowohl Entwicklungs- als auch reine Testausführungsrechner) ohne Dongle und lokale Lizenzdatei auf allen erreichbaren Rechnern im Netz installiert und ausgeführt werden.

Lizenzen werden dabei von den expecco-Rechnern vom Lizenzserver angefordert, im Lizenzserver reserviert,
und nach der Sitzung bzw. Testlauf wieder zurückgegeben. Damit können mehr Nutzer (allerdings nicht gleichzeitig) mit expecco arbeiten als Lizenzen erworben wurden.

Lizenzen sind kryptographisch gesicherte Dateien, welche nur in Verbindung mit einem von eXept gelieferten Lizenzserver-Dongle gelesen bzw. genutzt werden können. Lizenzen sind Dongle-spezifisch. Es ist also nicht notwendig, Maßnahmen zum Schutz vor Diebstahl oder Kopieren von Lizenzdateien zu ergreifen. Allerdings ist ein Verlust des Dongles aus nahe liegenden Gründen zu vermeiden.

{{SEITENTITEL:Lizenzservice Installation}}

== Voraussetzungen ==
Wir empfehlen, expecco ALM auf einem durchgehend verfügbaren Server mit Windows Server 2012 / Windows 10 oder höher zu installieren. Die Installation auf anderen Betriebssystemen (wie z.B. Linux) wäre bei Bedarf auch möglich. Ebenso ist die Installation in einer Cloud möglich, dort ist der Betrieb ohne Dongle möglich.

Damit expecco ALM flüssig arbeiten kann, werden folgende Hardware-Anforderungen an den Server gestellt:
 - ein "dezidierter" Prozessor mit mindestens 2 GHz
 - mindestens 1 GB Arbeitsspeicher (ausschließlich für expecco ALM)
 - mindestens 10 GB Festplattenspeicher (je nach Größe der Daten die expecco ALM verwalten soll)

Stellen Sie sicher, dass dieser Server für alle Clients erreichbar ist. Clients sind alle Rechner der expecco ALM Benutzer, Rechner die expecco ALM zur Testausführung dienen und Rechner mit "Floating" lizenziertem expecco. Bei Problemen bezüglich der Erreichbarkeit wenden Sie sich bitte an Ihren Netzwerkadministrator.

== Installation ==

Bitte halten Sie Ihre Lizenzdatei und ggfs. den Dongle für die Installation von expecco ALM bereit. 
Für die Installation in der Cloud benötigen Sie keinen Dongle; wir liefern dann eine Lizenzdatei, die an die MAC-Adresse des Servers gebunden ist. Falls sich der Server und damit dessen MAC-Adresse ändert, erhalten Sie eine neue angepasste Lizenzdatei von uns.

Ihre Lizenzdatei und eine Verknüpfung zum aktuellen expecco ALM Setup haben wir Ihnen per E-Mail zu kommen lassen. Der Installer hat folgenden Namen "expecco ALM 24.2.0 Setup.exe", wobei die Versionsnummer abweichen kann. Den Dongle haben wir per Post an Sie versendet (es sei denn Sie evaluieren expecco ALM oder nutzen die Cloud Variante mit der MAC-Adressen-Bindung).

Gehen Sie bitte wie folgt vor:
* Laden Sie den expecco ALM Installer auf dem Server, auf dem expecco ALM künftig laufen soll, herunter
* Legen Sie Ihre Lizenzdatei ebenfalls auf dem Server ab
* Verbinden Sie Ihren Dongle mit dem Server (Wenn Sie expecco ALM evaluieren oder die Cloud Variante mit der MAC-Adressen-Bindung nutzen, überspringen Sie diesen Schritt)
* Führen Sie den expecco ALM Installer ("expecco ALM ?.?.?.? Setup.exe" bzw. unter Linux "expecco ALM ?.?.?.? Setup.package") aus

Für Linux werden zusätzliche Pakete der Linux-Distribution benötigt. Diese sind [[Installation#Installation_von_expecco_auf_Linux|hier]] aufgeführt.

Nachdem der Installer erfolgreich ausgeführt wurde, läuft expecco ALM bereits als Service. Auf Ihrem Desktop wurde eine Verknüpfung zu expecco ALM angelegt. Es wurde auch ein Ordner für expecco ALM in Ihrem Startmenü erstellt. Dort können Sie unter "Konfiguration" den Port ändern (Standard ist Port 8081) oder über die "Logdatei" eventuelle Probleme feststellen.

[[Datei:InstallAlmLicense.png|mini|Anhang 1]]
Über die Verknüpfung auf Ihrem Desktop lässt sich expecco ALM mit Ihrem Standardbrowser öffnen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei (die Sie bereits auf dem Server abgelegt haben) auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen. Wenn bereits eine gültige Lizenz installiert ist, wird stattdessen die Anmeldeseite angezeigt. Falls es sich bei Ihnen um eine Erstinstallation handelt, können Sie sich mit Anmeldenamen "admin" und Kennwort "admin" anmelden.

Falls eine leere Seite oder eine Fehlerseite angezeigt wird, probieren Sie einen anderen Port aus und/oder schauen Sie in der Logdatei nach Fehlermeldungen.

== SSL-Verschlüsselung / Proxy-Server ==
Ab Version 26.1 unterstützen expecco ALM (bzw. AIDYMO) TLS/HTTPS direkt – ein vorgeschalteter Proxy-Server ist dafür nicht mehr zwingend erforderlich. Für den Betrieb in einer bestehenden Umgebung, in der sich mehrere Dienste einen Port teilen, wird der Proxy-Weg weiterhin unterstützt (siehe unten).

=== Native TLS-Verschlüsselung ===
Um HTTPS direkt zu aktivieren, legen Sie das Server-Zertifikat und den privaten Schlüssel im PEM-Format in das Datenverzeichnis des Servers. Der Server erkennt die Dateien beim Start automatisch und bedient denselben Port dann per HTTPS statt HTTP. Es sind keine weiteren Einstellungen nötig.

Erkannte Dateinamen (die erste vorhandene Kombination gewinnt):
{| class="wikitable"
! Variante !! Dateien
|-
| Kombiniert || <code>server.pem</code> (Zertifikat + privater Schlüssel in einer Datei)
|-
| Let's Encrypt || <code>fullchain.pem</code> + <code>privkey.pem</code>
|-
| Klassisch getrennt || <code>cert.pem</code> + <code>key.pem</code>
|}

Ablageort der PEM-Dateien:
* Windows (64-Bit): <code>C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM</code>
* oder das mit der Kommandozeilenoption <code>--workDir <Verzeichnis></code> angegebene Verzeichnis

Sind keine dieser Dateien vorhanden, startet der Server wie bisher unverschlüsselt (HTTP). Der Server-Hostname wird automatisch aus dem Zertifikat übernommen (erster SAN-dNSName, ersatzweise der CN).

=== Eigene IP-Adresse bei Port-Konflikt ===
Läuft auf demselben Rechner bereits ein anderer Webserver auf dem gleichen Port (z.B. ein Apache auf Port 443), so muss expecco ALM (bzw. AIDYMO) an eine eigene, separate IP-Adresse gebunden werden – zwei Dienste können sich denselben Port auf derselben IP-Adresse nicht teilen.

Binden Sie den Server dazu mit der Kommandozeilenoption <code>--listen</code> an eine bestimmte Adresse:
expeccoALM --listen 192.168.1.50 --port 443
oder alternativ:
AIDYMO --listen 192.168.1.50 --port 443

<code>--listen</code> kann mehrfach angegeben werden und akzeptiert IPv4- und IPv6-Adressen (z.B. <code>192.168.1.50</code>, <code>::1</code>, <code>[::1]:443</code>). Ohne eingebettete Portangabe gilt <code>--port</code> bzw. der Standardport. Ohne <code>--listen</code> lauscht der Server auf allen Adressen des Rechners (INADDR_ANY); das ist nur dann ein Problem, wenn der Port bereits von einem anderen Dienst belegt ist.

=== Proxy-Server (bestehende Umgebung, gemeinsamer Port ohne eigene IP-Adresse) ===
Wird expecco ALM (bzw. AIDYMO) in eine bestehende Umgebung integriert, in der bereits ein Webserver den Port 443 belegt und ''keine'' separate IP-Adresse zur Verfügung steht, kann der Port nicht direkt geteilt werden. In diesem Fall betreiben Sie expecco ALM weiterhin auf einem internen Port und stellen einen vorgeschalteten Proxy-Server (z.B. Apache) davor, der die TLS-Verschlüsselung übernimmt. Da sich nicht mehrere Prozesse gleichzeitig an denselben Port (443) auf derselben IP-Adresse binden können, ist dieser Weg hier erforderlich.

Eine Apache2 VirtualHost-Konfiguration würde entsprechend so aussehen (angenommen expecco ALM läuft mit Port 8465 - erforderliche Anpassung für ihre Konfiguration fett):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

Die SSL-Parameter mit dem Pfaden zu Ihren Zertifkaten uns Schlüsseln würden in diesem Konfigurations-Beispiel in der Apache-globalen Datei /etc/letsencrypt/ssl-xyz.de.conf liegen.

== Hinweise zur Lizenzierung ==
Wenn Sie expecco ALM erworben haben, erhalten Sie einen Dongle und eine Lizenzdatei. Falls Sie expecco ALM evaluieren, erhalten Sie ausschließlich die Lizenzdatei. Die Lizenzdatei beinhaltet eine für Sie individuelle expecco ALM Lizenz. So sind zum Beispiel: Der Name Ihrer Firma, für Sie freigeschaltete Module oder die Gültigkeitsdauer in der Lizenz hinterlegt. Der Dongle muss (insofern Sie expecco ALM erworben haben) ständig mit dem Server, auf dem expecco ALM ausgeführt wird, verbunden sein. Falls Sie den Dongle während des Betriebs abziehen, wird expecco ALM seinen Dienst einstellen.

== Lizenz wechseln ==
[[Datei:ChangeAlmLicense.png|mini|Anhang 2]]
Falls Sie eine aktuelle expecco ALM Version haben, können Sie eine neue Lizenzdatei "expecco ALM Lizenz *.lic" über das Webinterface von expecco ALM einspielen. Betrachten Sie dazu den angehängten Screenshot (Anhang 2).

Fall Sie eine ältere expecco ALM Version haben, müssen Sie folgendermaßen vorgehen:
 - Da Sie expecco ALM später neustarten müssen, tätigen Sie entsprechende Vorsorgemaßnahmen (Bspw. Benutzer abmelden, Datenbank sichern usw.)
 - Melden Sie sich auf dem Computer, der expecco ALM betreibt an
 - Begeben Sie sich in folgendes Verzeichnis "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM" oder falls es sich um ein 32Bit Betriebssystem handelt "C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM" und löschen Sie die Datei "expecco_ALM.lic"
 - Starten Sie den expecco ALM Service über den Windows-Service-Manager neu oder beenden Sie über den Windows-Task-Manager den Prozess "expecco_ALM.exe", in letzterem Fall wird der Windows-Service-Manager expecco ALM automatisch neustarten.
 - Nun können Sie das expecco ALM Webinterface aufrufen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei. auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen.

== Einbringen von expecco Floating-Lizenzen ==
Der Lizenzservice von expecco ALM vergibt verfügbare expecco Floating-Lizenzen aus einem bestimmten Pool. 
In diesen zunächst leeren Pool können von eXept erworbene expecco Floating-Lizenzen eingebracht werden.
 
Diese expecco Floating-Lizenzen erhalten Sie als Lizenzdatei(en) üblicherweise per E-Mail. 
Eine Lizenzdatei kann eine oder mehrere expecco Floating-Lizenzen auch für verschiedene Komponenten (Basissystem, Plugins und Erweiterungen) enthalten. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.
 
expecco Floating-Lizenzen werden immer spezifisch für eine expecco ALM Lizenz erstellt und sind nur mit dieser und deren Dongle nutzbar. 
Es ist also nicht notwendig solche Lizenzdateien unter Verschluss zu halten oder über eine sichere Verbindung auszutauschen. 
Allerdings sollten Sie den Dongle sicher aufbewahren bzw. Diebstahl vorbeugen.
 
Zur Einbringen einer expecco Floating-Lizenz öffnen Sie expecco ALM und melden Sie sich an. 
Jetzt navigieren Sie über die obere Hauptnavigationsleiste zum "Lizenzservice" Modul.
 
Sie befinden sich nun im Lizenzservice und Ihnen wird die Liste der installierten expecco Floating-Lizenzen angezeigt. 
Wechseln Sie zur Registerkarte "expecco Lizenzdateien". 
Navigieren Sie mithilfe des Navigationsmenüs auf der linken Seite zu "Hochladen/Upload". 
Hier können Sie nun durch ein einfaches Hochladen Ihrer expecco Floating-Lizenzen selbige in den Pool einbringen. 
In der zuvor genannte Liste werden nun die eben hochgeladenen expecco Floating-Lizenzen anzeigt. 
Diese sind von nun an auch von entfernten expecco Clients abrufbar. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.

== Lizenz Übersicht ==
Welche einzelnen expecco Floating-Lizenzen verfügbar oder vergeben sind, 
erfahren Sie indem Sie zur Registerkarte "expecco Lizenzen" wechseln. 
Insbesondere ist hieraus ersichtlich, welcher Rechner/Benutzer welche expecco Floating-Lizenz aktuell nutzt. 
Dies ist beispielsweise sinnvoll, wenn ein expecco Client seine Sitzung versehentlich nicht beendet hat, 
und andere Nutzer eine entsprechende Lizenz benötigen.

KI Coding Plugin

2026-07-29T07:50:05Z

Sv: link English translation via Languages template

KI Coding Plugin/en

2026-07-29T07:50:01Z

Sv: English translation of the AI Coding Plugin page (incl. 26.2 features)

{{Languages|KI Coding Plugin/en|label=English}}

= AI Coding Plugin =

The AI functions described here are part of the license feature '''AI Coding'''. If this feature is not included in your license, the ''Ask AI'' menu entries remain visible in the editor toolbars, but are disabled (tooltip: "Install the AI coding plugin to enable").

The AI Coding Plugin integrates a Large Language Model (LLM) based
AI assistant into the activity editor (activity code), the
compound network editor, the documentation editor and the
ST/X Class Browser. The plugin supports several providers, which can be
switched in the settings dialog:

* '''Anthropic Claude''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI ChatGPT''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' local or remote (codellama:7b, codellama:13b)
* others such as '''Groq''', '''Zen''', '''LLaMa''', '''Tabnine''' etc.
* '''Claude Code (subscription)''' — uses your existing Claude subscription instead of an API key ''(available in expecco 26.2)''

In addition there is a further entry '''Inhause'''; this one is intended for your own, company-internal AI.
:: Note: in fact they all speak the same OpenAI chatGPT protocol underneath; so you can just as well enter the URL of your own AI under some other provider. This entry therefore only serves clarity, and provides a place where you can store your credentials, in case you do want to be able to chat with other providers in between without having to re-enter the URLs and API keys each time.

Depending on the selected provider, the toolbar button appears as
<code>Ask Claude</code> or <code>Ask ChatGPT</code> or <code>Ask ...</code> ; the settings tab
is called "<code>AI Coding</code>", under Plugins (Erweiterungen).

== Activity Editor ==

In the activity code editor a button
<code>Ask Claude</code> / <code>Ask ChatGPT</code> appears in the toolbar, with the following actions:

* '''Open KI Chat Window''' — opens the standalone chat window
* '''Explain code''' — explains the code of the current activity
* '''Suggest improvement''' — suggests improvements
* '''Find bugs''' — looks for errors, race conditions, nil-handling problems
* '''Generate doc-comment''' — generates an activity documentation including pin comments and fills the Documentation tab
* '''Custom prompt...''' — free prompt; the activity code is sent along as context
* '''Set model''' ▸ — submenu with the models of the active provider (the currently active model is marked with ''(active)'')
* '''Set provider''' ▸ — only visible if API keys are configured for more than one provider; submenu to switch between Claude, ChatGPT or another provider

Code suggestions can be transferred into the activity body with
<code>[Apply]</code> (directly at the respective code block in the chat or via
the upper Apply button). Smalltalk/X helper methods delivered by the AI
(form: <code>Class >> selector</code>) are compiled into the named class after
a confirmation prompt.

== Compound (Network) Editor ==

The toolbar of compound worksheets carries the same
button, restricted to the actions that make sense for networks
(''Open KI Window'', ''Generate doc-comment'') — likewise with the
submenus ''Set model'' and, where applicable, ''Set provider''.

== Documentation Editor ==

The Documentation tab of the block description (editor for test cases,
test plans and activities) carries the same toolbar button
<code>Ask ...</code> with the entries listed above.
''Generate doc-comment'' analyses the current block (name,
existing description, input/output pins, sub-steps of a
compound network, referenced environment variables) and proposes
a complete block and pin documentation.

If the block is write-protected (imported library, RTL license),
<code>[Apply]</code> asks whether the block should be unlocked and the
documentation entered.

== Class Browser (ST/X) ==

In the Class Browser the actions are available under the '''AI''' submenu
and in the selector context menu. The actions
operate on the currently selected method (class + selector +
source text are sent along as context). '''[Apply]''' can insert the
result directly into the method of the active class.
Here too, '''Set model''' and, where applicable, '''Set provider''' are available as
submenus.

In addition there are two actions that refer to the selected '''class'''
instead of to a single method ''(available in expecco 26.2)''.
It is sufficient to select the class; a method selection is not needed for these:

* '''Explain Class''' — explains the class as a whole: what it is responsible for, what role its instance variables play, how its protocols interact and what to watch out for when using it.
* '''Generate Class Documentation''' — proposes a documentation text for the class; '''[Apply]''' enters it into the class's documentation.

== Chat Window ==

The standalone chat window carries the title
'''AI Coding [<product> / <model>]''' (e.g.
"AI Coding [Claude / claude-opus-4-7]") and shows the token usage
and the accumulated cost after each turn — provided that prices for
the selected model are on file. Provider and model changes
in the settings dialog are picked up live.

The transcript is built as a vertical panel of "cards":

* '''Prose cards''' contain the flowing text of the answer; lines are wrapped to the window width.
* '''Code cards''' (framed) are created from markdown code blocks (<code>```...```</code>) and are editable as a '''Workspace''' — the standard Smalltalk popup menu offers doIt / printIt / inspectIt, a <code>TestCase</code> <code>simulatedSelf</code> is set, so that <code>self assert:... equals:...</code> can be executed directly. Long blocks scroll inside the card. At the top right sit the buttons '''[Apply]''' (where it makes sense for the context) and '''[⎘ Copy]'''; on the left the language tag (smalltalk, python, …) is displayed.
* '''Doc cards''' (full width, prose) are created from the special <code>```doc</code> block that the documentation generator requests; the content is the proposed documentation for block and pin descriptions.

Scroll lock: as long as the user is already at the bottom end of the
transcript, the display automatically follows newly arriving cards;
after scrolling up manually the position stays put.

Images can be sent as attachments (screenshot or
PNG/JPG file). Attachments only work with vision-capable models (with OpenAI e.g. the gpt-4o family).

== Settings (AI Coding) ==

In the settings dialog under '''Plugins → AI Coding''' (or under
'''Tools → AI Coding''' in the Smalltalk launcher) the following are configured:

* '''Provider''' — Anthropic, OpenAI etc. When switching, the API URL and the default model are adjusted accordingly; the stored API key of the respective provider is loaded.

* '''Claude Code (subscription)''' ''(available in expecco 26.2)'' — this provider does not use the API, but the locally installed command line program ''Claude Code'' and thereby your existing Claude subscription. No API key is needed, and no token-based API costs are incurred. The fields '''API Key''', '''API URL''' and '''Proxy''' are hidden for this provider, since they have no meaning here; as authentication, "Subscription (external login)" is shown. The prerequisite is that ''Claude Code'' is installed and has been logged in once — for this, start <code>claude</code> in a console and complete the login. The model can be given as a tier alias (''sonnet'', ''opus'', ''haiku'' — in each case the current model of that tier) or as a fixed model name.

* '''API Key''' — key of the currently selected provider. The keys are stored separately per provider (<code>#claudeApiKey_anthropic</code> resp. <code>#claudeApiKey_openai</code>), so that one can switch between the providers without entering them again. Setting the key is done exclusively through this dialog.

* '''Model''' — a model from the list of the active provider or a model name entered by yourself. Can also be switched directly via the '''Set model''' submenu in the editor toolbars.

* '''Max output tokens''' — maximum answer length.

* '''API URL''' — only to be changed for your own proxies / gateways. Default: <code>https://api.anthropic.com/v1/messages</code> resp. <code>https://api.openai.com/v1/chat/completions</code>.

== Obtaining an API key ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], key format <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], key format <code>sk-...</code> or <code>sk-proj-...</code>. A funded account is required (minimum amount currently USD 5).

== Data protection / data flow ==

With the provider '''Anthropic''' active, the requests go directly to
<code>api.anthropic.com</code>, with '''OpenAI''' directly to
<code>api.openai.com</code>. There is no eXept-side proxy or
cache. Along with the activity source code resp. the method
source texts, pin descriptions, sub-step names and
referenced environment variables from the block description model
are also sent as context.

When using Anthropic API tokens - as is the case here - the data is, according to Anthropic, not used for training the AI model ([https://privacy.claude.com/en/articles/7996868 Anthropic's statement on this]). We cannot guarantee or be held liable for the truth of this statement. Also to be considered is that the AI models do not run in domestic data centers, and that possibly further "eavesdroppers" are involved. This applies in particular to high-tech, AI, software and defence companies, where cases of industrial espionage are known.

⚠ If you want to be sure that no information leaves your premises, we recommend your own closed in-house AI environment, as already exists at some of our customers. You may then of course only configure the URLs of that environment. Expecco communicates exclusively with the AI you have entered.

== Coding assistants ==

When starting the MCP server connection, expecco automatically enters the necessary configuration entries into the config files of the supported coding assistants. The following sections describe the location and format of the respective entries — for information, or in case you want to add or check them manually.

=== Claude Code ===
: Note: This section describes the reverse direction — an externally running ''Claude Code'' accesses expecco. If you want to use ''Claude Code'' the other way round as an AI provider ''inside'' expecco, see the provider '''Claude Code (subscription)''' in the section [[#Settings (AI Coding)|Settings]] ''(since expecco 26.2)''.

Entries for the mcp-server are inserted by expecco into the <code>".claude.json</code> file (typically in your home directory) from the settings dialog:
...
"mcpServers": {
"mcp": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
},
...
after that, once "claude.exe" has been started, it should be listed with the <code>/mcp</code> command.

=== Opencode (with Zen) ===

After logging in (opencode authlogin) you start opencode again. Currently the mcps have to be configured by you in an editor (automatic entries in a later version. For this, change the file "<code>.config\opencode\opencode.jsonc</code>" (likewise typically in the home directory) to:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
}
}

Should you have forgotten a comma, an error message will appear at startup. With "/mcps" the two should be listed.

=== Cursor ===
Cursor reads its MCP configuration from <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Add there:
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
At the next start of Cursor the servers should appear under <code>Settings → MCP</code> as ''connected''.

=== Zed ===
Zed reads its MCP configuration from <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). The entry sits under the key <code>context_servers</code> (not <code>mcpServers</code> as with the others):
{
"context_servers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}

=== Tabnine ===
Tabnine looks for its MCP configuration first per project under <code><project>/.tabnine/mcp_servers.json</code>, then in the home directory (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Alternatively you can also enter the server directly in the Tabnine IDE plugin via <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code>.

== Tips ==

* '''Multiple conversations''': the chat is a singleton — a new request via a browser/editor menu starts a '''new''' conversation each time. Follow-up questions (clarification, going deeper) go through the input field in the same conversation.
* '''Careful:''' The size of the transmitted data (including that from the chat window) goes into the cost calculation. Therefore always start a new conversation when it is about a new topic.
* '''Switching the model''': For quick routine answers Haiku or Sonnet, for difficult refactorings Opus. Via the '''Set model''' submenu directly from the toolbar or via the settings.
* '''Switching the provider''': If keys are configured for both providers, the '''Set provider''' submenu switches over without the detour via the settings dialog.
* '''Executing code directly''': In code cards, selected Smalltalk code can be evaluated directly via doIt / printIt / inspectIt — practical e.g. to try out SUnit asserts proposed by the model right away, without first copying the code into a workspace.
* '''Custom prompt''' is well suited for "why does method X do it this way and not that way?" or "write me a ParameterizedTest for this with the following data: …".

== Tips for working with claudeCode ==
This section is outdated; the tasks listed below can
now also be carried out 1:1 in the chat window.

If you use ClaudeCode or Opencode, far more functions are available to you: you can for example type into the claudeCode terminal:
* "make me a new suite in a new window",
* "Make an action to compute the circumference of a circle for a given radius",
* "Create a new suite with a test case that does the following:
** 1) open a web browser on "www.exept.de".
** 2) click on the logo at the top left.
** 3) close the web browser.
* which functionality is in xxx.ets

(Note: it makes no difference whether you converse in German or English)

We have put Claude in a position to search for suitable libraries by itself, to import them, to generate actions and to create the test plan.

In fact also to run the test right away and analyse the result.

Currently we are training, so that claude e.g. decides by itself whether it is better to define a missing action as a diagram or elementary. It is able to see the functions of the underlying framework and also to accomplish complex tasks:
* "Action for reading the annual revenues of a year from the database"
* extract all budget entries from the xml document and deliver the sum

=== Experiences and tips for the work ===

==== Choice of model; Sonnet, Heiku and Fable ====
Sonnet-4 feels far more intelligent than Heiku-4.5,
but also far more expensive. Fable is for very complex tasks, but very expensive (I mean: really expensive). Your budget can melt very quickly with Sonnet - especially when working at medium or high intelligence level. Haiku makes far more mistakes and one should look closely at what it generates. It felt as if Sonnet was better even at low level than Haiku. But the price...
Even better is Fable, but extremely expensive; within half an hour the daily token budget can already be used up.

The following concrete tips come from our first experiences, this list is being updated, and may also be based on our own stupidity. So it is possibly to be taken with caution.

* give Haiku more hints, e.g. "have a look over there, or take that as an example". Sonnet finds solutions much better by itself.

* short instructions, the more concrete the cheaper.

* Haiku is far "lazier". E.g. sonnet automatically created a documentation for new actions, and also kept it up to date. For Haiku on the other hand one had to set up an explicit rule for that (e.g. with "when you create or change an action, update the documentation")

* Heiku is dumber. Rules that were created by Sonnet may under certain circumstances not be followed by Haiku, because Sonnet can generalize far more.

* tell all of them that when they have a problem, they should not search for a long time by themselves, but instead ask whether one can give them a hint. If you do not do that, it can happen that Sonnet thinks for a quarter of an hour and the dollars melt like ice in the sun (happened to me when a socket problem occurred in the communication, and it did not recognize that the answers from mcp were wrong, it then searched for all sorts of ways by itself to send off a message, incl. the creation of various shell, curl and Python scripts... although there actually was an interface for it, which however had a bug). In particular I had stupidly said beforehand, in effect, that it should do this and that when a problem occurs, whereupon exactly this problem occurred again...

* restrict the model in its possibilities, e.g. say "do not edit the files but use a tool for it", or "one expecco action and tell me beforehand which one you take". Otherwise it can happen that it starts unpacking your ets in order to search for strings in it, although it can actually do that more easily via the interface (this concrete problem will no longer occur, but you see the point). There Sonnet was far more intelligent, but also thought for longer.

* when you notice that it makes a mistake, say (more or less literally) "remember: don't do this, or to do that do that."

* you can keep these memories both in your UserProfile (i.e. in the local filesystem) and in your expecco preferences. For that say "remember this in in my expecco preferences" or "remember (in my user memory): bla bla". Memories can also be deleted with "forget to ...". At the beginning of the next session say "read the expecco preferences memory".

* switch the model or the level, depending on the complexity of the task. But keep in mind that knowledge is lost from session to session if it is not remembered. Technically, memories are nothing other than the reading of a list of the earlier remember instructions. So they cost tokens too. You could therefore also just retype the memories ;-)

* Fable is a real star when it comes to designing e.g. a complex architecture. My tip: let it make a plan, and have a simpler model implement it step by step.

* even if it seems that way: the "thing" is not a human; leave out "please, thank you, or justifications - unless they serve the decision". In fact they may increase the token consumption.

Subjective summary:
* Haiku is much faster in answering and costs a tenth. With Sonnet my limit was reached after 3-4 hrs of work and I had to take a break of hours. With Fable the forced break can already be triggered after 1/2 an hour. With Haiku you can work through. But I also need at least twice as much time to guide Haiku and to iron out its mistakes again.

== What can a local AI (ollama) do ==

Please scroll forward to the LLaMa.cpp experiment.

First attempts were rather sobering. Without access to local sources 1), with purely trained-in knowledge, the models are presumably too small. Here a conversation with gemma3:8b-it-qat (8 billion, quantized) on a machine without GPU.
The response times are of course bad, but with a GPU possibly usable. If you have access to machines with GPU in-house you should definitely use them (with as much RAM as possible, so that the models actually fit in!)

Important: we are still beginners ourselves and no [https://en.wikipedia.org/wiki/Susan_Calvin AI psychologists].
But the experiences are currently being fed into the next release in a fine-tuning process.

1) e.g. via mcp tools, which we have already implemented for claudeCode in the current version.

=== Installation (ollama) ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Session 1 ===
Notes: Important, otherwise the model talks your ear off!

>>> respond short and concise
Understood

Notes: It has no Smalltalk/X knowledge, but VW and Pharo are similar enough.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Show-off - we shall see

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Wrong answer; Smalltalk uses 1-based indices, and 'bla' is a String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
not bad. PI does not exist as a global variable (correct would be "Float pi"), but still remarkable.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wrong again; 1-based index, substring:to: possibly present in some other Smalltalk. One could let that pass.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
better, but still the wrong index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
was to be expected

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
I see. It accepts that I corrected it - but then is stubborn.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, it could know it; but it evidently lacks the capacity for abstraction. Let's try it with an example:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
I see, a nuance. And actually I had said it should answer short and exact. It can spare us the apologies. Let's see:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
there we go; it works after all.

=== Session 2 ===

New attempt; a new session. Give it basic knowledge that it does not have in the model.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
correct! 
Would I have had to add that this does not only apply to strings? Let's see:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
correct!

So one has to fill the context with knowledge (or fine tuning, for which our GPU is presumably not capable), then quite sensible things come out. We are working on evaluating this, so that possibly even a local AI (with GPU, however) can provide useful support.

=== Experiments with qwen2.5-coder:7b ===
This one shows astonishingly good answers on our local ollama installation with an (by today's standards) average GPU (price today approx. 1500.-)

== Summary (local AI with small models) ==

One should have no illusions: a local AI with a few billion floats (or even 4bit quantized) cannot in the slightest keep up with
a model with trillions of values (i.e. Claude or ChatGPT or an in-house large data center with a few 10000 NVidia GPUs).

Here a chat with a local llama3.2:3b (3 billion floats, bf16):
--- user ---
how ´would you open an expecco app using mcp

''I am asking how it would call our mcp connection (large models from Anthropic or OpenAI would answer correctly here)''

```
MCP.openApp("type://com.expeccotech.app.name", null);
```

Replace `"type://com.expeccotech.app.name"` with the specific type identifier for your app. This might be a URI or a project handle.

This command will open the Expecco app using MCP, and it may prompt you to authenticate or authorize if necessary.

Here's an example of how you could use this method in Python:

```python
import mcpsys

app = mcpsys.MCP()
app.openApp("type://com.expeccotech.app.name", None)
```

In JavaScript, you can also use this method with the following code:

```javascript
var app = new MCP();
app.openApp("type://com.expeccotech.app.name", null);
```

''that is of course complete nonsense; one could say: it is making it up out of thin air; let's tell it that:''

--- user ---
you just made this all up. you are wrong. do not hallucinate. what mcp tools do you really have at hand

--- assistant ---
I got a bit carried away with my imagination.

To be honest, I don't actually have any MCP (Model Computing Platform) tools or knowledge at hand. I'm an AI trained on general knowledge and can only provide information based on my training data.

MCP is a specific framework developed by the University of Michigan, and it seems that I was not properly informed about its capabilities and tools. If you'd like to correct me or provide more information about MCP, I'll do my best to learn from it!

''aha - it admits it!''

== LLaMa.cpp ==

For installation see the website.

Command:
llama-server.exe -hf unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:Q4_K_M --cts-size XXXX

Note: by default, llama.cpp uses only a context window of 4096. That is too little for meaningful tasks. Start llama.cpp with --ctx-size 8192 or 16384, 32768 or 65536. The supported size depends on the model. A large context of course has an influence on memory requirements (VRAM in GPU, RAM in CPU) and response time. If you have enough CPU VRAM resp. RAM, it is in any case better to set a larger context size.

The model runs on the local CPU (laptop, without GPU), and shows quite good answers in doing so (if one has patience). Admittedly, we have also pre-packed a fair amount of knowledge into the memory.

In the expecco chat window:
open an exepcco browser on a new project
it does it!
create a python action to compute the area from given radius
it creates a correct Python script action. Chapeau. It even mastered the handling of the input and output pins, which is somewhat cumbersome with script actions.

again, as Smalltalk action
takes a while, but it reacts to syntax errors, corrects itself. Afterwards it executes the action for verification. Output: 
''Verified: for `radius = 5.0`, `area = 78.5398163397448` — same result as the Python version.''

It approaches the question of how to split a string (e.g. 'helloworld') systematically - it searches the running expecco for string functions. That takes a while



== Choice of model size ==

=== Translation ===
Experiments with gemma3:270m (very small; 270 million), gemma3:1b (1 billion) and gemma3:4b (4 billion). All on a local machine without GPU (which has no influence on the answer, but determines the response time).

Experiment: translation of a block documentation.

Input: translate to German:
"show a dialog with an informationstring"

The 270m and 1b models do not know grammatical gender; they express themselves somewhat awkwardly:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

resp. (1 billion).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

The 4 billion model seems usable:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In no case should one trust the AI "blindly".

=== Working with Expecco ===
To actually let the model generate code or actions, the
simplest models are NOT sufficient;
Here a preliminary list of our results:

* qwen2.5-coder:3b definitely too dumb
* qwen2.5-coder:7b after some improvements to the initial instructions on the use of the expecco tools the model can: open a browser, create a project. Attention: requires contextSize=8192; with 4096 it is too forgetful
*
[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

KI Coding Plugin

2026-07-29T07:48:34Z

Sv: /* Erfahrungen und Tipps für die Arbeit */

= KI Coding Plugin =

Die hier beschriebenen KI-Funktionen sind Teil des Lizenz-Features '''AI Coding'''. Ist dieses Feature in Ihrer Lizenz nicht enthalten, erscheinen die ''Ask AI''-Menüeinträge zwar weiterhin sichtbar in den Editor-Toolbars, sind aber deaktiviert (Tooltip: "Install the AI coding plugin to enable").

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic Claude''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI ChatGPT''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
* weitere wie '''Groq''', '''Zen''', '''LLaMa''', '''Tabnine''' etc.
* '''Claude Code (subscription)''' — nutzt Ihr vorhandenes Claude-Abonnement statt eines API-Schlüssels ''(verfügbar ab expecco 26.2)''

Zusätzlich gibt es noch einen weiteren Eintrag '''Inhause'''; dieser ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe OpenAI chatGPT Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Chat Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

Zusätzlich gibt es zwei Aktionen, die sich auf die ausgewählte '''Klasse'''
beziehen statt auf eine einzelne Methode ''(verfügbar ab expecco 26.2)''.
Es genügt, die Klasse auszuwählen; eine Methodenauswahl ist dafür nicht nötig:

* '''Explain Class''' — erklärt die Klasse als Ganzes: wofür sie zuständig ist, welche Rolle ihre Instanzvariablen spielen, wie ihre Protokolle zusammenwirken und worauf man beim Verwenden achten muss.
* '''Generate Class Documentation''' — schlägt einen Dokumentationstext für die Klasse vor; '''[Apply]''' trägt diesen in die Dokumentation der Klasse ein.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren nur mit vision-fähigen Modellen (bei OpenAI z.B. gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic, OpenAI etc. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.

* '''Claude Code (subscription)''' ''(verfügbar ab expecco 26.2)'' — dieser Anbieter verwendet nicht die API, sondern das lokal installierte Kommandozeilenprogramm ''Claude Code'' und damit Ihr vorhandenes Claude-Abonnement. Es wird kein API-Schlüssel benötigt, und es fallen keine tokenbasierten API-Kosten an. Die Felder '''API Key''', '''API URL''' und '''Proxy''' werden für diesen Anbieter ausgeblendet, da sie hier keine Bedeutung haben; als Authentifizierung erscheint "Subscription (external login)". Voraussetzung ist, dass ''Claude Code'' installiert ist und einmalig angemeldet wurde — dazu <code>claude</code> in einer Konsole starten und die Anmeldung abschließen. Das Modell kann als Stufen-Alias (''sonnet'', ''opus'', ''haiku'' — jeweils das aktuelle Modell dieser Stufe) oder als fester Modellname angegeben werden.

* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.

* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.

* '''Max output tokens''' — maximale Antwortlänge.

* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>. Es gibt keinen eXept-seitigen Proxy oder
Zwischenspeicher. Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Sub-Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell
als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens - wie hier der Fall - werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, daß die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind.

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Coding Assistenten ==

Beim Start der MCP-Server-Anbindung trägt expecco die nötigen Konfigurationseinträge automatisch in die Config-Dateien der unterstützten Coding-Assistenten ein. Die folgenden Abschnitte beschreiben Ort und Format der jeweiligen Einträge — zur Information bzw. falls Sie sie manuell ergänzen oder kontrollieren möchten.

=== Claude Code ===
: Anm.: Dieser Abschnitt beschreibt den umgekehrten Weg — ein extern laufendes ''Claude Code'' greift auf expecco zu. Wenn Sie ''Claude Code'' umgekehrt als KI-Anbieter ''innerhalb'' von expecco nutzen möchten, siehe den Anbieter '''Claude Code (subscription)''' im Abschnitt [[#Einstellungen (AI Coding)|Einstellungen]] ''(ab expecco 26.2)''.

Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"mcp": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls im typischerweise Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollten die beiden aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Dieser Abschnitt ist veraltet; die unten aufgeführten Aufgaben könnnen
nun 1:1 auch so im Chatfenster ausgeführt werden.

Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

== Erfahrungen und Tipps für die Arbeit ==

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen - es sei denn sie dienen der Entscheidung - weg. Tatsächlich erhöhen sie den Tokenverbrauch u.U.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (ollama) ==

Bitte vorwärts scrollen zu LLaMa.cpp Versuch.

Erste Versuche waren eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation (ollama) ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Zusammenfassung (lokale AI mit kleinen Modellen) ==

Man sollte sich keinen Illusionen hingeben: eine lokale AI mit ein paar Milliarden floats (oder gar 4bit quantized) kann nicht im geringsten mit
einem Modell mit Billionen Werten mithalten (i.e. Claude oder ChatGPT oder einem hauseigenen großen Rechenzentrum mit ein paar 10000 NVidia GPUs).

Hier ein chat mit lokalem llama3.2:3b (3 Milliarden floats, bf16):
--- user ---
how ´would you open an expecco app using mcp

''ich frage wie er unsere mcp Anbindung aufrufen würde (große Modelle von Anthropic oder OpenAI würden hier korrekt antworten)''

```
MCP.openApp("type://com.expeccotech.app.name", null);
```

Replace `"type://com.expeccotech.app.name"` with the specific type identifier for your app. This might be a URI or a project handle.

This command will open the Expecco app using MCP, and it may prompt you to authenticate or authorize if necessary.

Here's an example of how you could use this method in Python:

```python
import mcpsys

app = mcpsys.MCP()
app.openApp("type://com.expeccotech.app.name", None)
```

In JavaScript, you can also use this method with the following code:

```javascript
var app = new MCP();
app.openApp("type://com.expeccotech.app.name", null);
```

''das ist natürlich völliger Unsinn; man könnte sagen: er saugt sich das aus den Fingern; sagen wir ihm das:''

--- user ---
you just made this all up. you are wrong. do not hallucinate. what mcp tools do you really have at hand

--- assistant ---
I got a bit carried away with my imagination.

To be honest, I don't actually have any MCP (Model Computing Platform) tools or knowledge at hand. I'm an AI trained on general knowledge and can only provide information based on my training data.

MCP is a specific framework developed by the University of Michigan, and it seems that I was not properly informed about its capabilities and tools. If you'd like to correct me or provide more information about MCP, I'll do my best to learn from it!

''aha - er gibt es zu!''

== LLaMa.cpp ==

Installation siehe Webseite.

Kommando:
llama-server.exe -hf unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:Q4_K_M --cts-size XXXX

Hinweis: per default, verwendet llama.cpp nur ein Contextfenster von 4096. Das ist zu wenig für sinnvolle Aufgaben. Starten Sie llama.cpp mit --ctx-size 8192 oder 16384,32768 oder 65536. Die unterstützte Größe hängt vom Modell ab. Ein großer Context hat natürlich Einfluß auf Speicherbedarf (VRAM in GPU, RAM in CPU) und Antwortzeit. Wenn Sie genug CPU VRAM bzw. RAM haben, ist es in jedem Fall besser, eine größere Contextsize zu setzen.

Das Modell läuft auf der lokalen CPU (Laptop, ohne GPU), und zeigt dabei durchaus gute Antworten (wenn man Geduld hat). Zugegeben, wir haben auch einiges an Wissen in den Speicher vorgepackt.

Im expecco Chat Fenster:
open an exepcco browser on a new project
macht er!
create a python action to compute the area from given radius
er legt eine korrekte Pythonscript Aktion an. Chapeau. Sogar die Behandlung der Ein- und Ausgangspins, die bei Scriptaktionen etwas umständlich ist, hat er gemeistert.

again, as Smalltalk action
braucht etwas, aber er reagiert auf Syntaxfehler, korrigiert sich. Danach führt er die Aktion zur Verifikation aus. Ausgabe: 
''Verified: for `radius = 5.0`, `area = 78.5398163397448` — same result as the Python version.''

Die Frage wie man einen String (z.B. 'helloworld') zerlegt geht er systematisch an - er sucht im laufenden expecco nach Stringfunktionen. Das dauert



== Wahl der Modellgrösse ==

=== Übersetzung ===
Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In keinem Fall sollte man der KI "blind" vertrauen.

=== Arbeit mit Expecco ===
Um das Modell tatsächlich Code oder Aktionen erzeugen zu lassen reichen die
einfachsten Modell NICHT;
Hier eine vorläufige Liste unserer Resultate:

* qwen2.5-coder:3b definitiv zu dumm
* qwen2.5-coder:7b nach einigen Verbesserungen an den initialen Anweisungen zum Gebrauch der expecco tools kann das Model: Browser öffnen, Projekt anlegen. Achtung: benötigt contextSize=8192; mit 4096 ist es zu vergesslich
*
[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

KI Coding Plugin

2026-07-29T07:37:20Z

Sv: 26.2: Anbieter 'Claude Code (subscription)'; Klassen-Aktionen Explain Class / Generate Class Documentation

= KI Coding Plugin =

Die hier beschriebenen KI-Funktionen sind Teil des Lizenz-Features '''AI Coding'''. Ist dieses Feature in Ihrer Lizenz nicht enthalten, erscheinen die ''Ask AI''-Menüeinträge zwar weiterhin sichtbar in den Editor-Toolbars, sind aber deaktiviert (Tooltip: "Install the AI coding plugin to enable").

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic Claude''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI ChatGPT''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
* weitere wie '''Groq''', '''Zen''', '''LLaMa''', '''Tabnine''' etc.
* '''Claude Code (subscription)''' — nutzt Ihr vorhandenes Claude-Abonnement statt eines API-Schlüssels ''(verfügbar ab expecco 26.2)''

Zusätzlich gibt es noch einen weiteren Eintrag '''Inhause'''; dieser ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe OpenAI chatGPT Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Chat Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

Zusätzlich gibt es zwei Aktionen, die sich auf die ausgewählte '''Klasse'''
beziehen statt auf eine einzelne Methode ''(verfügbar ab expecco 26.2)''.
Es genügt, die Klasse auszuwählen; eine Methodenauswahl ist dafür nicht nötig:

* '''Explain Class''' — erklärt die Klasse als Ganzes: wofür sie zuständig ist, welche Rolle ihre Instanzvariablen spielen, wie ihre Protokolle zusammenwirken und worauf man beim Verwenden achten muss.
* '''Generate Class Documentation''' — schlägt einen Dokumentationstext für die Klasse vor; '''[Apply]''' trägt diesen in die Dokumentation der Klasse ein.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren nur mit vision-fähigen Modellen (bei OpenAI z.B. gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic, OpenAI etc. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.

* '''Claude Code (subscription)''' ''(verfügbar ab expecco 26.2)'' — dieser Anbieter verwendet nicht die API, sondern das lokal installierte Kommandozeilenprogramm ''Claude Code'' und damit Ihr vorhandenes Claude-Abonnement. Es wird kein API-Schlüssel benötigt, und es fallen keine tokenbasierten API-Kosten an. Die Felder '''API Key''', '''API URL''' und '''Proxy''' werden für diesen Anbieter ausgeblendet, da sie hier keine Bedeutung haben; als Authentifizierung erscheint "Subscription (external login)". Voraussetzung ist, dass ''Claude Code'' installiert ist und einmalig angemeldet wurde — dazu <code>claude</code> in einer Konsole starten und die Anmeldung abschließen. Das Modell kann als Stufen-Alias (''sonnet'', ''opus'', ''haiku'' — jeweils das aktuelle Modell dieser Stufe) oder als fester Modellname angegeben werden.

* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.

* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.

* '''Max output tokens''' — maximale Antwortlänge.

* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>. Es gibt keinen eXept-seitigen Proxy oder
Zwischenspeicher. Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Sub-Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell
als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens - wie hier der Fall - werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, daß die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind.

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Coding Assistenten ==

Beim Start der MCP-Server-Anbindung trägt expecco die nötigen Konfigurationseinträge automatisch in die Config-Dateien der unterstützten Coding-Assistenten ein. Die folgenden Abschnitte beschreiben Ort und Format der jeweiligen Einträge — zur Information bzw. falls Sie sie manuell ergänzen oder kontrollieren möchten.

=== Claude Code ===
: Anm.: Dieser Abschnitt beschreibt den umgekehrten Weg — ein extern laufendes ''Claude Code'' greift auf expecco zu. Wenn Sie ''Claude Code'' umgekehrt als KI-Anbieter ''innerhalb'' von expecco nutzen möchten, siehe den Anbieter '''Claude Code (subscription)''' im Abschnitt [[#Einstellungen (AI Coding)|Einstellungen]] ''(ab expecco 26.2)''.

Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"mcp": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls im typischerweise Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"mcp": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollten die beiden aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"mcp": {
"url": "http://127.0.0.1:9876/mcp"
},
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Dieser Abschnitt ist veraltet; die unten aufgeführten Aufgaben könnnen
nun 1:1 auch so im Chatfenster ausgeführt werden.

Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

=== Erfahrungen und Tipps für die Arbeit ===

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen - es sei denn sie dienen der Entscheidung - weg. Tatsächlich erhöhen sie den Tokenverbrauch u.U.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (ollama) ==

Bitte vorwärts scrollen zu LLaMa.cpp Versuch.

Erste Versuche waren eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation (ollama) ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Zusammenfassung (lokale AI mit kleinen Modellen) ==

Man sollte sich keinen Illusionen hingeben: eine lokale AI mit ein paar Milliarden floats (oder gar 4bit quantized) kann nicht im geringsten mit
einem Modell mit Billionen Werten mithalten (i.e. Claude oder ChatGPT oder einem hauseigenen großen Rechenzentrum mit ein paar 10000 NVidia GPUs).

Hier ein chat mit lokalem llama3.2:3b (3 Milliarden floats, bf16):
--- user ---
how ´would you open an expecco app using mcp

''ich frage wie er unsere mcp Anbindung aufrufen würde (große Modelle von Anthropic oder OpenAI würden hier korrekt antworten)''

```
MCP.openApp("type://com.expeccotech.app.name", null);
```

Replace `"type://com.expeccotech.app.name"` with the specific type identifier for your app. This might be a URI or a project handle.

This command will open the Expecco app using MCP, and it may prompt you to authenticate or authorize if necessary.

Here's an example of how you could use this method in Python:

```python
import mcpsys

app = mcpsys.MCP()
app.openApp("type://com.expeccotech.app.name", None)
```

In JavaScript, you can also use this method with the following code:

```javascript
var app = new MCP();
app.openApp("type://com.expeccotech.app.name", null);
```

''das ist natürlich völliger Unsinn; man könnte sagen: er saugt sich das aus den Fingern; sagen wir ihm das:''

--- user ---
you just made this all up. you are wrong. do not hallucinate. what mcp tools do you really have at hand

--- assistant ---
I got a bit carried away with my imagination.

To be honest, I don't actually have any MCP (Model Computing Platform) tools or knowledge at hand. I'm an AI trained on general knowledge and can only provide information based on my training data.

MCP is a specific framework developed by the University of Michigan, and it seems that I was not properly informed about its capabilities and tools. If you'd like to correct me or provide more information about MCP, I'll do my best to learn from it!

''aha - er gibt es zu!''

== LLaMa.cpp ==

Installation siehe Webseite.

Kommando:
llama-server.exe -hf unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:Q4_K_M --cts-size XXXX

Hinweis: per default, verwendet llama.cpp nur ein Contextfenster von 4096. Das ist zu wenig für sinnvolle Aufgaben. Starten Sie llama.cpp mit --ctx-size 8192 oder 16384,32768 oder 65536. Die unterstützte Größe hängt vom Modell ab. Ein großer Context hat natürlich Einfluß auf Speicherbedarf (VRAM in GPU, RAM in CPU) und Antwortzeit. Wenn Sie genug CPU VRAM bzw. RAM haben, ist es in jedem Fall besser, eine größere Contextsize zu setzen.

Das Modell läuft auf der lokalen CPU (Laptop, ohne GPU), und zeigt dabei durchaus gute Antworten (wenn man Geduld hat). Zugegeben, wir haben auch einiges an Wissen in den Speicher vorgepackt.

Im expecco Chat Fenster:
open an exepcco browser on a new project
macht er!
create a python action to compute the area from given radius
er legt eine korrekte Pythonscript Aktion an. Chapeau. Sogar die Behandlung der Ein- und Ausgangspins, die bei Scriptaktionen etwas umständlich ist, hat er gemeistert.

again, as Smalltalk action
braucht etwas, aber er reagiert auf Syntaxfehler, korrigiert sich. Danach führt er die Aktion zur Verifikation aus. Ausgabe: 
''Verified: for `radius = 5.0`, `area = 78.5398163397448` — same result as the Python version.''

Die Frage wie man einen String (z.B. 'helloworld') zerlegt geht er systematisch an - er sucht im laufenden expecco nach Stringfunktionen. Das dauert



== Wahl der Modellgrösse ==

=== Übersetzung ===
Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In keinem Fall sollte man der KI "blind" vertrauen.

=== Arbeit mit Expecco ===
Um das Modell tatsächlich Code oder Aktionen erzeugen zu lassen reichen die
einfachsten Modell NICHT;
Hier eine vorläufige Liste unserer Resultate:

* qwen2.5-coder:3b definitiv zu dumm
* qwen2.5-coder:7b nach einigen Verbesserungen an den initialen Anweisungen zum Gebrauch der expecco tools kann das Model: Browser öffnen, Projekt anlegen. Achtung: benötigt contextSize=8192; mit 4096 ist es zu vergesslich
*
[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

Release Notes 26.x

2026-07-29T07:29:49Z

Sv: 26.2: AI Coding - Claude Code (subscription) provider; Explain Class / Generate Class Documentation

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==
* Feature: bridged Scheme (currently only Racket Scheme) action blocks
* Feature: bridged Octave/Matlab action blocks
* Feature: bridged C# action blocks
* Feature: '''NEW''' AI Coding provider "'''Claude Code (subscription)'''" — uses your existing Claude subscription via the locally installed ''Claude Code'' command line program instead of an API key, so no key has to be entered and no per-token API charges are billed. Choose it like any other provider in the settings dialog (Plugins → AI Coding); the API key, endpoint URL and proxy fields are hidden for it because they do not apply, and the authentication method reads "Subscription (external login)". It requires ''Claude Code'' to be installed and logged in once (run <code>claude</code> in a terminal and complete the login). The model is selectable either as a tier alias (''sonnet'', ''opus'', ''haiku'' — always the current model of that tier) or as a pinned model id.
* Feature: two new AI actions that work on the selected '''class''' rather than on a single method, reachable from the '''AI''' menu of the class browser: "'''Explain Class'''" explains the class as a whole — what it is responsible for, what its instance variables hold and how its protocols fit together — and "'''Generate Class Documentation'''" proposes a class documentation text which the "[Apply]" button installs into the class' documentation.

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports '''Anthropic Claude''', '''OpenAI ChatGPT''', '''ollama''' and others as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via [[Tools_FileBrowser/en|FileBrowser]])
* Feature: public/private keypair generation via a [[Tools_FileBrowser/en|FileBrowser]] menu (for easy SSH setup)
* Improvement: Bundled python3 installer updated to version 3.13.14
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed the [[Number_API_Functions|Number]] stack (see also in [[Numeric_Limits/en| Numeric Limits]]):
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. and type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan). Now all test cases produce a result within the precision limits of their type
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]]
* UI: '''Ctrl-Return''' now accepts the default action in every modal dialog — both the modern SimpleDialog-based ones (check-in log message, search dialogs, ...) and old-style DialogBox-based ones (EnterBox, OptionBox, InfoBox, ...). Unlike plain Return, Ctrl-Return submits the dialog even when the focus is on a multi-line text editor (which normally keeps Return as a newline), so there is no need to tab off the editor first.
* UI: Transcript (the console) always appends text at end.
* UI: Transcript does not scroll to end on incoming text while moving the scrollbar
* Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
* Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
* Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Performance: speedup of cryptographic algorithms (affects key generation and other)
* Performance: tuned loading of stored ets/elf files (30-40% speedup)
* Performance: further speedup when loading test-result archives that embed large execution logs — typical load is roughly a third faster again

Release Notes 26.x

2026-07-21T14:42:04Z

Sv: Release 26.1: add Ctrl-Return default-button UI entry

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==
* Feature: bridged Scheme (currently only Racket Scheme) action blocks
* Feature: bridged Octave/Matlab action blocks
* Feature: bridged C# action blocks

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports '''Anthropic Claude''', '''OpenAI ChatGPT''', '''ollama''' and others as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via [[Tools_FileBrowser/en|FileBrowser]])
* Feature: public/private keypair generation via a [[Tools_FileBrowser/en|FileBrowser]] menu (for easy SSH setup)
* Improvement: Bundled python3 installer updated to version 3.13.14
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed the [[Number_API_Functions|Number]] stack (see also in [[Numeric_Limits/en| Numeric Limits]]):
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. and type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan). Now all test cases produce a result within the precision limits of their type
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]]
* UI: '''Ctrl-Return''' now accepts the default action in every modal dialog — both the modern SimpleDialog-based ones (check-in log message, search dialogs, ...) and old-style DialogBox-based ones (EnterBox, OptionBox, InfoBox, ...). Unlike plain Return, Ctrl-Return submits the dialog even when the focus is on a multi-line text editor (which normally keeps Return as a newline), so there is no need to tab off the editor first.
* UI: Transcript (the console) always appends text at end.
* UI: Transcript does not scroll to end on incoming text while moving the scrollbar
* Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
* Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
* Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Performance: speedup of cryptographic algorithms (affects key generation and other)
* Performance: tuned loading of stored ets/elf files (30-40% speedup)
* Performance: further speedup when loading test-result archives that embed large execution logs — typical load is roughly a third faster again

KI Coding Plugin

2026-06-19T13:11:46Z

Sv: add AI Coding license-feature note at top

= KI Coding Plugin =

Die hier beschriebenen KI-Funktionen sind Teil des Lizenz-Features '''AI Coding'''. Ist dieses Feature in Ihrer Lizenz nicht enthalten, erscheinen die ''Ask AI''-Menüeinträge zwar weiterhin sichtbar in den Editor-Toolbars, sind aber deaktiviert (Tooltip: "Install the AI coding plugin to enable").

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic Claude''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI ChatGPT''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
Zusätzlich gibt es noch einen weiteren Eintrag '''Inhause'''; dieser ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe OpenAI chatGPT Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren mit beiden Anbietern; bei
OpenAI nur mit vision-fähigen Modellen (gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic oder OpenAI. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.
* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.
* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.
* '''Max output tokens''' — maximale Antwortlänge.
* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>. Es gibt keinen eXept-seitigen Proxy oder
Zwischenspeicher. Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Sub-Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell
als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens - wie hier der Fall - werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, daß die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind.

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Coding Assistenten ==

Beim Start der MCP-Server-Anbindung trägt expecco die nötigen Konfigurationseinträge automatisch in die Config-Dateien der unterstützten Coding-Assistenten ein. Die folgenden Abschnitte beschreiben Ort und Format der jeweiligen Einträge — zur Information bzw. falls Sie sie manuell ergänzen oder kontrollieren möchten.

=== Claude Code ===
Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"smalltalk": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp/expecco"
}
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls im typischerweise Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"smalltalk": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollten die beiden aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

=== Erfahrungen und Tipps für die Arbeit ===

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen - es sei denn sie dienen der Entscheidung - weg. Tatsächlich erhöhen sie den Tokenverbrauch u.U.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (z.B. ollama) ==

Erste Versuche sind eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Wahl der Modellgrösse ==

Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In jedem Fall darf man der KI nicht "blind" vertrauen.

[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

KI Coding Plugin

2026-06-19T12:44:39Z

Sv: note that config entries are written automatically on MCP server start

= KI Coding Plugin =

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic Claude''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI ChatGPT''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
Zusätzlich gibt es noch einen weiteren Eintrag '''Inhause'''; dieser ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe OpenAI chatGPT Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren mit beiden Anbietern; bei
OpenAI nur mit vision-fähigen Modellen (gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic oder OpenAI. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.
* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.
* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.
* '''Max output tokens''' — maximale Antwortlänge.
* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>. Es gibt keinen eXept-seitigen Proxy oder
Zwischenspeicher. Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Sub-Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell
als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens - wie hier der Fall - werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, daß die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind.

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Coding Assistenten ==

Beim Start der MCP-Server-Anbindung trägt expecco die nötigen Konfigurationseinträge automatisch in die Config-Dateien der unterstützten Coding-Assistenten ein. Die folgenden Abschnitte beschreiben Ort und Format der jeweiligen Einträge — zur Information bzw. falls Sie sie manuell ergänzen oder kontrollieren möchten.

=== Claude Code ===
Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"smalltalk": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp/expecco"
}
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls im typischerweise Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"smalltalk": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollten die beiden aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

=== Erfahrungen und Tipps für die Arbeit ===

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen - es sei denn sie dienen der Entscheidung - weg. Tatsächlich erhöhen sie den Tokenverbrauch u.U.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (z.B. ollama) ==

Erste Versuche sind eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Wahl der Modellgrösse ==

Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In jedem Fall darf man der KI nicht "blind" vertrauen.

[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

KI Coding Plugin

2026-06-19T12:39:15Z

Sv: add Cursor and Zed sections; fill in Tabnine stub (MCP HTTP setup)

= KI Coding Plugin =

Das KI Coding Plugin bindet einen Large Language Model (LLM) basierten
KI-Assistenten in den Activity-Editor (Aktivitäten-Code), den
Compound-Netzwerk-Editor, den Dokumentations-Editor und in den
ST/X Class Browser ein. Das Plugin unterstützt mehrere Anbieter, die im
Einstellungsdialog umschaltbar sind:

* '''Anthropic Claude''' (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)
* '''OpenAI ChatGPT''' (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o1, o3)
* '''Ollama''' lokal oder remote (codellama:7b, codellama:13b)
Zusätzlich gibt es noch einen weiteren Eintrag '''Inhause'''; dieser ist für eigene, firmeninterne KI vorgesehen.
:: Anm.: tatsächlich sprechen all hinterher das selbe OpenAI chatGPT Protokoll; sie können also auch unter irgend einem anderen Anbieter einfach die URL zu ihrer eignene KI eingeben. Dieser Eintrag dient also lediglich der Übersichtlichkeit, und einem Platz wo Sie Ihre Zugangsdaten ablegen können, wenn Sie doch noch zwischen durch mit anderen Anbietern chatten können und wollen ohne jedesmal die URLs und API keys neu eingeben zu müssen.

Je nach gewähltem Anbieter erscheint die Toolbar-Schaltfläche als
<code>Ask Claude</code> bzw. <code>Ask ChatGPT</code> bzw. <code>Ask ...</code> ; das Einstellungs-Tab
heißt "<code>AI Coding</code>", unter Plugins (Erweiterungen).

== Aktivitäten-Editor ==

Im Aktivitäten-Code-Editor erscheint in der Toolbar eine Schaltfläche
<code>Ask Claude</code> / <code>Ask ChatGPT</code> mit folgenden Aktionen:

* '''Open KI Window''' — öffnet das eigenständige Chat-Fenster
* '''Explain code''' — erklärt den Code der aktuellen Aktivität
* '''Suggest improvement''' — schlägt Verbesserungen vor
* '''Find bugs''' — sucht nach Fehlern, Race Conditions, nil-Handling-Problemen
* '''Generate doc-comment''' — generiert eine Aktivitäts-Dokumentation inklusive Pin-Kommentaren und füllt den Documentation-Tab
* '''Custom prompt...''' — freier Prompt; der Aktivitäts-Code wird als Kontext mitgesendet
* '''Set model''' ▸ — Untermenü mit den Modellen des aktiven Anbieters (das aktuell aktive Modell ist mit ''(active)'' markiert)
* '''Set provider''' ▸ — nur sichtbar, wenn API-Schlüssel für mehr als einen Anbieter konfiguriert sind; Untermenü zum Umschalten zwischen Claude, ChatGPT oder anderem Anbieter

Code-Vorschläge können mit <code>[Apply]</code> (direkt am jeweiligen
Code-Block im Chat oder über die obere Apply-Schaltfläche) in den
Aktivitäts-Body übernommen werden. Vom KI gelieferte Smalltalk/X
Hilfsmethoden (Form: <code>Klasse >> selector</code>) werden nach
Rückfrage in die genannte Klasse compiliert.

== Compound (Netzwerk) Editor ==

Auf der Toolbar von Compound-Worksheets erscheint dieselbe
Schaltfläche, beschränkt auf die für Netze sinnvollen Aktionen
(''Open KI Window'', ''Generate doc-comment'') — ebenfalls mit den
Untermenüs ''Set model'' und ggf. ''Set provider''.

== Dokumentations-Editor ==

Der Dokumentations-Tab der Block-Description (Editor für Test-Cases,
Test-Plans und Aktivitäten) trägt dieselbe Toolbar-Schaltfläche
<code>Ask ...</code> mit den obigen Einträgen
''Generate doc-comment'' analysiert den aktuellen Block (Name,
vorhandene Beschreibung, Eingangs-/Ausgangs-Pins, Sub-Steps eines
Compound-Netzes, referenzierte Environment-Variablen) und schlägt
eine vollständige Block- und Pin-Dokumentation vor.

Ist der Block schreibgeschützt (importierte Library, RTL-Lizenz),
fragt <code>[Apply]</code> nach, ob der Block freigeschaltet und die
Dokumentation eingetragen werden soll.

== Class Browser (ST/X) ==

Im Class Browser stehen die Aktionen unter dem '''AI'''-Untermenü
sowie im Selektor-Kontextmenü zur Verfügung. Die Aktionen
operieren auf der aktuell ausgewählten Methode (Klasse + Selektor +
Quelltext werden als Kontext mitgesendet). '''[Apply]''' kann das
Resultat direkt in die Methode der aktiven Klasse einbauen.
Auch hier sind '''Set model''' und ggf. '''Set provider''' als
Untermenüs verfügbar.

== Chat-Fenster ==

Das eigenständige Chat-Fenster trägt den Titel
'''AI Coding [<Produkt> / <Modell>]''' (z.B.
"AI Coding [Claude / claude-opus-4-7]") und zeigt nach jedem Turn
den Tokenverbrauch und die kumulierten Kosten — sofern Preise für
das gewählte Modell hinterlegt sind. Anbieter- und Modellwechsel
im Einstellungsdialog werden live übernommen.

Das Transkript ist als vertikales Panel von "Karten" aufgebaut:

* '''Prosa-Karten''' enthalten den fließenden Text der Antwort; Zeilen werden auf die Fenster-Breite umgebrochen.
* '''Code-Karten''' (eingerahmt) entstehen aus markdown-Code-Blöcken (<code>```...```</code>) und sind als '''Workspace''' editierbar — das Standard-Smalltalk-Popup-Menü bietet doIt / printIt / inspectIt, ein <code>TestCase</code>-<code>simulatedSelf</code> ist gesetzt, so dass <code>self assert:... equals:...</code> direkt ausgeführt werden kann. Lange Blöcke scrollen innerhalb der Karte. Rechts oben sitzen die Schaltflächen '''[Apply]''' (sofern für den Kontext sinnvoll) und '''[⎘ Copy]'''; links wird der Sprachtag (smalltalk, python, …) angezeigt.
* '''Doku-Karten''' (volle Breite, Prosa) entstehen aus dem speziellen <code>```doc</code>-Block, den der Dokumentations-Generator anfordert; Inhalt ist die Vorschlags-Dokumentation für Block- und Pin-Beschreibungen.

Scroll-Lock: solange der Anwender bereits am unteren Ende des
Transkripts steht, folgt die Anzeige neu eintreffenden Karten
automatisch; nach manuellem Hochscrollen bleibt die Position stehen.

Bilder können als Anhang versendet werden (Screenshot oder
PNG/JPG-Datei). Anhänge funktionieren mit beiden Anbietern; bei
OpenAI nur mit vision-fähigen Modellen (gpt-4o-Familie).

== Einstellungen (AI Coding) ==

Im Einstellungsdialog unter '''Plugins → AI Coding''' (bzw. unter
'''Tools → AI Coding''' im Smalltalk-Launcher) werden konfiguriert:

* '''Provider''' — Anthropic oder OpenAI. Beim Wechsel werden API-URL und Default-Modell entsprechend angepasst; der gespeicherte API-Schlüssel des jeweiligen Anbieters wird geladen.
* '''API Key''' — Schlüssel des aktuell gewählten Anbieters. Die Schlüssel werden pro Anbieter getrennt gespeichert (<code>#claudeApiKey_anthropic</code> bzw. <code>#claudeApiKey_openai</code>), so dass zwischen den Anbietern ohne erneute Eingabe gewechselt werden kann. Das Setzen des Schlüssels erfolgt ausschließlich über diesen Dialog.
* '''Model''' — ein Modell aus der Liste des aktiven Anbieters oder ein selbst eingegebener Modellname. Kann auch direkt über das '''Set model'''-Untermenü in den Editor-Toolbars umgeschaltet werden.
* '''Max output tokens''' — maximale Antwortlänge.
* '''API URL''' — nur zu ändern für eigene Proxies / Gateways. Standard: <code>https://api.anthropic.com/v1/messages</code> bzw. <code>https://api.openai.com/v1/chat/completions</code>.

== API-Schlüssel beschaffen ==

* Anthropic: [https://console.anthropic.com console.anthropic.com], Schlüsselformat <code>sk-ant-...</code>.
* OpenAI: [https://platform.openai.com/api-keys platform.openai.com/api-keys], Schlüsselformat <code>sk-...</code> oder <code>sk-proj-...</code>. Voraussetzung ist ein aufgeladenes Konto (Mindestbetrag derzeit USD 5).

== Datenschutz / Datenfluss ==

Bei aktivem Anbieter '''Anthropic''' gehen die Anfragen direkt an
<code>api.anthropic.com</code>, bei '''OpenAI''' direkt an
<code>api.openai.com</code>. Es gibt keinen eXept-seitigen Proxy oder
Zwischenspeicher. Mit dem Aktivitäts-Quelltext bzw. den Methoden-
Quelltexten werden auch Pin-Beschreibungen, Sub-Step-Namen und
referenzierte Environment-Variablen aus dem Block-Description-Modell
als Kontext versendet.

Bei Benutzung von Anthropic API-Tokens - wie hier der Fall - werden laut Anthropic die Daten nicht zum Training des KI-Modells genutzt ([https://privacy.claude.com/de/articles/7996868-werden-meine-daten-fur-das-modelltraining-verwendet Anthropic Erkärung dazu]). Für die Wahrheit dieser Aussage können wir nicht garantieren und haften. Zu bedenken ist auch, daß die KI-Modelle nicht in inländischen Rechenzentren laufen, und eventuell weitere "Mitleser" involviert sind. Dies gilt insbesondere für Hightech, KI, Software und Defence Unternehmen, wo Fälle von Wirtschaftsspionage bekannt sind.

⚠ Wenn Sie sicher sein wollen, daß keine Information Ihr Haus verlässt empfehlen wir eine eigenem geschlossene in-House KI Umgebung, wie sie bei einigen unserer Kunden bereits existiert. Sie dürfen dann selbstverständlich nur die URLs dieser Umgebung konfigurieren. Expecco kommuniziert ausschließlich mit der von Ihnen eingegebenen KI.

== Coding Assistenten ==

=== Claude Code ===
Einträge für den mcp-server werden von expecco in die <code>".claude.json</code> Datei (typischerweise in Ihrem Homeverzeichnis) vom Einstellungsdialog eingebracht:
...
"mcpServers": {
"smalltalk": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"type": "http",
"url": "http://127.0.0.1:9876/mcp/expecco"
}
},
...
danach sollte nach dem Start von "claude.exe" diese mit dem <code>/mcp</code> Kommando gelistet werden.

=== Opencode (mit Zen) ===

Nach der Anmeldung (opencode authlogin) starten Sie opencode erneut. Aktuell müssen die mcp in einem Editor von Ihnen konfiguriert werden (autom. Eintrage in einer späteren Version. Ändern Sie dazu die Datei "<code>.config\opencode\opencode.jsonc</code>" (ebenfalls im typischerweise Heimatverzeichnis) zu:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"smalltalk": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"type": "remote",
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}

Sollten Sie ein Komma vergessen haben wird beim Start eine Fehlermeldung erscheinen. Mit "/mcps" sollten die beiden aufgelistet werden.

=== Cursor ===
Cursor liest seine MCP-Konfiguration aus <code>~/.cursor/mcp.json</code> (Windows: <code>%USERPROFILE%\.cursor\mcp.json</code>). Ergänzen Sie dort:
{
"mcpServers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}
Beim nächsten Start von Cursor sollten die Server unter <code>Settings → MCP</code> als ''connected'' erscheinen.

=== Zed ===
Zed liest seine MCP-Konfiguration aus <code>~/.config/zed/settings.json</code> (Windows: <code>%APPDATA%\Zed\settings.json</code>). Der Eintrag steht unter dem Schlüssel <code>context_servers</code> (nicht <code>mcpServers</code> wie bei den anderen):
{
"context_servers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}

=== Tabnine ===
Tabnine sucht seine MCP-Konfiguration zuerst projektbezogen unter <code><Projekt>/.tabnine/mcp_servers.json</code>, dann im Homeverzeichnis (<code>~/.tabnine/mcp_servers.json</code>, Windows: <code>%USERPROFILE%\.tabnine\mcp_servers.json</code>):
{
"mcpServers": {
"smalltalk": {
"url": "http://127.0.0.1:9876/mcp"
},
"expecco": {
"url": "http://127.0.0.1:9876/mcp/expecco"
}
}
}
Alternativ können Sie den Server auch direkt im Tabnine-IDE-Plugin über <code>☰ → ⛭ Settings → Tools and MCPs → MCP servers → + Add MCP server</code> eintragen.

== Tipps ==

* '''Mehrere Konversationen''': der Chat ist ein Singleton — eine neue Anfrage über ein Browser-/Editor-Menü startet jedesmal eine '''neue''' Konversation. Folge-Fragen (Klärung, Vertiefung) gehen über das Eingabefeld in derselben Konversation.
* '''Vorsicht:''' Die Größe der übertragenen Daten (auch die aus dem Chatfenster) geht in die Kostenberechnung ein. Deshalb immer eine neue Konversation starten, wenn es um ein neues Thema geht.
* '''Modell wechseln''': Für schnelle Routine-Antworten Haiku oder Sonnet, für schwierige Refactorings Opus. Über das '''Set model'''-Untermenü direkt aus der Toolbar oder über die Settings.
* '''Anbieter wechseln''': Sind Schlüssel für beide Anbieter konfiguriert, schaltet das '''Set provider'''-Untermenü ohne Umweg über den Settings-Dialog um.
* '''Code direkt ausführen''': In Code-Karten kann markierter Smalltalk-Code per doIt / printIt / inspectIt direkt evaluiert werden — praktisch z.B. um vom Modell vorgeschlagene SUnit-Asserts gleich auszuprobieren, ohne den Code erst in einen Workspace zu kopieren.
* '''Custom prompt''' eignet sich gut für „warum macht Methode X es so und nicht so?" oder „schreib mir einen ParameterizedTest dazu mit folgenden Daten: …".

== Tipps für die Arbeit mit claudeCode ==
Wenn Sie ClaudeCode oder Opencode verwenden, stehen ihnen noch weit mehr Funktionen zur Verfügung: sie können zum Beispiel im claudeCode Terminal eingeben:
* "mach mir eine neue Suite in einem neuen Fenster",
* "Mache eine Aktion zur Berechnung des Umfangs eines Kreises bei gegebenen Radius",
* "Erstelle eine neue Suite mit einem Testfall der folgendes macht:
** 1) webbrowser auf "www.exept.de" öffnen.
** 2) auf das logo oben links klicken.
** 3) webbrowser schliessen.
* welche Funktionalität ist in xxx.ets

(Anm.: es spielt keine Rolle, ob Sie sich in Deutsch oder Englisch unterhalten)

Claude wurde von uns in die Lage versetzt, selbst nach passenden Bibliotheken zu suchen, diese zu importieren, Aktionen zu generieren und den Testplan anzulegen.

Tatsächlich auch, den Test gleich durchzuführen und das Resultat zu analysieren.

Aktuell sind wir am trainieren, so dass claude z.B. selbst entscheidet ob es besser ist, eine fehlende Aktion als Diagramm oder elementa zu definieren. Es ist in der Lage, die Funktionen des unterliegenden Frameworks zu sehen und auch komplexe Aufgaben zu erledigen:
* "Aktion zum Lesen der Jahresumsätze eines Jahres aus der Datenbank"
* extrahiere aus dem xml Dokument alle budget Einträge und liefere die Summe

=== Erfahrungen und Tipps für die Arbeit ===

==== Modellwahl; Sonnet, Heiku und Fable ====
Sonnet-4 ist gefühlt weit intelligenter als Heiku-4.5,
aber auch weit teurer. Fable ist für sehr komplexe Aufgaben, aber sehr teuer (ich meine: wirklich teuer). Ihr Budget kann sehr schnell schmelzen mit Sonnet - insbesondere wenn man auf medium oder high Intelligenzlevel arbeitet. Haiku macht weit mehr Fehler und man sollte genau hinschauen was er so generiert. Gefühlt war Sonnet selbst im low level besser als Haiku. Aber der Preis...
Noch besser ist Fable, aber extrem teuer; in einer halben Stunde kann da schon mal das Tagesbudget an Tokens verbraucht werden.

Folgende konkrete Tipps aus unseren ersten Erfahrungen, diese Liste wird aktualisiert, und kann auch basieren auf unserer eigenen Dummheit. Ist also u.U. mit Vorsicht zu genießen.

* geben Sie Haiku mehr Hinweise, z.B. "schau mal dort, oder nimm das als Beispiel". Sonnet findet selbst viel besser Lösungen.

* kurze Anweisungen, je konkreter desto günstiger.

* Haiku ist weit "fauler". Z.B hat sonnet automatisch eine Dokumentation bei neuen Aktionen angelegt, und diese auch aktualisiert. Haiku hingegen musste man explizit eine Regel dazu anlegen (z.B. mit "wenn du eine Aktion anlegst oder änderst, aktualisiere die Dokumentation")

* Heiku ist dümmer. Regeln die von Sonnet angelegt wurden, können von Haiku u.U. nicht befolgt werden, weil Sonnet weit mehr generalisieren kann.

* sagen Sie allen sie sollten wenn sie ein Problem haben, nicht lange selbst suchen. sondern nachfragen ob man ihnen einen Tipp geben kann. Wenn Sie das nicht tun, kann es sein dass Sonnet auch eine viertel Stunde nachdenkt und die Dollars schmelzen wie Eis in der Sonne (ist mir passiert, als ein Socket Problem in der Kommunikation auftrat, und er nicht erkannte, das die Antworten von mcp falsch waren, es hat dann selbst alle möglichen Wege gesucht, eine Nachricht abzusetzen, incl. der Erstellung diverser Shell, curl und Python Scripte... obgleich es eigentlich ein Interface dafür gab, das aber einen Fehler hatte). Insbesondere hatte ich dummerweise vorher sinngemäß gesagt er solle, wenn ein Problem auftritt dies und jenes tun, wobei dabei genau dieses Problem wieder auftrat...

* schränken Sie das Modell in seinen Möglichkeiten ein, z.B. sagen sie "editiere nicht die files sondern verwende dazu ein tool", oder "eine expecco Aktion und sag mir vorher welche du nimmst". Sonst kann es passieren dass es anfängt ihre ets zu entpacken um darin nach Strings zu suchen, obgleich es das eigentlich einfacher über das interface machen kann (dieses konkrete Problem wird nicht mehr auftreten aber Sie sehen den Punkt). Da war Sonnet weit intelligenter hat aber auch länger nachgedacht.

* wenn sie feststellen, dass es einen Fehler macht, sagen sie (mehr oder weniger wörtlich) "remember: mach dies nicht, oder um das zu machen tu das."

* sie können diese Erinnerungen sowohl in ihrem UserProfile (also im lokalen Filesystem) als auch in ihren expecco Präferenzen halten. Sagen Sie dazu "remember this in in my expecco preferences" oder "remember (in my user memory): bla bla". Erinnerungen kann man auch löschen "forget to ...". Zu Beginn der nächsten Session sagen sie "read the expecco preferences memory".

* wechseln sie das Modell oder den level, je nach Komplexität der Aufgabe. Aber bedenken Sie dass Wissen von Session zu Session verloren geht, wenn es nicht erinnert wird. Technisch sind Erinnerungen nichts anderes als das Lesen einer Liste der vormaligen remember Anweisungen. Kosten also auch Tokens. Sie könnten also die Erinnerungen auch einfach neu eintippen ;-)

* Fable ist ein echter Star, wenn es darum geht, z.B. eine komplexe Architektur zu entwerfen. Mein Tipp: lassen sie ihn einen Plan machen, und von einem einfacheren Modell Schritt für Schritt umsetzen.

* auch wenn es so scheint: das "Ding" ist kein Mensch; lassen sie "bitte, danke, oder Begründungen - es sei denn sie dienen der Entscheidung - weg. Tatsächlich erhöhen sie den Tokenverbrauch u.U.

Subjektive Zusammenfassung:
* Haiku ist viel schneller in der Antwort und kostet ein Zehntel. Mit Sonnet war nach 3-4 Std Arbeit mein Limit erreicht und ich durfte Stunden Pause machen. Mit Fable kann schon nach 1/2 Stunde die Zwangspause erzwungen werden. Mit Haiku kann man durcharbeiten. Aber ich brauche auch mindestens doppelt so viel Zeit um Haiku anzuleiten und seine Fehler wieder auszubügeln.

== Was kann eine lokale KI (z.B. ollama) ==

Erste Versuche sind eher ernüchternd. Ohne Zugriff auf lokale Quellen 1), mit rein antrainiertem Wissen sind die Modelle vermutlich zu klein. Hier eine Konversation mit gemma3:8b-it-qat (8 Mrd, quantifiziert) auf einem Rechner ohne GPU.
Die Antwortzeiten sind natürlich schlecht, aber mit einer GPU u.U. brauchbar. Wenn Sie im Haus Zugriff auf Rechner mit GPU haben sollten Sie diese unbedingt nutzen (mit möglichst viel RAM, damit die Modelle auch hineinpassen!)

Wichtig: wir sind selbst noch Anfänger und keine [https://en.wikipedia.org/wiki/Susan_Calvin KI Psychologen].
Aber die Erfahrungen werden aktuell in einem Feintuning Prozess in die nächste Release eingebracht.

1) z.B. über mcp tools, welche wir in der aktuellen Version für claudeCode bereits implementiert haben.

=== Installation ===
install ollama
ollama pull gemma3:8b-it-qat ;; gemma3:8b / gemma3:12b usw.
ollama run gemma3:8b-it-qat

=== Sitzung 1 ===
Hinweise: Wichtig, sonst labert Sie das Modell voll!

>>> respond short and concise
Understood

Hinweise: Smalltalk/X wissen hat er nicht, aber VW und Pharo sind ähnlich genug.

>>> you are an expert in smalltalk programming, especially in Smalltalk/X, visualworks and Squeak.

You have come to the right place I have a considerable depth of knowledge regarding Smalltalk...
Angeber- wir werden sehen

>>> what does the smalltalk expression "self at:4 put:'bla' " mean

Sets the character 'b' at index 4 of `self` (assuming `self` is a string).
Falsche Antwort; Smalltalk verwendet 1-basierte Indices, und 'bla' ist ein String

>>> how to compute the area of a circle given radius

```smalltalk
| radius area |
radius := 5.0.
area := radius * radius * PI.
^area
```
nicht schlecht. PI gibt es zwar nicht als globale Variable (richtig wäre "Float pi"), aber dennoch bemerkenswert.

>>> how to extract a substring

`substring:startIndexToEndIndex` (inclusive). E.g., `"hello" substring:2 to:4` yields `"llo"`.
wieder falsch; 1-basierter index, substring:to: möglicherweise in einem anderen Smalltalk vorhanden. Könnte man durchgehen lassen.

>>> alternative?

`copyFrom:to:` (indexes inclusive). `string copyFrom:1 to:3` gives `"ell"`.
besser, aber immer noch falscher Index

>>> what is the result of 'hello' copyFrom:2 to:4

"llo"
war zu erwarten

>>> smalltalk uses 1 based indexing. what is the result

Correct. The result of `'hello' copyFrom:2 to:4` is `"llo"`.
soso. Er sieht ein, dass ich korrigiert habe - dann aber dickköpfig.

>>> in smalltalk the first index is 1 the last is the collection's size. Not as in Python or C.

Precisely. 1-based indexing is core to Smalltalk.
aha, er könnte es wissen; es fehlt ihm aber offensichtlich an Abstraktionsvermögen. Versuchen wir es mit einem Beispiel:

>>> remember: the result of 'hello' copyFrom:2 to4 is 'ell'

You are absolutely right! My apologies. `copyFrom:to:` includes both endpoints, so `'hello' copyFrom:2 to:4` results in `"ell"`. Thanks for the correction. I am still under development and learning nuances like this.
soso, eine Nuance. Und eigentlich hatte ich gesagt, er solle kurz und exakt antworten. Die Entschuldigungen kann er sich sparen. Mal sehen:

>>> >> what is the result of 'abcde' copyFrom:2 to:4

"bcd"
na also; geht doch.

=== Sitzung 2 ===

Neuer Versuch; eine neue Session. Gib ihm Grundwissen, das er nicht im Modell hat.
/clear
>>> answer short an concise
Okay.

>>> you are expert in smalltalk programming, especially smalltalk/x, visualworks and pharo

Acknowledged. I'm ready to leverage my knowledge of Smalltalk (including Smalltalk/X, VisualWorks, and Pharo) to assist you. Ask away!

>>> remember: because smalltalk is 1-based indexing, the result of 'hello' copyFrom:2 to4 is 'ell'

Understood. I will keep in mind Smalltalk's 1-based indexing when answering your questions about string manipulation and other operations

>>> what is the result of 'abcde' copyFrom:2 to:4

'bcd'
richtig! 
Hätte ich hinzufügen müssen, daß das nicht nur für Strings gilt? Mal sehen:

>>> given Array #(10 20 30 40) what is the result of array at:3

30
richtig!

Man muss den Kontext also mit Wissen füllen (oder fein tuning, wozu aber unsere GPU vermutlich nicht in der Lage ist), dann kommt durchaus sinnvolles heraus. Wir sind dran, das zu evaluieren damit möglicherweise sogar eine lokale KI (allerdings mit GPU) hilfreich unterstützen kann.

=== Versuche mit qwen2.5-coder:7b ===
Dieser zeigt erstaunlich gute Antworten auf unserer lokalen ollama installtaion mit einer (nach heutigem Maßstab) durchschnittlichen GPU (Preis heute ca. 1500.-)

== Wahl der Modellgrösse ==

Versuche mit gemma3:270m (sehr klein; 270Mio), gemma3:1b (1 Mrd) und gemma3:4b (4 Mrd). Alle auf lokalem Rechner ohne GPU (was keinen Einfluss auf die Antwort hat, aber die Antwortzeit bestimmt).

Versuch: Übersetzung einer Bausteindokumentation.

Eingabe: translate to German:
"show a dialog with an informationstring"

Die 270m und 1b Modelle kennen das Geschlecht nicht; sie drücken sich etwas ungeschickt aus:

"Zeigen Sie eine Dialoge mit einer Informationsstring"

Alternativen:
"Zeige einen Dialog mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."
"Zeige eine Dialoge mit einer Informationsstring."

bzw (1Mrd).
"Zeig eine Dialog mit einem Informationsstring"

Alternativen:
"Gib ein Dialog mit einem Informationen-String aus"
"Zeige einen Dialog, der eine Informations-Stränge enthält"

Das 4Mrd Modell scheint brauchbar:
"Zeige einen Dialog mit einer Informationsnachricht"

Alternativen:
"Erstelle ein Dialogfenster mit einer Informationsanzeige"
"Zeige ein Dialogfeld mit einer Informationen"

In jedem Fall darf man der KI nicht "blind" vertrauen.

[[Kategorie:Plugin]]
[[Kategorie:Erweiterung]]

Remote Access/en

2026-06-08T14:26:29Z

Sv: password authentication: URL form, code API, auth order; launcher menu entries

{{Languages|Remote Access/en|label=English}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation in <code>exept:libcrypt/ssh</code>; no external dependency on OpenSSL or libssh. Use this for anything that touches credentials or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine. Used for local-tool integration and for the local end of a remote workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No encryption, passwords on the wire in clear. Use only when the target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code> subclass that lets the rest of ST/X treat a remote SFTP path the same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user[:password]@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>. The optional <code>:password</code> piece is the
RFC-3986-style userinfo password — see
[[#Password authentication]] for when this is appropriate and what
the security trade-offs are. When present, it is used as a USERAUTH
fallback after the normal publickey/agent attempts and is '''never'''
re-emitted by the printable URL form, so logging the filename does
not leak the credential.

The '''Refresh''' button in the toolbar (the round-arrow icon
between ''Forward'' and ''DirectoryUp'') re-reads both the
directory tree and the contents pane on demand. Works uniformly
for local and SFTP paths; for SFTP it also flushes the per-file
STAT cache, so changes made directly on the remote side become
visible immediately rather than waiting for the 5-second cache TTL
to expire.

The small arrow next to the Refresh icon opens a dropdown with a
single checkbox, '''Automatic Refresh''', controlling the
background polling task that walks every expanded tree item to
detect external changes. The default depends on the current root:

* Local filesystem → '''on''' (10-second cycle, matches the long-standing behaviour).
* SFTP → '''off'''. Each cycle costs one STAT round-trip per child, which is fine for a handful of local directories but painful over the network. Click Refresh manually when you need to pick up remote changes.

When you navigate between local and SFTP roots the toggle flips
automatically — but only if you haven't overridden it for
the previous root. An explicit user choice is preserved across
navigations.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a remote host.
* '''SFTP Connect...''' — points this browser tab at a remote filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of the filesystem holding the currently displayed directory. Works uniformly for local paths and SFTP paths; for SFTP it requires the server to advertise the <code>statvfs@openssh.com</code> extension (every modern OpenSSH does). Sizes are reported in IEC binary units (MiB, GiB, TiB) — the largest unit yielding a value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB'' rather than ''10240 GiB''.

== From the Launcher ==

The Launcher's '''Workspace''' submenu carries two stand-alone
entries (gated on the SSH package being loaded):

* '''SSH Terminal''' — prompts for a target in the form <code>user[:password]@host[:port]</code> and opens a top-level VT100 terminal connected to it. No FileBrowser involved — this is the launcher analogue of the FileBrowserV2 '''Tools → SSH Connect...''' entry.
* '''SFTP Connection''' — prompts for an SFTP target (same URL grammar as the FileBrowserV2 location bar, see [[#From the FileBrowserV2]]) and opens a fresh FileBrowserV2 already navigated to that path.

Both entries honour the URL-embedded password syntax described in
[[#Password authentication]].

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code> (or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only; gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file unencrypted (agent-only mode ignores the passphrase, since the OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to '''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally; a ST/X on the Windows side does not. Bridging needs a helper like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Password authentication ==

Public-key (with or without ssh-agent) is the recommended path.
Password authentication is supported as a fallback for the cases
where keys are not available: legacy hosts, on-the-fly access to a
test box, scripted access to an account whose owner refuses to add
your public key. Keep in mind:

* The plaintext password lives in memory on the ST/X side for the lifetime of the <code>SSH::Client</code> — treat it like any other in-memory secret.
* The server still controls which methods it accepts. If <code>sshd_config</code> has <code>PasswordAuthentication no</code>, no Smalltalk-side configuration can override that.
* Wire-level the handshake is RFC 4252 §8: the password is sent inside the encrypted SSH transport, never in clear over the network.

=== From a URL ===

Both the FileBrowserV2 location bar and the launcher's
'''Workspace → SFTP Connection''' / '''Workspace → SSH
Terminal''' prompts accept an inline password in the standard
RFC-3986 userinfo position:

<pre>
sftp://alice:s3cret@host.example.com/srv/data
ssh alice:s3cret@host.example.com:2222
</pre>

The parser splits on the '''last''' <code>@</code> so passwords
containing <code>@</code> still parse; the first <code>:</code>
inside the userinfo separates user from password. Passwords
containing <code>:</code> are not supported in this form —
use the programmatic API below.

The password is stripped from the printable URL: every place that
ends up logging or displaying the filename (status line,
<code>printOn:</code>, <code>nameString</code>, the breadcrumb path)
shows the credential-free form
<code>sftp://alice@host.example.com/...</code>.

=== From code ===

Two equivalent ways to attach a password to an
<code>SSH::Client</code>:

<pre>
"/ literal -- simplest, password is just an ivar
client := SSH::Client newToHost:'host.example.com' port:22 user:'alice'.
client password:'s3cret'.
client connect.
</pre>

<pre>
"/ callback -- lazy; the password never lives on the client.
"/ Useful with an interactive prompt, a keychain lookup, or a
"/ vault-fetched secret that you do not want long-lived in memory.
client passwordCallback:[ Dialog requestPassword:'SSH password' ].
client connect.
</pre>

The callback wins if both are set. Both are evaluated lazily
during <code>#connect</code>, after publickey/agent attempts have
been rejected, so a working key always wins over a password when
both are configured.

=== Authentication order ===

<code>SSH::Client>>authenticate</code> walks every available
credential in this order, returning on the first one the server
accepts:

# ssh-agent identities, if <code>#useAgent</code> was called and the agent has loaded keys.
# ed25519 private-key seed, if <code>#privateKeyFromFile:</code> picked one up.
# RSA private key.
# ECDSA private key.
# Password, if <code>#password:</code> / <code>#passwordCallback:</code> was set '''and''' the server still advertises <code>password</code> in its USERAUTH_FAILURE methods list.

Each step is skipped when the server's last
<code>USERAUTH_FAILURE</code> reply dropped the relevant method
from its allowed list — we do not bang on
<code>publickey</code> after the server stops offering it. The
password attempt is only fired when the server still wants
<code>password</code>, so a misconfigured client password against a
key-only server raises a clean
<code>SSH::AuthenticationError</code> without an extra useless
round-trip.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's walkback plus each waiter's, formatted as plain text. Use when a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed (e.g. legacy PEM, encrypted-without-agent) — the file is skipped, others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime), no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On servers that advertise <code>posix-rename@openssh.com</code> (every modern OpenSSH does), overwrite is atomic; on the rare server that does not, the receiver is emulated as delete-then-rename and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always returns <code>#isDirectory</code> (the accurate answer would cost three round-trips per directory icon, which made the original tree expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link. Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe, EOF, MNU on nil socket) evicts the dead pool entry, opens a fresh client, retries the request '''once'''. Application-level SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP + one SFTP channel per host means N concurrent requests serialise. Pipelining over multiple SshClients in the pool (preferred), or a transport-level reader process demultiplexing to per-channel inboxes, would let the tree pane keep listing while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (first batch only) + CLOSE — three RTTs per probe; needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style canonicalisation. (Atomic-overwrite rename is already handled via the OpenSSH <code>posix-rename@openssh.com</code> extension; see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]

Remote Access

2026-06-08T14:26:01Z

Sv: password authentication: URL form, code API, auth order; launcher menu entries

{{Languages|Remote Access|label=Deutsch}}

'''Fernzugriff''' bezeichnet die Möglichkeit, einen entfernten
Rechner oder ein entferntes Netzwerk aus diesem expecco-Image heraus
zu bedienen — Shells zu öffnen, Befehle abzusetzen, Dateien zu
verschieben oder ein Testgerät anzusteuern. Drei Protokoll-Familien
sind unterstützt, in absteigender Empfehlungsreihenfolge:

* '''SSH und SFTP''' (empfohlen) — verschlüsselte Shell und sichere Dateiübertragung über einen SSH-2-Tunnel. Reine Smalltalk-Implementierung in <code>exept:libcrypt/ssh</code>; keine externe Abhängigkeit von OpenSSL oder libssh. Für alles mit Zugangsdaten oder sensiblen Nutzdaten.
* '''Lokale Kommando-Shell''' — fork + exec auf der lokalen Maschine. Für die Anbindung lokaler Werkzeuge und für die lokale Seite eines hybriden Workflows.
* '''Telnet''' (veraltet) — Klartext-Terminalsitzung. Keine Verschlüsselung, Passwörter im Klartext auf der Leitung. Nur einsetzen, wenn die Gegenstelle keine Alternative bietet.

= SSH und SFTP =

Der SSH-Stack deckt das vollständige SSH-2-Protokoll ab
(RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) inklusive der
chacha20-poly1305-Transportchiffrierung von OpenSSH sowie das
SFTP-v3-Subsystem (draft-ietf-secsh-filexfer-02). Zwei Schichten:

* '''<code>SSH::Client</code>''' — programmatischer SSH-Zugriff (entferntes <code>exec</code>, TTY-Shell, Agent-Weiterleitung, ProxyJump-Bastion).
* '''<code>SSH::SftpFilename</code>''' — eine
<code>Filename</code>-Unterklasse, die es dem restlichen ST/X
erlaubt, einen entfernten SFTP-Pfad zu behandeln wie eine lokale
Datei.

Die folgenden Abschnitte sind nutzeraufgaben-zuerst aufgebaut:
zuerst das, was der Anwender sieht und tut, darunter die
expecco-Bibliotheks-Anbindung, ganz unten Implementierungsdetails
für Interessierte.

== Aus dem FileBrowserV2 ==

Im Adress-Dropdown eine <code>sftp://</code>-URL einfügen. Der
Browser-Tab füllt sich wie bei einem lokalen Pfad.
Baum-Ausklappen, Spaltensortierung (Name / Größe / mtime),
Vorschau und Doppelklick zum Öffnen im Editor verhalten sich
normal. Der erste Klick auf einen Host dauert ~200–500 ms
(TCP + KEX + Auth); folgende Klicks nutzen die gepoolte
Verbindung weiter.

URL-Syntax:

<pre>
sftp://[user[:password]@]host[:port]/remote/path
</pre>

Fehlt <code>user</code>, wird der lokale Login-Name verwendet, Port
ist standardmäßig 22, Pfad standardmäßig <code>/</code>. Das
optionale <code>:password</code>-Segment ist das RFC-3986-Userinfo-Passwort
— wann es angebracht ist und welche Sicherheitsabwägungen
damit verbunden sind, beschreibt [[#Passwort-Authentifizierung]].
Wenn vorhanden, dient es als USERAUTH-Fallback nach den üblichen
Publickey-/Agent-Versuchen und wird '''niemals''' wieder von der
druckbaren URL-Form ausgegeben — das Protokollieren des
Dateinamens leakt also nicht das Credential.

Die Schaltfläche '''Refresh''' in der Symbolleiste
(Pfeil-Kreis-Symbol zwischen ''Forward'' und ''DirectoryUp'') liest
Baum und Inhalts-Panel auf Anforderung neu ein. Funktioniert
einheitlich für lokale und SFTP-Pfade; bei SFTP wird zusätzlich der
per-Datei-STAT-Cache geleert, sodass Änderungen, die direkt auf
der Gegenseite gemacht wurden, sofort sichtbar werden — ohne auf
den Ablauf der 5-Sekunden-Cache-TTL zu warten.

Der kleine Pfeil neben dem Refresh-Symbol öffnet ein Aufklappmenü
mit einem einzelnen Kontrollkästchen, '''Automatic Refresh''', das
den Hintergrund-Task an- bzw. abschaltet, der alle expandierten
Baumeinträge auf externe Änderungen prüft. Die Vorgabe richtet
sich nach der aktuellen Wurzel:

* Lokales Dateisystem → '''an''' (10-Sekunden-Zyklus, entspricht dem bisherigen Verhalten).
* SFTP → '''aus'''. Jeder Zyklus kostet einen STAT-Roundtrip pro Kind — für eine Handvoll lokaler Verzeichnisse harmlos, über das Netz schmerzhaft. Bei Bedarf manuell auf Refresh klicken, um Änderungen zu sehen.

Beim Wechsel zwischen lokalen und SFTP-Wurzeln wird der Schalter
automatisch umgelegt — aber nur, sofern man ihn für die
vorherige Wurzel nicht selbst verstellt hat. Eine explizite
Benutzerwahl bleibt über Navigationen hinweg erhalten.

Das Menü '''Tools''' im FileBrowserV2 bietet vier Aktionen — die
drei SSH-spezifischen sind nur bei geladener SSH-Bibliothek
sichtbar:

* '''Generate SSH Key Pair...''' — öffnet den Schlüsselerzeugungs-Dialog, siehe [[#Einen SSH-Schlüssel erzeugen]] unten.
* '''SSH Connect...''' — öffnet ein interaktives VT100-Terminal zu einem entfernten Host.
* '''SFTP Connect...''' — navigiert diesen Browser-Tab über SFTP auf ein entferntes Dateisystem.
* '''Filesystem Info...''' — zeigt Größe, freien Platz und Belegung des Dateisystems, das das aktuell angezeigte Verzeichnis enthält. Funktioniert einheitlich für lokale und SFTP-Pfade; bei SFTP setzt der Aufruf voraus, daß der Server die Erweiterung
<code>statvfs@openssh.com</code> ankündigt (jedes moderne OpenSSH
tut das). Größen werden in IEC-Binäreinheiten ausgegeben (MiB,
GiB, TiB) — gewählt wird die größte Einheit, die einen Wert ≥ 1
liefert, damit ein TB-großes Volume als ''X TiB'' statt
''10240 GiB'' erscheint.

== Aus dem Launcher ==

Das Untermenü '''Workspace''' im Launcher enthält zwei eigenständige
Einträge (nur sichtbar bei geladenem SSH-Paket):

* '''SSH Terminal''' — fragt nach einem Ziel der Form <code>user[:password]@host[:port]</code> und öffnet ein VT100-Terminal als eigenständiges Fenster. Das ist das Launcher-Pendant zum FileBrowserV2-Eintrag '''Tools → SSH Connect...'''.
* '''SFTP Connection''' — fragt nach einem SFTP-Ziel (gleiche URL-Grammatik wie in der FileBrowserV2-Adresszeile, siehe [[#Aus dem FileBrowserV2]]) und öffnet einen frischen FileBrowserV2, der bereits dorthin navigiert ist.

Beide Einträge unterstützen die in [[#Passwort-Authentifizierung]]
beschriebene URL-Form mit eingebettetem Passwort.

== Aus expecco-Aktionen ==

Das Expecco-RemoteAccess-Plugin
([[Expecco::RemoteAccessImportPlugin]]) stellt folgende Testaktionen
in der expecco-Aktionspalette bereit:

* '''CmdShell - Open SSH Remote Connection''' — öffnet eine SSH-Sitzung über das plattformeigene <code>ssh</code>-Binary (PuTTYs <code>plink</code> unter Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — dasselbe, jedoch mit expliziter Public-Key-Authentifizierung.

Voraussetzung: ein eingerichtetes Schlüsselpaar (privater
Schlüssel auf dieser Maschine, öffentlicher Teil in der
<code>~/.ssh/authorized_keys</code> des Zielhosts). Schlüssel
erzeugen entweder über den Dialog unten oder über
<code>ssh-keygen</code>.

Das Plugin fügt zusätzlich eine Settings-Seite hinzu:
'''Extras → Settings → Plugins → Remote Access — SSH Keys''' mit
einer einzelnen Schaltfläche '''Generate SSH Key Pair...''', die
denselben Dialog öffnet.

== Einen SSH-Schlüssel erzeugen ==

=== Der Dialog (FileBrowserV2 / Settings-Seite) ===

Der Dialog fragt alle Parameter in einem Formular ab:

* '''Comment''' — wird in den erzeugten Schlüssel eingebettet (Voreinstellung <code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — schreibt
<code>~/.ssh/id_ed25519_stx</code> (oder wohin man will) samt
zugehöriger <code>.pub</code>-Datei daneben.
** ''Save to disk AND load into ssh-agent'' — schreibt die Datei UND übergibt den Schlüssel dem laufenden ssh-agent.
** ''Load into ssh-agent only'' — der Schlüssel lebt nur im Speicher des Agents; nach Agent-Neustart ist er verloren.
* '''Private key file''' — vollständiger Pfad; ausgegraut im Agent-only-Modus.
* '''Passphrase / Confirm''' — leer lässt die On-Disk-Datei unverschlüsselt (Agent-only-Modus ignoriert die Passphrase, da das OpenSSH-Agent-Wire-Protokoll nur den entschlüsselten Schlüssel transportiert).

Bei '''Generate''' wird die Public-Key-Zeile (dieselbe
<code>ssh-ed25519 AAAA... comment</code>-Zeichenfolge, die
ssh-keygen ausgibt) in die System-Zwischenablage kopiert — zum
direkten Einfügen in die <code>~/.ssh/authorized_keys</code> des
Zielhosts.

=== Aus einem Workspace ===

Für Headless-Deployments, Sandbox-Builds oder Skripte stellt
<code>SSH::Client</code> einen reinen Smalltalk-Schlüsselgenerator
bereit, dessen Ausgabe bit-kompatibel zu
<code>ssh-keygen -t ed25519</code> ist:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Passphrase-verschlüsselt auf Platte speichern"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ UND in den laufenden Agent laden"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Public-Key-Zeile zum Einfügen in authorized_keys ausgeben"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Die so erzeugten Schlüssel sind mit den OpenSSH-Werkzeugen voll
interoperabel (<code>ssh-keygen -y -f ...</code> rekonstruiert den
öffentlichen Schlüssel, <code>ssh-keygen -p -f ...</code> ändert
die Passphrase usw.).

=== Mit den Shell-Werkzeugen ===

Der klassische Weg funktioniert weiterhin:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== ssh-agent vorbereiten ==

Der Weg über den Agent ist dem direkten Lesen von Schlüsseldateien
deutlich vorzuziehen: er hält verschlüsselte private Schlüssel
einmal pro Sitzung entsperrt und kann Identitäten verwalten
(hardware-tokengestützte Schlüssel, KeePassXC-Einträge), die ST/X
nie direkt sehen soll.

ST/X erkennt den Agent-Pfad automatisch, sobald
<code>$SSH_AUTH_SOCK</code> '''zum Zeitpunkt des Starts von stx'''
in der Prozessumgebung gesetzt ist. Eine spätere Zuweisung aus
einem Workspace nützt nichts.

=== Linux / macOS ===

Die meisten Desktop-Distributionen starten einen Agent automatisch
beim Login (gnome-keyring unter GNOME, ssh-agent.service unter
systemd, KWallet unter KDE). Prüfen im Terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh oder ähnlich
ssh-add -l # listet geladene Identitäten
ssh-add ~/.ssh/id_ed25519 # eigene laden, falls nicht da
</pre>

Läuft gar kein Agent, dieses Snippet in die Shell-rc-Datei
aufnehmen:

<pre>
# ~/.bashrc oder ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X muss aus einer Shell gestartet werden, die diese rc bereits
gelesen hat — ein Desktop-Launcher aus dem Dateimanager erbt die
Variable nicht. Empfehlung: ein kleines Wrapper-Skript unter
<code>~/.local/bin/</code>, das die rc sourcet und dann stx
startet.

Die Settings-Seite ('''Extras → Settings → Plugins → Remote
Access — SSH Keys''') zeigt an, ob das laufende Image einen
Agent sieht.

==== Permanente Einrichtung via systemd ====

Für einen wirklich sitzungsübergreifenden Agent (überlebt Desktop-
Abmeldung, kommt beim nächsten Login wieder hoch) die bei den
meisten Distros mit dem Paket <code>openssh-clients</code>
ausgelieferte Per-User-systemd-Unit aktivieren:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Anschließend <code>SSH_AUTH_SOCK</code> in der Shell-rc auf den
User-Service-Socket zeigen lassen (ersetzt das
<code>eval $(ssh-agent -s)</code>-Snippet oben):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Schlüssel automatisch beim ersten Einsatz laden ====

Um den manuellen <code>ssh-add</code>-Schritt zu sparen, kann
OpenSSH Schlüssel beim ersten Bedarf selbst in den Agent laden.
In <code>~/.ssh/config</code> eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

Die erste SSH-Verbindung fragt dann einmal nach der Passphrase und
übergibt den entsperrten Schlüssel an den Agent; weitere
Verbindungen nutzen die gespeicherte Identität ohne Prompt.

=== Windows ===

Windows 10+ bringt das native OpenSSH inklusive Agent-Dienst mit.
Einmalige Einrichtung:

# '''Dienste''' (<code>services.msc</code>) als Administrator öffnen.
# '''OpenSSH Authentication Agent''' suchen, Starttyp auf '''Automatisch''' setzen, '''Starten''' anklicken.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Prüfen: <code>ssh-add -l</code>.

Der Windows-OpenSSH-Agent lauscht auf einer Named Pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), nicht auf einem
Unix-Socket. ST/X unterstützt beide Transporte, jedoch setzt das
Windows-ssh-add <code>SSH_AUTH_SOCK</code> '''nicht''' selbst.
Daher einmalig systemweit setzen:

# {{Key|Win}} drücken → "Umgebungsvariablen" → „Systemumgebungs- variablen bearbeiten".
# '''Umgebungsvariablen''' → unter '''Benutzervariablen''', '''Neu''' klicken.
# Name: <code>SSH_AUTH_SOCK</code>
# Wert: <code>\\.\pipe\openssh-ssh-agent</code>
# Ab- und wieder anmelden (oder stx neu starten), damit die neue Umgebung übernommen wird.

==== PowerShell-Schnelleinrichtung ====

Derselbe Aufbau aus einer '''Administrator-PowerShell''' heraus,
z.B. für Skripte oder unbeaufsichtigte Bereitstellung:

<pre>
# Agent jetzt und bei jedem Neustart starten (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# SSH_AUTH_SOCK dauerhaft für den Benutzer setzen (übersteht Reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Schlüssel laden (fragt nach Passphrase, falls die Datei verschlüsselt ist).
ssh-add $HOME\.ssh\id_ed25519
</pre>

Für einen einmaligen Agent-Start ohne dauerhafte Aktivierung
(z.B. Einzelsitzung) die <code>Set-Service</code>-Zeile weglassen
und nur <code>Start-Service ssh-agent</code> ausführen. Die
env-var-Zeile lässt sich ebenfalls weglassen, wenn
<code>SSH_AUTH_SOCK</code> nur in der aktuellen Shell gebraucht
wird — dann statt der <code>[Environment]</code>-Variante
<code>$env:SSH_AUTH_SOCK = '...'</code> verwenden.

Auf stark abgespeckten Windows-Installationen ist der
ssh-agent-Dienst eventuell nicht vorhanden. Einmalig nachrüsten
über '''Einstellungen → Apps → Optionale Features → OpenSSH-
Client'''.

Alternative Agenten:

* '''PuTTY pageant''' — eigenes Protokoll; von ST/X's
<code>SSH::Agent</code> '''nicht''' unterstützt. Schlüssel zu
OpenSSH migrieren.
* '''Git für Windows ssh-agent''' — funktioniert;
<code>SSH_AUTH_SOCK</code> auf den dort veröffentlichten Socket
zeigen lassen.
* '''WSL 2''' — ein ST/X innerhalb der WSL sieht den WSL-eigenen Agent normal; ein ST/X auf der Windows-Seite nicht. Eine Brücke per <code>npiperelay</code> + <code>socat</code> ist möglich.

Prüfung über die Settings-Seite
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
die Anzeige dort meldet, ob das laufende Image den Agent sieht.

==== Schlüssel automatisch beim ersten Einsatz laden ====

Windows-OpenSSH speichert agent-geladene Schlüssel '''nicht'''
über Agent-Neustarts hinweg. Um nicht nach jedem Reboot manuell
<code>ssh-add</code> aufrufen zu müssen, dieselbe Lazy-Load-
Konfiguration in <code>%USERPROFILE%\.ssh\config</code>
eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH lädt den Schlüssel dann beim ersten Einsatz in den Agent
(fragt einmal nach der Passphrase) und nutzt ihn für die übrige
Sitzung weiter.

== Passwort-Authentifizierung ==

Empfohlen ist Public-Key-Authentifizierung (mit oder ohne
ssh-agent). Passwort-Authentifizierung ist als Fallback gedacht,
wenn keine Schlüssel verfügbar sind: Altsysteme, Ad-hoc-Zugriff
auf einen Testserver, Skripte gegen ein Konto, dessen Besitzer den
Public Key nicht hinterlegen möchte. Zu beachten:

* Das Klartext-Passwort liegt auf ST/X-Seite für die Lebensdauer des <code>SSH::Client</code> im Speicher — entsprechend behandeln wie jedes andere In-Memory-Geheimnis.
* Der Server entscheidet, welche Methoden er akzeptiert. Steht in <code>sshd_config</code> <code>PasswordAuthentication no</code>, kann keine Smalltalk-seitige Einstellung das überschreiben.
* Auf Drahtebene entspricht der Vorgang RFC 4252 §8: das Passwort wandert innerhalb der verschlüsselten SSH-Transportschicht, niemals im Klartext über das Netz.

=== Aus einer URL ===

Sowohl die FileBrowserV2-Adressleiste als auch die Launcher-Dialoge
'''Workspace → SFTP Connection''' / '''Workspace → SSH
Terminal''' akzeptieren ein eingebettetes Passwort an der
standardmäßigen RFC-3986-Userinfo-Position:

<pre>
sftp://alice:s3cret@host.example.com/srv/data
ssh alice:s3cret@host.example.com:2222
</pre>

Der Parser splittet am '''letzten''' <code>@</code>, sodass
Passwörter mit enthaltenem <code>@</code> dennoch korrekt geparst
werden; der erste <code>:</code> im Userinfo-Teil trennt Benutzer
und Passwort. Passwörter, die selbst ein <code>:</code> enthalten,
werden in dieser Form nicht unterstützt — dafür die
programmatische API unten verwenden.

Das Passwort wird aus der druckbaren URL entfernt: jede Stelle, die
am Ende den Dateinamen ausgibt (Statuszeile,
<code>printOn:</code>, <code>nameString</code>, die Breadcrumb-Leiste)
zeigt die credential-freie Form
<code>sftp://alice@host.example.com/...</code>.

=== Aus Code ===

Zwei äquivalente Wege, einem <code>SSH::Client</code> ein Passwort
mitzugeben:

<pre>
"/ Literal -- am einfachsten, Passwort ist nur ein Ivar
client := SSH::Client newToHost:'host.example.com' port:22 user:'alice'.
client password:'s3cret'.
client connect.
</pre>

<pre>
"/ Callback -- lazy; das Passwort lebt nie auf dem Client.
"/ Praktisch für interaktive Abfrage, Keychain-Lookup oder ein
"/ Vault-gespeichertes Geheimnis, das nicht langlebig im Speicher
"/ liegen soll.
client passwordCallback:[ Dialog requestPassword:'SSH-Passwort' ].
client connect.
</pre>

Sind beide gesetzt, gewinnt der Callback. Beide werden lazy
während <code>#connect</code> ausgewertet, nachdem die
Publickey-/Agent-Versuche abgelehnt wurden — ein
funktionierender Schlüssel schlägt also immer ein parallel
konfiguriertes Passwort.

=== Reihenfolge der Authentifizierungsversuche ===

<code>SSH::Client>>authenticate</code> geht jedes verfügbare
Credential der Reihe nach durch und kehrt beim ersten zurück, das
der Server akzeptiert:

# ssh-agent-Identitäten, sofern <code>#useAgent</code> aufgerufen wurde und der Agent Schlüssel geladen hat.
# ed25519-Privatschlüssel-Seed, sofern <code>#privateKeyFromFile:</code> einen geladen hat.
# RSA-Privatschlüssel.
# ECDSA-Privatschlüssel.
# Passwort, sofern <code>#password:</code> / <code>#passwordCallback:</code> gesetzt ist '''und''' der Server <code>password</code> in seiner USERAUTH_FAILURE-Methodenliste weiterhin anbietet.

Jeder Schritt wird übersprungen, wenn die letzte
<code>USERAUTH_FAILURE</code>-Antwort des Servers die jeweilige
Methode aus der erlaubten Liste gestrichen hat — auf
<code>publickey</code> wird also nicht weiter herumgehämmert,
sobald der Server damit aufhört. Der Passwortversuch läuft nur,
wenn der Server <code>password</code> noch verlangt; ein falsch
konfiguriertes Passwort gegen einen reinen Schlüssel-Server erzeugt
also einen sauberen <code>SSH::AuthenticationError</code> ohne
zusätzlichen nutzlosen Roundtrip.

== Konfiguration ==

Alle Stellschrauben sind klassenseitig auf
<code>SSH::SftpFilename</code> erreichbar:

{| class="wikitable"
! Accessor !! Voreinstellung !! Steuert
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 Min) || Wie lange
eine gepoolte Verbindung im Leerlauf liegen darf, bevor sie beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet wird.
Liegt knapp unter dem typischen
<code>ClientAliveInterval × ClientAliveCountMax</code> des sshd,
damit wir uns recyceln, bevor der Server uns mit TCP-RESET
trennt. <code>nil</code> setzt auf Voreinstellung zurück.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Maximales Alter (s)
eines gecachten STAT, bevor <code>#ensureAttrs</code> neu am
Server fragt. Eltern-listDir stempelt ohnehin frische Attribute
auf alle Kinder, daher zahlt das Navigieren im offenen
Verzeichnis das TTL nicht. <code>0</code> schaltet den Cache
ab.
|-
| <code>#closeAllConnections</code> || (Aktion) || Reißt jede
gepoolte Verbindung ab. Nützlich nach einem bekannt schlechten
Netzereignis, vor einem bewussten Identitätswechsel oder zum
sauberen Image-Shutdown.
|}

== Diagnose ==

=== SemaphoreMonitor ===

<code>SemaphoreMonitor</code> über das Untermenü „Status" des
Launchers öffnen. Der pro-Host-SFTP-Mutex erscheint als
<code>SFTP/<user@host:port></code>, der pool-weite Mutex als
<code>SFTP/pool</code>. Per Rechtsklick:

* '''Copy Waiters Stack to Clipboard''' — schreibt den Walkback des letzten Eigners samt aller Waiter als Text in die Zwischenablage. Unverzichtbar, wenn ein Prozess in
<code>readWait</code> innerhalb von
<code>withSftpClientDo:</code> klemmt.
* '''Copy List to Clipboard''' — die ganze Tabelle, ideal für eine E-Mail-Diagnose.
* '''Detect Deadlocks''' — DFS über den Wait-for-Graph, meldet Zyklen.

=== Logger ===

Interessante Ereignisse werden über <code>Logger</code> geloggt:

* <code>warning:</code> bei automatischem Reconnect nach toter Verbindung.
* <code>warning:</code> bei Idle-Verdrängung eines Pool-Eintrags.
* <code>warning:</code> wenn eine SSH-Schlüsseldatei nicht geparst werden konnte — die Datei wird übersprungen.

== Einschränkungen ==

* '''Nur SFTP v3.''' Kein SETSTAT (kein entferntes chmod / chown / utime), kein SSH_FXP_READLINK exponiert (<code>#isSymbolicLink</code> liefert immer <code>false</code>,
<code>#linkInfo</code> die normale stat-Info). Einige
SFTPv5+-Annehmlichkeiten werden dennoch über OpenSSH-spezifische
SSH_FXP_EXTENDED-Aufrufe nutzbar — siehe
[[#OpenSSH-SFTP-Erweiterungen]] weiter unten.
* '''Serialisierung pro Host.''' Zwei gleichzeitige Operationen am selben Host stehen am Host-Mutex an. Siehe [[#Ausblick]].
* '''<code>#renameTo:</code>-Fallback hat ein TOCTOU-Fenster.''' Bei Servern, die <code>posix-rename@openssh.com</code> ankündigen (jedes moderne OpenSSH tut das), ist das Überschreiben atomar. Beim seltenen Server, der das nicht tut, wird auf Delete-dann-Rename ausgewichen und ein anderer Prozess kann sich dazwischenschieben.
* '''<code>#isNonEmptyDirectory</code> ist eine Heuristik.''' Liefert immer <code>#isDirectory</code> (die genaue Antwort würde drei Roundtrips pro Verzeichnis-Symbol kosten, was das ursprüngliche Baum-Ausklappen unerträglich gebremst hatte).

== Implementierungsdetails ==

Für Leser, die die Architektur verstehen wollen. Fünf Klassen,
von oben nach unten:

{| class="wikitable"
! Klasse !! Aufgabe
|-
| <code>SSH::SftpFilename</code> || Filename-Unterklasse, die
öffentliche API. Bildet <code>sftp://...</code>-URLs auf
entfernte Dateien ab und stellt <code>directoryContents</code>,
<code>readingFileDo:</code>, <code>renameTo:</code> usw. bereit.
|-
| <code>SSH::SftpClient</code> || SFTP-v3-Protokoll
(Request/Response-Codec, listDir, stat, open, read, write, mkdir).
Wird von SftpFilename angesteuert.
|-
| <code>SSH::Channel</code> || SSH-Kanal-Multiplexer (CHANNEL_OPEN,
DATA, EOF, CLOSE, WINDOW_ADJUST). Eine logische Sitzung pro
Channel-Instanz.
|-
| <code>SSH::Client</code> || High-Level-SSH-Client: öffnet den
Transport, führt KEX, Hostschlüssel-Prüfung und userauth durch und
verteilt anschließend Kanäle.
|-
| <code>SSH::Transport</code> || Drahtschicht. Banner- und
KEXINIT-Austausch, ChaCha20-Poly1305-Paket-Framing, sendSeq /
recvSeq, Heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH-SFTP-Erweiterungen ===

SFTP v3 (Entwurf draft-ietf-secsh-filexfer-02) ist bewusst
minimal gehalten. OpenSSH bringt einen offenen
Erweiterungsmechanismus mit: der Server listet im
<code>SSH_FXP_VERSION</code>-Reply die Erweiterungsnamen auf, die
er versteht, und der Client ruft sie über
<code>SSH_FXP_EXTENDED(200)</code>-Pakete mit dem
Erweiterungsnamen als erstem String auf. Jede Erweiterung wird
über <code>SSH::SftpClient>>supportsExtension:</code>
feature-detektiert; Aufrufer fallen zurück, wenn der Server sie
nicht ankündigt.

Der Stack nutzt heute vier OpenSSH-Erweiterungen:

* <code>posix-rename@openssh.com</code> — atomares rename-mit-Überschreiben. Wird automatisch von
<code>SftpFilename>>renameTo:</code> aufgegriffen; die
Delete-dann-Rename-Fallback-Variante kommt nur bei Servern zum
Einsatz, die die Erweiterung nicht haben.
* <code>hardlink@openssh.com</code> — Erzeugt einen POSIX-Hardlink. Verfügbar als <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX-
<code>statvfs(3)</code>-typische Dateisystem-Statistik.
Verfügbar als <code>SftpFilename>>fileSystemInfo</code>;
das Ergebnis ist form-kompatibel zu
<code>OperatingSystem getDiskInfoOf:</code>, sodass Aufrufer
lokale und entfernte Pfade einheitlich behandeln können.
Treibt den Menü-Eintrag '''Tools → Filesystem Info...''' an,
der am Anfang dieser Seite beschrieben ist.
* <code>fsync@openssh.com</code> — schreibt den serverseitigen Schreibpuffer eines geöffneten Handles auf Platte. Liegt als
<code>SftpClient>>fsyncHandle:</code> bereit; noch nicht
in eine "Durable-Write"-API auf Filename-Ebene eingebunden.

Die verbleibenden OpenSSH-Erweiterungen
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
werden in der angekündigten Liste erkannt, aber nicht auf
Filename-Ebene gekapselt — es gibt dafür noch keinen
Filename-seitigen Aufrufer.

=== Verbindungs-Pooling ===

Alle <code>SftpFilename</code>-Instanzen, die auf dasselbe Tripel
<code>user@host:port</code> zeigen, teilen sich einen
<code>SSH::Client</code> samt einem <code>SSH::SftpClient</code>.
Der Pool ist klassenseitig und wird von einem einzigen
<code>ConnectionPoolMutex</code> bewacht:

* '''Lazy-Aufbau''' — TCP + KEX + userauth + SFTP-INIT laufen erst beim ersten SFTP-Aufruf, nicht in <code>forUrl:</code>.
* '''Serialisierung pro Host''' — SFTP-Anfragen an einen bestimmten Host werden durch einen <code>RecursionLock</code> mit dem Namen <code>SFTP/<user@host:port></code> serialisiert (sichtbar im SemaphoreMonitor).
* '''Idle-Verdrängung''' — ein Pool-Eintrag, der länger als
<code>idleEvictionSeconds</code> ungenutzt liegt, wird beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet.
* '''Automatischer Reconnect''' — ein Fehler auf Transportebene (Broken Pipe, EOF, MNU auf nil-Socket) verdrängt den Pool-Eintrag, öffnet einen frischen Client und wiederholt die Anfrage '''einmal'''. Anwendungsfehler aus SFTP-STATUS-Antworten werden sofort durchgereicht.

== Ausblick ==

Geplant, aber noch nicht umgesetzt:

* '''Multi-Channel-Parallelität pro Host''' — aktuell bedeutet eine TCP- plus eine SFTP-Verbindung pro Host, dass N gleichzeitige Anfragen serialisieren. Pipelining über mehrere SshClients im Pool (bevorzugt) oder ein transport-seitiger Reader-Prozess, der eingehende Pakete in Pro-Kanal-Postfächer demultiplext, würde es dem Baum-Panel erlauben, weiter aufzulisten, während das Inhalts-Panel eine große Datei liest.
* '''Genaues <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (nur erstes Batch) + CLOSE — drei Roundtrips pro Sondierung; lohnt erst, wenn der SftpClient Anfragen pipelinen kann.
* '''SFTP-v5/v6-Aushandlung''' für erweiterte Attribute und FTP-artige Kanonisierung. (Atomares Überschreibungs-rename ist bereits über die OpenSSH-Erweiterung
<code>posix-rename@openssh.com</code> abgedeckt; siehe
[[#OpenSSH-SFTP-Erweiterungen]].)

= Kommando-Shell =

Lokale Kommando-Shell auf dieser expecco-Maschine. Typische
Anwendungen: lokale Kommandozeile, lokales Hilfsprogramm,
Brücke zwischen entferntem Workflow und lokalem Tool.

Das RemoteAccess-Plugin stellt bereit:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

Keine Zugangsdaten, kein Netzwerk — läuft als der Benutzer des
expecco-Prozesses. Ausgaben gehen in das expecco-Log.

= Telnet =

[[File:Warning.svg|24px|Warnung]] '''Telnet ist ein veraltetes
Protokoll ohne Verschlüsselung.''' Passwörter werden im Klartext
über die Leitung übertragen; jeder im Netzpfad kann sie lesen.
Telnet NUR einsetzen, wenn die Gegenstelle keine Alternative
bietet (typisch: alte Industriesteuerungen, Laborgeräte,
eingebettete Messgeräte ohne SSH-Stack). Für alles andere
[[#SSH und SFTP]] verwenden.

Das expecco-Plugin stellt bereit:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (interne Demo)

Das Telnet-Protokoll (RFC 854) ist ein bidirektionaler
8-Bit-Byte-Strom über TCP, mit In-Band-Steuersequenzen für
Terminal-Optionen. Verbindungsaufbau zum Ziel-Host:Port; nach
optionalem In-Band-Login können beide Seiten Daten senden.

= Siehe auch =

* [[SSH Client|SSH::Client]] — die SSH-Schicht (exec, TTY, Agent-Weiterleitung, ProxyJump).
* [[FileBrowserV2]] — die Haupt-UI dieses Stacks.
* [[ClaudeCode plugin|Claude Code]] — nutzt denselben SSH-Stack als HTTPS-Transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Netz]]
[[Category:SSH]]

Release Notes 26.x

2026-05-29T07:39:47Z

Sv: add performance entry for log-archive load speedup

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports both '''Anthropic Claude''', '''OpenAI ChatGPT''' or '''Llama''' as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via [[Tools_FileBrowser/en|FileBrowser]])
* Feature: public/private keypair generation via a [[Tools_FileBrowser/en|FileBrowser]] menu (for easy SSH setup)
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed the [[Number_API_Functions|Number]] stack (see also in [[Numeric_Limits/en| Numeric Limits]]):
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. and type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan). Now all test cases produce a result within the precision limits of their type
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]].
* Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
* Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
* Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Performance: speedup of cryptographic algorithms (affects key generation and other)
* Performance: tuned loading of stored ets/elf files (30-40% speedup)
* Performance: further speedup when loading test-result archives that embed large execution logs — typical load is roughly a third faster again

FAQ on Bridges/en

2026-05-27T13:48:26Z

Sv: update SSL section: client cert in prefs, load/inspect/clear UI, chain validation on load

== Why Bridged Actions and not Script Actions? ==

Script actions will start the language interpreter anew for every such action. Thus, no internal state can be held and transferred from one such action to another. Especially, it is not possible to open a communication channel on one script action, pass it back to expecco, and use it with different followup script actions (i.e. actions like "''open-port''" / "''send message''" / "''receive message''" / "''close port''" etc.).

For this, it is required to call individual API-entries inside the bridge code, and return handles from the bridge to expecco, which can later be passed to other API entries. This of course only makes sense, if the interpreter stays active during the lifetime of the connection.

On the other hand, script actions are easier to use if a self contained program or app is to be started, or which performs a single processing action or which stays alive for longer, serving a socket or database. In any such case, there is no need to exchange individual data objects (such as handles) with expecco. It may however interact with expecco through other communication channels, such as sockets, RPC calls, SOAP interface or stdin/stdout text ports.

Thus, you will typically use script actions to start server applications and bridged actions to call individual functions of a framework.

== Which Languages are Supported ==

By the time this chapter was written, bridged code execution is supported for:
* Java (using either Groovy or Jython as "''glue''" or directly using proxy objects in expecco)
* Python (both Python 2.7 and Python 3.x)
* .NET (using IronPython as "''glue''" or directly via proxy objects)
* NodeJS (i.e. JavaScript)
* C/C++ (Root/Cling is being developed currently)
* Smalltalk (Smalltalk/X and VisualWorks are currently supported; VisualAge may come in the near future, if there is sufficient customer interest)
* Ruby
Plans are to support Dart and Scheme in the future.

== How are Bridges Started ==

Bridges on the local machine are usually automatically started by expecco itself, when the first bridged action is executed (and stays alive, until expecco is terminated, or bridge connections are closed via the menu or via an expecco action block). Some language interpreters may take a few seconds to come up, so the first such action will execute relatively slow compared to later actions. You can add a dummy (empty) bridged action to your startup actions (project's postLoad action) to prepare the bridged interpreter and have it startup in parallel.

Bridges on other machines, or additional bridges on the local machine must be started by executing a bridge start action block or simply by executing a shell/batch action to call the corresponding language interpreter (python, node, etc.). On Windows, a powershell action can be used for remote execution (given that your Windows security settings allow that). On Unix, a shell action executin a remote shell / ssh command could be used.

== Who Initiates the Connection ==

Normally, expecco opens a port and tells the bridge (via command line argument) to which port to connect. Depending on the setup of your network and firewall, it may sometimes be required to reverse this, and let the bridge open a port and expecco connect to it.

For this, some bridges support command line arguments ("--server" and "--port") to specify this behavior. Details are found in the individual bridge documentation pages.

== Ports Used for Bridge Communication ==

Unless ports are configured in the expecco settings,
the following default ports are used (bridges typically listen on or connect to this port, unless an explicit "--port" argument is given):

Python 8677 , 8678 (debug)
Python2 8679 , 8680 (debug)
Python3 8681 , 8682 (debug)
Jython 8777 , 8778 (debug)
IronPython 8787 , 8788 (debug)
Node 8577 , 8578 (debug)
Electron 8588 , 8589 (debug)
[[Embedded_Systems_C_Bridge_API |CBridge]] 8855 (also for Root/Cling)
Smalltalk 8877
VASmalltalk 8879
VWSmalltalk 8881
Dart 8885
Ruby 8977
Scheme 8599

Note: for some bridges, two connections are used, the debug port being used by the debugger to inspect data and to support breakpoints, single stepping etc.
 Note: expecco will try successive alternative ports, if the default port happens to be already in use.

Debugging is not supported on all bridges (eg. the C-bridge does not).

== What are Proxy Objects ==
These are placeholder objects inside expecco, which will look like regular Smalltalk (or JavaScript) objects inside expecco, but will forward any call via the socket ower to the bridge partner.

Thus, they can be used transparently inside Smalltalk and JavaScript elementary actions, performing whatever is implemented in the remote side.

For example, given a Java bridge connection named "bridge", you can instantiate a remote object there from within your local JavaScript code with:
var remoteArrayListClass, myList;
remoteArrayListClass = bridge.resolveType("java.util.ArrayList");
myList = new remoteArrayListClass(10);
myList.add("hello");
...
in a Smalltalk action, the code is similar:
|remoteArrayList myList|
remoteArrayListClass := bridge resolveType:'java.util.ArrayList'.
myList := remoteArrayListClass new:10.
myList add:'hello'.
...

This works without any remote code injection and is typically a bit faster than via Groovy. However, the language syntax is the local expecco syntax, which might be inconvenient to hard-core Java programmers (and the same is true for proxies to other language's bridge objects).

Remote proxy objects are also returned by the "<code>makeRef</code>" API as described in the API documentation, and when remote objects are inspected in the expecco data inspector window.

== What can I do if a Bridge is Dead(locked) ==

The code executed in the bridge may run into an endless loop (for example, if your elementary code contains a bug), or when it calls a function which does not return.
As a consequence, the corresponding elementary action will not finish.

Try to stop or abort the execution via the corresponding toolbar function (in the expecco editor page).
Even though the corresponding expecco action has now finished (i.e. expecco will no longer wait for the action's return value and status), a problem might be reported when expecco is about to call another action inside that bridge: the bridge will still be in its loop, and the bridge will therefore not respond and expecco will report that the bridge is no longer answering.

You now have to kill the bridge, and start a new one, with the undesired consequence of loosing any state inside the previous bridge incarnation. Especially, any connections in the previous bridge are now lost.

To kill the bridge, perform one of the following:
* click the "''Terminate Bridge''" toolbar button in the "Test/Demo" tab. This will terminate that language's bridges
* select "''Extras''" → "''Debugging''" → "''Close all Bridge Connections''" This will terminate all running bridges (maybe this is not what you want)
* select "''Extras''" → "''Debugging''" → "''OS Process Monitor''" to get a list of all OS processes which have been started by expecco, select the one to terminate and choose "''Terminate''" from the context menu.
* select and terminate the bridge process in the Task Manager (Windows) or find its processID with the "ps" command and terminate it via the "kill" command (Unix)

If the bridge was not originally started by expecco (eg. if it is a remote bridge, which was started automatically or by a remote command), you have to log into that remote machine and terminate the bridge there.

In a production system, you may add time limits to actions which might suffer from locked bridges, and add a bridge-terminate action (found in the Standard Library) to be triggered via the exception pin of the time-controlled action.

== I got an Object (Reference) from a Bridge but Access to its Fields is Slow ==
Be reminded ([[#What_are_Proxy_Objects |see above]]), that when an object (reference) is returned from a bridge to expecco, a proxy (placeholder object) is created inside expecco, which is what appears at the output pin.
This proxy object will intercept any calls to it and forward them to the real object inside the bridge, then wait for a response (the return value) and encode that again as a proxy.

Thus, every such operation involves a round trip which is typically in the order of milliseconds (if the bridge is on a remote machine, and additional routers/switches are involved, the round trip times may even be in the 10-millisecond range).
These times can easily add up to seconds, for example if you enumerate a remote collection with many elements.

Possible solutions to that problem:
* install the code which enumerates the object inside the bridge (i.e. define another elementary action or require/import a piece of code which contains this functionality. Then call this code which runs completely inside the bridge.
* pass the object's encoding (for example as JSON) and decode it on the expecco side for the enumeration. This one call will then probably run much slower, but further processing (enumeration of elements) is much faster. This is the way to go, if bulk data has been collected inside the bridge, which has to be analyzed inside expecco afterwards. Be aware though, that the object inside expecco is effectively a "copy" of the object; if the object will change inside the bridge, expecco will still present the old state.

== I get Timeouts - how can I change the Defaults ? ==
There is currently no dialog to change the default settings (except for the CBridge in v23.1).

However, the default values which control the timeouts can be changed via Smalltalk expressions (or corresponding JavaScript expressions).
 To set a common default for all Python, CBridge and NodeJS bridge In Smalltalk syntax:
SimpleBridge connectTimeout: ''seconds''.
SimpleBridge defineAckTimeoutMS: ''millis''.
SimpleBridge executeAckTimeoutMS: ''millis''.
or in JavaScript syntax:
SimpleBridge.connectTimeout(''seconds'');
SimpleBridge.defineAckTimeoutMS(''millis'');
SimpleBridge.executeAckTimeoutMS(''millis'');

We are sorry for the inconsistent argument (seconds vs. milliseconds); these result from history and later added features. We will provide a consistent interface in later versions.

To set the default for individual language bridges:
PythonBridge connectTimeout: ''seconds''.
PythonBridge defineAckTimeoutMS: ''millis''.
PythonBridge executeAckTimeoutMS: ''millis''.

CBridge connectTimeout: ''seconds''.
CBridge defineAckTimeoutMS: ''millis''.
CBridge executeAckTimeoutMS: ''millis''.

NodeJSBridge connectTimeout: ''seconds''.
NodeJSBridge defineAckTimeoutMS: ''millis''.
NodeJSBridge executeAckTimeoutMS: ''millis''.

You can retrieve the default values via corresponding getter messages:
<someBridgeClass> connectTimeout => that bridge type's connectTimeout
<someBridgeClass> defineAckTimeoutMS => that bridge type's defineAckTimeout in milliseconds
<someBridgeClass> executeAckTimeoutMS => that bridge type's executeAckTimeout in milliseconds

"connectTimeout" is relevant, when connecting to a remote machine;
 "defineAckTimeoutMS" is the time expecco will wait for a confirmation after an action's code has been transferred to the bridge;
 "executeAckTimeoutMS" is the time expecco waits for an acknowledge after sending an action-step's data (pin values). See note below.

To be effective, these default values must be set before a bridge connection is setup.
You can either place these expressions into the "startup.rc" file (in the expecco installation folder), or into a test suite as an elementary (Smalltalk or JavaScript) action which is executed as post-load action or as a prepare action of a testplan.

The above control the default values for new bridge connections. You can also change an existing connection's parameter by sending the same messages to a concrete bridge.

Expecco 21.2:
:You may have to adjust the executeAckTimeout, if huge amounts of data are transfered.
:(we encountered this limit eg. when transferring a vector of 1 mio floats to the bridge)
Expecco 22.1:
:Expecco adjusts this automatically to match the amount of data.

== I don't see the difference between DLL actions and bridged C-actions; when to use which? ==

DLL action blocks - when executed - will ensure that the specified DLL (shared object) is loaded into the running expecco program and directly called from within expecco. In other words: it executes in the same address space as expecco.

On the other hand, C-Bridge actions are executed by a separate program (the "''CBridge''") and expecco communicates with that program via a socket connection.

Both mechanisms have advantages and disadvantages:

DLL actions:
 '''(+)''' very fast call (no remote procedure call)
 '''(+)''' very fast data transmission (especially, big vectors can be passed quickly)
 '''(+)''' can be used if only the binary is present and no compiler toolchain is needed/wanted
 '''(-)''' the called code may crash the expecco executable if it misbehaves or is provided with wrong arguments (notice: although expecco tries to catch any illegal memory references, it may still happen, that a called DLL-function misbehaves and overwrites/manipulates memory which it is not supposed to. For example, if it overwrites any data of expecco, there may be a later crash in expecco.
 '''(-)''' the called code may block expecco or slow down the user interface
 '''(-)''' the called code may exit/terminate the current thread or the program and thus terminate expecco (i.e. make sure, it does not call "<code>exit()</code>"). Although expecco sets the "atexit" handler, shared libraries may still find other means to terminate.

Bridged Calls:
 '''(+)''' code runs completely isolated from expecco - the bridge may crash due to bad data or a bad library call, but expecco will remain alive. You'll get a fail-status of the corresponding action in expecco.
 '''(+)''' additional data conversions or checks are easily added (in case the called function's interface requires complicated object structures, such as complex structures/unions, pointers to pointers, pointers to return values etc.)
 '''(+)''' better support for debugging (writing log-entries, adding printfs or running the cBridge under a debugger)
 '''(+)''' the expecco UI will not be blocked by a runaway bridged action
 '''(+)''' the bridged action can be executed on the local or on a remote machine
 '''(+)''' the bridged action can be executed on a different operating system or CPU architecture (eg. expecco runs on a Linux machine, the bridge on Windows or even in a RasperryPI)
 '''(+)''' multiple bridged C actions can execute in parallel on multiple machines or in multiple processes on one machine
 '''(-)''' the round trip times are quite long compared to direct DLL calls (in the order of milliseconds, in contrast to direct DLL calls, which run in the order of nanoseconds)
 '''(-)''' multiple round trips if many fields of returned object references have to be accessed
 '''(-)''' a C-compiler toolchain is needed (on the local or the target system, where the bridged C code is to be executed)

Despite the above mentioned performance differences, we highly recommend to use bridged C actions instead of direct DLL calls, iff the performance/round trip times are acceptable. The added safety due to the process boundaries makes it much easier to develop and maintain those.

== How can I debug the code in the bridge ==
Expecco does include some limited debugging support for bridged code, but the level of support is different between individual bridges:
* Python, Node, Smalltalk, Groovy Support breakpoints and single stepping. Walkback and some access to remote objects.
* C Walkback and some access to remote objects.

To debug bridged C-code, we recommend executing the bridge inside a debugger; for example, under Unix, you would compile your framework with the "-g" (debug) option, then open a shell terminal window and start the bridge under a debugger (say "lldb" or "gdb") with:
lldb cBridge
>> r --server --port 8899
then change the expecco settings for the CBridge to "''Connect to an already running bridge''" and also define the port there. Expecco will then connect to your debugged bridge instead of starting one itself.
A similar setup is to be used when debugging with Eclipse or Visual Studio on Windows.

To debug Python code, you can check the "''Disable Debugger''" flag in the Python settings, and attach a Python debugger (eg. VSCode) to the running Python process.

== Security Considerations ==
Make sure that remote bridges are only reachable from inside your local network and only from trusted hosts. You should configure your firewall as appropriate, or run tests in an isolated network. You may also configure switches and routers to limit access, or use a secondary interface (alternative lan or wifi).

Another recommened option is to setup an ssh tunnel for the particular port(s) in question.

All bridges support command line arguments to only accept connections from a particular host; this option should be used if a remote bridge is started via a remote shell command.

=== SSL/TLS Encrypted Connections ===
All bridges support SSL/TLS encrypted connections. This provides both confidentiality and (with mutual TLS) authentication.

To enable SSL for a bridge connection, configure the following in the expecco bridge settings (under "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''CBridge''" or "''Python''"):
* '''Use SSL''': enable TLS encryption
* '''Certificate File''': PEM file containing the server certificate and private key (used by the bridge process)
* '''Client Certificate''': the client certificate for mutual TLS authentication. The PEM content is stored directly in the expecco preferences. Use the '''"..."''' button to load from a file, '''"?"''' to inspect the certificate chain, and '''"X"''' to clear it. On load, the certificate chain is validated (expiry, CA flag, key identifier match).

When the client certificate PEM includes the CA certificate in the chain, the CA is automatically trusted for server verification.

Certificate generation is built into the cBridge and Python bridge executables using Ed25519 keys:
cBridge --generateCA ca.pem --cn "My CA"
cBridge --generateCert server.pem --ca ca.pem --cn myhost
cBridge --generateCert client.pem --ca ca.pem --cn expecco

Generated PEM files include the full certificate chain.

For mutual TLS (mTLS), start the remote bridge with the <code>--clientAuth</code> flag:
cBridge --port 8855 --ssl --cert server.pem --clientAuth

See [[Cbridge_setup#SSL/TLS_Connection_to_a_Remote_CBridge|CBridge Setup: SSL/TLS Connection]] for detailed instructions.

== File Transfer and Remote Directory Operations ==
All bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk) support transferring files between expecco and the remote bridge:
* <code>putFile: localPath to: remotePath</code> — upload a file to the bridge
* <code>getFile: remotePath to: localPath</code> — download a file from the bridge
* <code>makeDirectory: remotePath</code> — create a directory (including parent directories) on the bridge

These operations use the existing bridge connection and work over SSL if enabled. They are useful for deploying test data, collecting results, or transferring compiled binaries.

== [OS X Only] CrashReporter Dialog Boxes ==
You may get annoying dialog boxes telling about "''Unexpected Termination''" whenever a bridge is hard terminated via the "''Terminate''" button in the debugger.

This is a "''feature''" of the OS X system, not controlled by expecco.

You can disable this by executing the following command in a console terminal:
defaults write com.apple.CrashReporter DialogType none

Back to [[FAQ/en | FAQ]]

Cbridge setup

2026-05-27T13:48:21Z

Sv: update SSL settings: client cert stored in prefs, load/inspect/clear buttons, chain validation

= CBridge Setup =

In order to compile and execute C/C++ actions, a C compiler toolchain has to be installed on the machine, where the Bridge executable (Windows: <code>cBridge.exe</code> / Unix: <code>cBridge</code>) runs.
 Typically this is the local machine on which expecco runs, but it may be any other machine in your reachable network.
 The CPU architecture and or operating system may be (and often is) different from the CPU which executes expecco, therefore the C-code is compiled on the target machine (i.e. not cross-compiled).

== C-Compiler Toolchain Installation ==

=== Windows + Borland Compiler (32bit) ===
The compiler is a bit outdated, but still free and useful. However, it only supports 32bit programs. Thus, it cannot be used if you need access to 64bit dlls. (on the other hand, if you need to interact with a 32bit dll to communicate with some hardware device, you'll must use a 32bit cBridge).

We recommend to install the toolchain at its default installation path (typically "<code>C:\borland</code>"). Then, the provided cc-compile script for borland can be used unchanged.

=== Windows + MINGW Compiler (32 or 64bit) ===
The mingw toolchain is based on the gcc compiler. This is recommended and preferred over borland.

=== Windows + Microsoft Visual C / Visual Studio ===
There is no need to install the full Visual Studio IDE. Only the C-compiler, linker and libraries are required.
Thus, you can untoggle all additional optional packages during the installation.

Check for the "<code>cl</code>" command (being in your <code>PATH</code>) or find and remember the path to it (typically somewhere under "<code>c:\Program Files\Microsoft\...</code>").

=== Unix / Linux ===
Install whatever packages are required; check if the "<code>cc</code>" command is found along your <code>PATH</code> (before starting expecco),
or alternatively, remember the path to the "<code>cc</code>" command.

Regardless of which compiler you use,
please remember the installation path. You will need it later unless the compiler is found along your <code>PATH</code>.

== Quick Check if it Already Works ==
We provide a number of setups for common installations.
In many situations, this will already be correct for your setup.

To check, create a new elementary-bridgedC action, and run it.
(the initial tree which is created with examples also contains a simple C action).

If you get a green OK result, you're already done.
If not, your setup needs to be adjusted.

Read the chapter at the end of this page on step-by-step setup verification.

== The Compile Script ==
For compilation, the cBridge program calls a batch/shell script, which is responsible for compilation of the C-code to a DLL/shared object file.
This script may need to be edited.
We recommend, that you navigate to the folder where the cBridge executable is located, take one of the existing scripts as template, make a copy under a new name, and then edit this copy to suit your needs.

Take one of the existing scripts which uses the same compiler (borland/mingw/visualC).

In the editor, check the <code>PATH</code> setting, and edit it as appropriate, finally save it.

Back in expecco, go to the cBridge settings under the external-script settings,
and change the CC-script setting there ("''Extras''" - "''Settings''" - "''Execution''" - "''External Script Interpreters''" - "''CBridge''").

Shutdown any already running bridge ("''Extras''" - "''Debugging''" - "''Shutdown all Bridge Connections''")

Go back to the C-action and repeat the quick check.

Eventually, you should see a green OK result.

== Special Additional Libraries ==

It may be required that your C-code needs additional shared libraries to be linked against your code.
The easiest is to add those libraries and corresponding command line options to the CC-script's compiler call command.
The details depend on the compiler used.
You may need to do a "<code>cc --help</code>", "<code>cl/help</code>" or similar, to figure out which command line options are required.

= Remote C-Bridges =
You can run any number of cBridges on any machine within your network (and also multiple cBridges on your local or a remote machine), and execute C-actions there. For this, the following setup steps are to be performed:

* copy the cbridge executable and its support files to a new folder on the target machine; the files are found below the expecco installation folder (eg. "<code>c:\Program Files\exept\expecco</code>") in "<code>packages\bridgeFramework\cBridge\cLibrary</code>".
:The easiest way is to copy the whole folder. Make sure that the copied folder matches the target machine's architecture (i.e. if the target is a Linux machine, you must obviously copy the files from a Linux installation, and same so for Windows machines).

* on the remote machine, make sure that the cBridge is running; either by executing a remote command from inside your expecco suite, or by adding the cBridge startup to a cron tab (Unix/Linux) or the service list or autoexec.bat (Windows).
:As a test, start it manually with: "<code>cBridge --port 8856</code>", and connect to it from expecco (change the settings ("''Extras''" - "''Settings''" - "''Execution''" - "''External Script Interpreters''" - "''CBridge''") to connect to an already running cBridge at that port).

* if in doubt, start the cBridge with a "<code>--help</code>" option.

=== CBridge Command Line Arguments ===

* --help Prints a list of the supported comamnd line arguments
* --localOnly only accept connections from the local machine
* --host ''hostname'' connect to that host instead of waiting for incoming connections
* --port the TCP port on which the bridge is waiting for incoming requests or connecting to (with --host argument)
* -- keepAlive after the first connection, keep on waiting for more incoming connections. Without this, the bridge will only handle a single session and exit after that.
* --log log actions on stderr
* --log2 even more detailed log
* --ccScript ''scriptFile'' Use the given script file (a shell or batch script) to compile
* --includes ''files'' Additional include folders passed to the compile script
* --dlls ''files'' Additional dlls (shared libraries) to be linked against actions
* --testCompile For a standalone selftest if compilation works. Compiles a dummy almost empty source file

More arguments may be recognized, depending on the cBridge version. Use "--help" to see more.

=== SSL/TLS Connection to a Remote CBridge ===

The cBridge supports encrypted TLS connections with optional mutual certificate authentication (mTLS).

==== Generating Certificates ====
The cBridge can generate Ed25519 CA and server/client certificates directly:

cBridge --generateCA ~/.ssl/ca.pem --cn "My CA" --days 3650
cBridge --generateCert ~/.ssl/server.pem --ca ~/.ssl/ca.pem --cn myhost
cBridge --generateCert ~/.ssl/client.pem --ca ~/.ssl/ca.pem --cn expecco

Each generated PEM file contains the certificate, private key, and the CA certificate chain. The <code>--cn</code> option sets the common name (default: localhost), <code>--days</code> sets the validity period (default: 3650).

The same certificate generation is also available via the Python bridge script (<code>--generateCA</code> / <code>--generateCert</code>).

==== Starting the CBridge with SSL ====

cBridge --port 8855 --ssl --cert ~/.ssl/server.pem

A combined PEM file (certificate + key in one file) is used by default. Separate files are also supported:

cBridge --port 8855 --ssl --cert server.crt --key server.key

==== Mutual TLS (Client Certificate Authentication) ====

To require clients to present a certificate signed by the same CA:

cBridge --port 8855 --ssl --cert ~/.ssl/server.pem --ca ~/.ssl/ca.pem --clientAuth

Clients must then be configured with a client certificate (see the expecco CBridge settings dialog).

==== Expecco Settings for SSL ====

In expecco, configure the CBridge connection under "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''CBridge''":
* '''Use SSL''': enable encrypted connection
* '''Certificate File''': the server certificate PEM (used by the bridge process)
* '''Client Certificate''': load a client certificate PEM for mutual TLS authentication. The certificate is stored in the expecco preferences (not as a file path). Use the buttons:
** '''"..."''' to load a certificate from a PEM file
** '''"?"''' to inspect the certificate chain (shows subject, issuer, validity, algorithm, CA flag, private key presence, and chain verification via AuthorityKeyIdentifier)
** '''"X"''' to remove the stored certificate
: On load, the certificate chain is validated: the leaf certificate must not be expired, the CA must have the BasicConstraints CA flag set, and the AuthorityKeyIdentifier must match the CA's SubjectKeyIdentifier (or the issuer DN must match).

When the client certificate PEM includes the CA certificate in the chain, the CA is automatically trusted for server certificate verification — no need to enable "Allow Self-Signed Certificates".

The same SSL and client certificate settings are also available in the Python bridge settings dialog ("''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Python''").

==== File Transfer and Directory Operations ====
All bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk) support file transfer to and from the remote bridge:
* <code>putFile: localPath to: remotePath</code> — upload a file
* <code>getFile: remotePath to: localPath</code> — download a file
* <code>makeDirectory: remotePath</code> — create a directory (including parent directories)

These operations work over the bridge's existing connection (including SSL if enabled).

= Step-by-Step Problem Finding/Fixing =

=== Ensure that the cBridge executable is present and can be executed ===
* goto the expecco installation folder (typically somewhere under "<code>c:\Program Files\exept\expecco\</code>"), and look for files named "<code>cBridge.exe</code>" or "<code>cBridge32.exe</code>" or "<code>cBridge</code>" (under Unix/Linux). It is typically found in a sub folder named "<code>packages/expecco/bridgeFramework/cBridge</code>".
* open a shell- or cmd window (and navigate there).
* type "<code>cBridge --help</code>" (with powershell: "<code>.\cBridge --help</code>")
:: if that fails (does not output some useful help text), make sure that it can be executed. Maybe your security policy is too strict ot the installation is incomplete.
* start the bridge with "<code>cBridge --log</code>"
:: it should output some messages, the last being "<code>... listening on port xxxx</code>"
* if the cBridge is to run on a machine different from the one expecco is running on, make sure that the firewall allows for connections between the two machines (at the desired port nr)
* if required, use another port (i.e. run it with "<code>cBridge --log --port <Nr></code>")
:: now we have a cBridge running, ready to accept connections from expecco at the given port nr.
* keep the shell/cmd window open; we will need it later (and also to see any diagnostic output)

=== Ensure that the cBridge is reachable from expecco ===
for this, we first try to connect to that already running bridge (instead of letting expecco start it itself)
* in expecco, open the settings and navigate to the cBridge settings:
:: "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''CBridge''"
* check the "''Connect to already Running Bridge''" box.
:: enter CBridge Host and Port as "<code>localhost</code>" and the above port number (default is 8855)
* close the settings dialog (without saving the settings for now, when asked)
* open a new project. The default project will contain a sample "Hello World" C-action, which can be used for the smoke test.
* in the expecco tree, find the "<code>Simple Elementary Action (C)</code>" (under the "Activities" group).
* run it
:: if the error states that no connection could be setup, check your security policy, firewall etc. and repeat
:: if the error states that the compilation failed, the bridge connection works, but the compilation script setup is wrong. Proceed.

=== Ensure that the compilation works ===
the cBridge needs a C-compiler for its operation; to verify,
* stop the manually started C-bridge (in the shell/cmd window) by pressing CTRL-C there
* depending on the C-compiler you intend to use, one of the "compile_xxx.bat" or "compile_xxx.sh" script files will be used. The task to be performed by these scripts is to compile a given C-file.
* check which compiler you installed and intent to use (MSVC, Mingw, gcc, clang or bcc), and look for a corresponding script file.
* check if the compiler is correctly installed (especially MSVC and MINGW sometimes make trouble here).
:: one particular problem with MSVC is when deinstalling and reinstalling another version. There seem to be leftover files and/or registry entries which may break the installation (this happend to one of our customers, and also to us when upgrading)
* Enter the compile-command ("cl", "cc", "gcc" or "clang") on a command line (cmd or shell)
:: check that you get an answer
:: try to compile a one-liner (eg. "<code>main() { printf("hello\n"); }</code>" and run it to see if it links correctly. Run it!
* check if the bridge's cc script file works by running "<code>cBridge --log --ccScript <scriptfilename> --testCompile</code>"
:: if required, make a copy of one of the script files (the one you think is best to start with) and fix any path inside. If required, add echo statements to show what is going on. Keep the original script and create a new one.
:: under Windows: in the script, the PATH to the compiler is typically searched and set; for example by calling the vcvarsall.bat script which is provided by microsoft. If required, change the line which calls this (you can also add this batch-call to your autoexec.bat and remove the line from the script). In any case: at the end, the "cl" command should be found along your path.
* the --testCompile will generate a piece of code which outputs "here is foo"; i.e. on your system (we use mingw), the command is "<code>cBridge --log --ccScript compile_windows_mingw.bat" --testCompile</code>", and the output is "here is foo" - "void pointer size: 8", followed by the usual "listening on port" message.

=== Change the Settings in expecco ===
* open the cBridge settings again
* uncheck the "''Connect to already running bridge''" box
* enter the name of the compile script into the "CC-script" field (possibly the name of the new script)
* shutdown any already running bridge
* try executing the expecco-C action again
* if you get a green outcome, save your expecco settings.

FAQ on Bridges/en

2026-05-27T07:02:32Z

Sv: add SSL/TLS section and file transfer/makeDirectory documentation

== Why Bridged Actions and not Script Actions? ==

Script actions will start the language interpreter anew for every such action. Thus, no internal state can be held and transferred from one such action to another. Especially, it is not possible to open a communication channel on one script action, pass it back to expecco, and use it with different followup script actions (i.e. actions like "''open-port''" / "''send message''" / "''receive message''" / "''close port''" etc.).

For this, it is required to call individual API-entries inside the bridge code, and return handles from the bridge to expecco, which can later be passed to other API entries. This of course only makes sense, if the interpreter stays active during the lifetime of the connection.

On the other hand, script actions are easier to use if a self contained program or app is to be started, or which performs a single processing action or which stays alive for longer, serving a socket or database. In any such case, there is no need to exchange individual data objects (such as handles) with expecco. It may however interact with expecco through other communication channels, such as sockets, RPC calls, SOAP interface or stdin/stdout text ports.

Thus, you will typically use script actions to start server applications and bridged actions to call individual functions of a framework.

== Which Languages are Supported ==

By the time this chapter was written, bridged code execution is supported for:
* Java (using either Groovy or Jython as "''glue''" or directly using proxy objects in expecco)
* Python (both Python 2.7 and Python 3.x)
* .NET (using IronPython as "''glue''" or directly via proxy objects)
* NodeJS (i.e. JavaScript)
* C/C++ (Root/Cling is being developed currently)
* Smalltalk (Smalltalk/X and VisualWorks are currently supported; VisualAge may come in the near future, if there is sufficient customer interest)
* Ruby
Plans are to support Dart and Scheme in the future.

== How are Bridges Started ==

Bridges on the local machine are usually automatically started by expecco itself, when the first bridged action is executed (and stays alive, until expecco is terminated, or bridge connections are closed via the menu or via an expecco action block). Some language interpreters may take a few seconds to come up, so the first such action will execute relatively slow compared to later actions. You can add a dummy (empty) bridged action to your startup actions (project's postLoad action) to prepare the bridged interpreter and have it startup in parallel.

Bridges on other machines, or additional bridges on the local machine must be started by executing a bridge start action block or simply by executing a shell/batch action to call the corresponding language interpreter (python, node, etc.). On Windows, a powershell action can be used for remote execution (given that your Windows security settings allow that). On Unix, a shell action executin a remote shell / ssh command could be used.

== Who Initiates the Connection ==

Normally, expecco opens a port and tells the bridge (via command line argument) to which port to connect. Depending on the setup of your network and firewall, it may sometimes be required to reverse this, and let the bridge open a port and expecco connect to it.

For this, some bridges support command line arguments ("--server" and "--port") to specify this behavior. Details are found in the individual bridge documentation pages.

== Ports Used for Bridge Communication ==

Unless ports are configured in the expecco settings,
the following default ports are used (bridges typically listen on or connect to this port, unless an explicit "--port" argument is given):

Python 8677 , 8678 (debug)
Python2 8679 , 8680 (debug)
Python3 8681 , 8682 (debug)
Jython 8777 , 8778 (debug)
IronPython 8787 , 8788 (debug)
Node 8577 , 8578 (debug)
Electron 8588 , 8589 (debug)
[[Embedded_Systems_C_Bridge_API |CBridge]] 8855 (also for Root/Cling)
Smalltalk 8877
VASmalltalk 8879
VWSmalltalk 8881
Dart 8885
Ruby 8977
Scheme 8599

Note: for some bridges, two connections are used, the debug port being used by the debugger to inspect data and to support breakpoints, single stepping etc.
 Note: expecco will try successive alternative ports, if the default port happens to be already in use.

Debugging is not supported on all bridges (eg. the C-bridge does not).

== What are Proxy Objects ==
These are placeholder objects inside expecco, which will look like regular Smalltalk (or JavaScript) objects inside expecco, but will forward any call via the socket ower to the bridge partner.

Thus, they can be used transparently inside Smalltalk and JavaScript elementary actions, performing whatever is implemented in the remote side.

For example, given a Java bridge connection named "bridge", you can instantiate a remote object there from within your local JavaScript code with:
var remoteArrayListClass, myList;
remoteArrayListClass = bridge.resolveType("java.util.ArrayList");
myList = new remoteArrayListClass(10);
myList.add("hello");
...
in a Smalltalk action, the code is similar:
|remoteArrayList myList|
remoteArrayListClass := bridge resolveType:'java.util.ArrayList'.
myList := remoteArrayListClass new:10.
myList add:'hello'.
...

This works without any remote code injection and is typically a bit faster than via Groovy. However, the language syntax is the local expecco syntax, which might be inconvenient to hard-core Java programmers (and the same is true for proxies to other language's bridge objects).

Remote proxy objects are also returned by the "<code>makeRef</code>" API as described in the API documentation, and when remote objects are inspected in the expecco data inspector window.

== What can I do if a Bridge is Dead(locked) ==

The code executed in the bridge may run into an endless loop (for example, if your elementary code contains a bug), or when it calls a function which does not return.
As a consequence, the corresponding elementary action will not finish.

Try to stop or abort the execution via the corresponding toolbar function (in the expecco editor page).
Even though the corresponding expecco action has now finished (i.e. expecco will no longer wait for the action's return value and status), a problem might be reported when expecco is about to call another action inside that bridge: the bridge will still be in its loop, and the bridge will therefore not respond and expecco will report that the bridge is no longer answering.

You now have to kill the bridge, and start a new one, with the undesired consequence of loosing any state inside the previous bridge incarnation. Especially, any connections in the previous bridge are now lost.

To kill the bridge, perform one of the following:
* click the "''Terminate Bridge''" toolbar button in the "Test/Demo" tab. This will terminate that language's bridges
* select "''Extras''" → "''Debugging''" → "''Close all Bridge Connections''" This will terminate all running bridges (maybe this is not what you want)
* select "''Extras''" → "''Debugging''" → "''OS Process Monitor''" to get a list of all OS processes which have been started by expecco, select the one to terminate and choose "''Terminate''" from the context menu.
* select and terminate the bridge process in the Task Manager (Windows) or find its processID with the "ps" command and terminate it via the "kill" command (Unix)

If the bridge was not originally started by expecco (eg. if it is a remote bridge, which was started automatically or by a remote command), you have to log into that remote machine and terminate the bridge there.

In a production system, you may add time limits to actions which might suffer from locked bridges, and add a bridge-terminate action (found in the Standard Library) to be triggered via the exception pin of the time-controlled action.

== I got an Object (Reference) from a Bridge but Access to its Fields is Slow ==
Be reminded ([[#What_are_Proxy_Objects |see above]]), that when an object (reference) is returned from a bridge to expecco, a proxy (placeholder object) is created inside expecco, which is what appears at the output pin.
This proxy object will intercept any calls to it and forward them to the real object inside the bridge, then wait for a response (the return value) and encode that again as a proxy.

Thus, every such operation involves a round trip which is typically in the order of milliseconds (if the bridge is on a remote machine, and additional routers/switches are involved, the round trip times may even be in the 10-millisecond range).
These times can easily add up to seconds, for example if you enumerate a remote collection with many elements.

Possible solutions to that problem:
* install the code which enumerates the object inside the bridge (i.e. define another elementary action or require/import a piece of code which contains this functionality. Then call this code which runs completely inside the bridge.
* pass the object's encoding (for example as JSON) and decode it on the expecco side for the enumeration. This one call will then probably run much slower, but further processing (enumeration of elements) is much faster. This is the way to go, if bulk data has been collected inside the bridge, which has to be analyzed inside expecco afterwards. Be aware though, that the object inside expecco is effectively a "copy" of the object; if the object will change inside the bridge, expecco will still present the old state.

== I get Timeouts - how can I change the Defaults ? ==
There is currently no dialog to change the default settings (except for the CBridge in v23.1).

However, the default values which control the timeouts can be changed via Smalltalk expressions (or corresponding JavaScript expressions).
 To set a common default for all Python, CBridge and NodeJS bridge In Smalltalk syntax:
SimpleBridge connectTimeout: ''seconds''.
SimpleBridge defineAckTimeoutMS: ''millis''.
SimpleBridge executeAckTimeoutMS: ''millis''.
or in JavaScript syntax:
SimpleBridge.connectTimeout(''seconds'');
SimpleBridge.defineAckTimeoutMS(''millis'');
SimpleBridge.executeAckTimeoutMS(''millis'');

We are sorry for the inconsistent argument (seconds vs. milliseconds); these result from history and later added features. We will provide a consistent interface in later versions.

To set the default for individual language bridges:
PythonBridge connectTimeout: ''seconds''.
PythonBridge defineAckTimeoutMS: ''millis''.
PythonBridge executeAckTimeoutMS: ''millis''.

CBridge connectTimeout: ''seconds''.
CBridge defineAckTimeoutMS: ''millis''.
CBridge executeAckTimeoutMS: ''millis''.

NodeJSBridge connectTimeout: ''seconds''.
NodeJSBridge defineAckTimeoutMS: ''millis''.
NodeJSBridge executeAckTimeoutMS: ''millis''.

You can retrieve the default values via corresponding getter messages:
<someBridgeClass> connectTimeout => that bridge type's connectTimeout
<someBridgeClass> defineAckTimeoutMS => that bridge type's defineAckTimeout in milliseconds
<someBridgeClass> executeAckTimeoutMS => that bridge type's executeAckTimeout in milliseconds

"connectTimeout" is relevant, when connecting to a remote machine;
 "defineAckTimeoutMS" is the time expecco will wait for a confirmation after an action's code has been transferred to the bridge;
 "executeAckTimeoutMS" is the time expecco waits for an acknowledge after sending an action-step's data (pin values). See note below.

To be effective, these default values must be set before a bridge connection is setup.
You can either place these expressions into the "startup.rc" file (in the expecco installation folder), or into a test suite as an elementary (Smalltalk or JavaScript) action which is executed as post-load action or as a prepare action of a testplan.

The above control the default values for new bridge connections. You can also change an existing connection's parameter by sending the same messages to a concrete bridge.

Expecco 21.2:
:You may have to adjust the executeAckTimeout, if huge amounts of data are transfered.
:(we encountered this limit eg. when transferring a vector of 1 mio floats to the bridge)
Expecco 22.1:
:Expecco adjusts this automatically to match the amount of data.

== I don't see the difference between DLL actions and bridged C-actions; when to use which? ==

DLL action blocks - when executed - will ensure that the specified DLL (shared object) is loaded into the running expecco program and directly called from within expecco. In other words: it executes in the same address space as expecco.

On the other hand, C-Bridge actions are executed by a separate program (the "''CBridge''") and expecco communicates with that program via a socket connection.

Both mechanisms have advantages and disadvantages:

DLL actions:
 '''(+)''' very fast call (no remote procedure call)
 '''(+)''' very fast data transmission (especially, big vectors can be passed quickly)
 '''(+)''' can be used if only the binary is present and no compiler toolchain is needed/wanted
 '''(-)''' the called code may crash the expecco executable if it misbehaves or is provided with wrong arguments (notice: although expecco tries to catch any illegal memory references, it may still happen, that a called DLL-function misbehaves and overwrites/manipulates memory which it is not supposed to. For example, if it overwrites any data of expecco, there may be a later crash in expecco.
 '''(-)''' the called code may block expecco or slow down the user interface
 '''(-)''' the called code may exit/terminate the current thread or the program and thus terminate expecco (i.e. make sure, it does not call "<code>exit()</code>"). Although expecco sets the "atexit" handler, shared libraries may still find other means to terminate.

Bridged Calls:
 '''(+)''' code runs completely isolated from expecco - the bridge may crash due to bad data or a bad library call, but expecco will remain alive. You'll get a fail-status of the corresponding action in expecco.
 '''(+)''' additional data conversions or checks are easily added (in case the called function's interface requires complicated object structures, such as complex structures/unions, pointers to pointers, pointers to return values etc.)
 '''(+)''' better support for debugging (writing log-entries, adding printfs or running the cBridge under a debugger)
 '''(+)''' the expecco UI will not be blocked by a runaway bridged action
 '''(+)''' the bridged action can be executed on the local or on a remote machine
 '''(+)''' the bridged action can be executed on a different operating system or CPU architecture (eg. expecco runs on a Linux machine, the bridge on Windows or even in a RasperryPI)
 '''(+)''' multiple bridged C actions can execute in parallel on multiple machines or in multiple processes on one machine
 '''(-)''' the round trip times are quite long compared to direct DLL calls (in the order of milliseconds, in contrast to direct DLL calls, which run in the order of nanoseconds)
 '''(-)''' multiple round trips if many fields of returned object references have to be accessed
 '''(-)''' a C-compiler toolchain is needed (on the local or the target system, where the bridged C code is to be executed)

Despite the above mentioned performance differences, we highly recommend to use bridged C actions instead of direct DLL calls, iff the performance/round trip times are acceptable. The added safety due to the process boundaries makes it much easier to develop and maintain those.

== How can I debug the code in the bridge ==
Expecco does include some limited debugging support for bridged code, but the level of support is different between individual bridges:
* Python, Node, Smalltalk, Groovy Support breakpoints and single stepping. Walkback and some access to remote objects.
* C Walkback and some access to remote objects.

To debug bridged C-code, we recommend executing the bridge inside a debugger; for example, under Unix, you would compile your framework with the "-g" (debug) option, then open a shell terminal window and start the bridge under a debugger (say "lldb" or "gdb") with:
lldb cBridge
>> r --server --port 8899
then change the expecco settings for the CBridge to "''Connect to an already running bridge''" and also define the port there. Expecco will then connect to your debugged bridge instead of starting one itself.
A similar setup is to be used when debugging with Eclipse or Visual Studio on Windows.

To debug Python code, you can check the "''Disable Debugger''" flag in the Python settings, and attach a Python debugger (eg. VSCode) to the running Python process.

== Security Considerations ==
Make sure that remote bridges are only reachable from inside your local network and only from trusted hosts. You should configure your firewall as appropriate, or run tests in an isolated network. You may also configure switches and routers to limit access, or use a secondary interface (alternative lan or wifi).

Another recommened option is to setup an ssh tunnel for the particular port(s) in question.

All bridges support command line arguments to only accept connections from a particular host; this option should be used if a remote bridge is started via a remote shell command.

=== SSL/TLS Encrypted Connections ===
All bridges support SSL/TLS encrypted connections. This provides both confidentiality and (with mutual TLS) authentication.

To enable SSL for a bridge connection, configure the following in the expecco bridge settings:
* '''Use SSL''': enable TLS encryption
* '''Certificate File''': PEM file containing the server certificate and private key (used by the bridge process)
* '''Client Certificate File''': PEM file containing the client certificate and private key (presented to servers that require client authentication)

Certificate generation is built into the cBridge and Python bridge executables using Ed25519 keys:
cBridge --generateCA ca.pem --cn "My CA"
cBridge --generateCert server.pem --ca ca.pem --cn myhost
cBridge --generateCert client.pem --ca ca.pem --cn expecco

Generated PEM files include the full certificate chain, so the CA is automatically trusted without additional configuration.

For mutual TLS (mTLS), start the remote bridge with the <code>--clientAuth</code> flag:
cBridge --port 8855 --ssl --cert server.pem --clientAuth

See [[Cbridge_setup#SSL/TLS_Connection_to_a_Remote_CBridge|CBridge Setup: SSL/TLS Connection]] for detailed instructions.

== File Transfer and Remote Directory Operations ==
All bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk) support transferring files between expecco and the remote bridge:
* <code>putFile: localPath to: remotePath</code> — upload a file to the bridge
* <code>getFile: remotePath to: localPath</code> — download a file from the bridge
* <code>makeDirectory: remotePath</code> — create a directory (including parent directories) on the bridge

These operations use the existing bridge connection and work over SSL if enabled. They are useful for deploying test data, collecting results, or transferring compiled binaries.

== [OS X Only] CrashReporter Dialog Boxes ==
You may get annoying dialog boxes telling about "''Unexpected Termination''" whenever a bridge is hard terminated via the "''Terminate''" button in the debugger.

This is a "''feature''" of the OS X system, not controlled by expecco.

You can disable this by executing the following command in a console terminal:
defaults write com.apple.CrashReporter DialogType none

Back to [[FAQ/en | FAQ]]

Cbridge setup

2026-05-27T07:01:30Z

Sv: document SSL/TLS, certificate generation, mTLS, file transfer, makeDirectory

= CBridge Setup =

In order to compile and execute C/C++ actions, a C compiler toolchain has to be installed on the machine, where the Bridge executable (Windows: <code>cBridge.exe</code> / Unix: <code>cBridge</code>) runs.
 Typically this is the local machine on which expecco runs, but it may be any other machine in your reachable network.
 The CPU architecture and or operating system may be (and often is) different from the CPU which executes expecco, therefore the C-code is compiled on the target machine (i.e. not cross-compiled).

== C-Compiler Toolchain Installation ==

=== Windows + Borland Compiler (32bit) ===
The compiler is a bit outdated, but still free and useful. However, it only supports 32bit programs. Thus, it cannot be used if you need access to 64bit dlls. (on the other hand, if you need to interact with a 32bit dll to communicate with some hardware device, you'll must use a 32bit cBridge).

We recommend to install the toolchain at its default installation path (typically "<code>C:\borland</code>"). Then, the provided cc-compile script for borland can be used unchanged.

=== Windows + MINGW Compiler (32 or 64bit) ===
The mingw toolchain is based on the gcc compiler. This is recommended and preferred over borland.

=== Windows + Microsoft Visual C / Visual Studio ===
There is no need to install the full Visual Studio IDE. Only the C-compiler, linker and libraries are required.
Thus, you can untoggle all additional optional packages during the installation.

Check for the "<code>cl</code>" command (being in your <code>PATH</code>) or find and remember the path to it (typically somewhere under "<code>c:\Program Files\Microsoft\...</code>").

=== Unix / Linux ===
Install whatever packages are required; check if the "<code>cc</code>" command is found along your <code>PATH</code> (before starting expecco),
or alternatively, remember the path to the "<code>cc</code>" command.

Regardless of which compiler you use,
please remember the installation path. You will need it later unless the compiler is found along your <code>PATH</code>.

== Quick Check if it Already Works ==
We provide a number of setups for common installations.
In many situations, this will already be correct for your setup.

To check, create a new elementary-bridgedC action, and run it.
(the initial tree which is created with examples also contains a simple C action).

If you get a green OK result, you're already done.
If not, your setup needs to be adjusted.

Read the chapter at the end of this page on step-by-step setup verification.

== The Compile Script ==
For compilation, the cBridge program calls a batch/shell script, which is responsible for compilation of the C-code to a DLL/shared object file.
This script may need to be edited.
We recommend, that you navigate to the folder where the cBridge executable is located, take one of the existing scripts as template, make a copy under a new name, and then edit this copy to suit your needs.

Take one of the existing scripts which uses the same compiler (borland/mingw/visualC).

In the editor, check the <code>PATH</code> setting, and edit it as appropriate, finally save it.

Back in expecco, go to the cBridge settings under the external-script settings,
and change the CC-script setting there ("''Extras''" - "''Settings''" - "''Execution''" - "''External Script Interpreters''" - "''CBridge''").

Shutdown any already running bridge ("''Extras''" - "''Debugging''" - "''Shutdown all Bridge Connections''")

Go back to the C-action and repeat the quick check.

Eventually, you should see a green OK result.

== Special Additional Libraries ==

It may be required that your C-code needs additional shared libraries to be linked against your code.
The easiest is to add those libraries and corresponding command line options to the CC-script's compiler call command.
The details depend on the compiler used.
You may need to do a "<code>cc --help</code>", "<code>cl/help</code>" or similar, to figure out which command line options are required.

= Remote C-Bridges =
You can run any number of cBridges on any machine within your network (and also multiple cBridges on your local or a remote machine), and execute C-actions there. For this, the following setup steps are to be performed:

* copy the cbridge executable and its support files to a new folder on the target machine; the files are found below the expecco installation folder (eg. "<code>c:\Program Files\exept\expecco</code>") in "<code>packages\bridgeFramework\cBridge\cLibrary</code>".
:The easiest way is to copy the whole folder. Make sure that the copied folder matches the target machine's architecture (i.e. if the target is a Linux machine, you must obviously copy the files from a Linux installation, and same so for Windows machines).

* on the remote machine, make sure that the cBridge is running; either by executing a remote command from inside your expecco suite, or by adding the cBridge startup to a cron tab (Unix/Linux) or the service list or autoexec.bat (Windows).
:As a test, start it manually with: "<code>cBridge --port 8856</code>", and connect to it from expecco (change the settings ("''Extras''" - "''Settings''" - "''Execution''" - "''External Script Interpreters''" - "''CBridge''") to connect to an already running cBridge at that port).

* if in doubt, start the cBridge with a "<code>--help</code>" option.

=== CBridge Command Line Arguments ===

* --help Prints a list of the supported comamnd line arguments
* --localOnly only accept connections from the local machine
* --host ''hostname'' connect to that host instead of waiting for incoming connections
* --port the TCP port on which the bridge is waiting for incoming requests or connecting to (with --host argument)
* -- keepAlive after the first connection, keep on waiting for more incoming connections. Without this, the bridge will only handle a single session and exit after that.
* --log log actions on stderr
* --log2 even more detailed log
* --ccScript ''scriptFile'' Use the given script file (a shell or batch script) to compile
* --includes ''files'' Additional include folders passed to the compile script
* --dlls ''files'' Additional dlls (shared libraries) to be linked against actions
* --testCompile For a standalone selftest if compilation works. Compiles a dummy almost empty source file

More arguments may be recognized, depending on the cBridge version. Use "--help" to see more.

=== SSL/TLS Connection to a Remote CBridge ===

The cBridge supports encrypted TLS connections with optional mutual certificate authentication (mTLS).

==== Generating Certificates ====
The cBridge can generate Ed25519 CA and server/client certificates directly:

cBridge --generateCA ~/.ssl/ca.pem --cn "My CA" --days 3650
cBridge --generateCert ~/.ssl/server.pem --ca ~/.ssl/ca.pem --cn myhost
cBridge --generateCert ~/.ssl/client.pem --ca ~/.ssl/ca.pem --cn expecco

Each generated PEM file contains the certificate, private key, and the CA certificate chain. The <code>--cn</code> option sets the common name (default: localhost), <code>--days</code> sets the validity period (default: 3650).

The same certificate generation is also available via the Python bridge script (<code>--generateCA</code> / <code>--generateCert</code>).

==== Starting the CBridge with SSL ====

cBridge --port 8855 --ssl --cert ~/.ssl/server.pem

A combined PEM file (certificate + key in one file) is used by default. Separate files are also supported:

cBridge --port 8855 --ssl --cert server.crt --key server.key

==== Mutual TLS (Client Certificate Authentication) ====

To require clients to present a certificate signed by the same CA:

cBridge --port 8855 --ssl --cert ~/.ssl/server.pem --ca ~/.ssl/ca.pem --clientAuth

Clients must then be configured with a client certificate (see the expecco CBridge settings dialog).

==== Expecco Settings for SSL ====

In expecco, configure the CBridge connection under "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''CBridge''":
* '''Use SSL''': enable encrypted connection
* '''Certificate File''': the server certificate PEM (for the bridge process)
* '''Client Certificate File''': the client certificate PEM (presented to the server for mTLS)

When the client certificate PEM includes the CA certificate in the chain, the CA is automatically trusted for server certificate verification.

==== File Transfer and Directory Operations ====
All bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk) support file transfer to and from the remote bridge:
* <code>putFile: localPath to: remotePath</code> — upload a file
* <code>getFile: remotePath to: localPath</code> — download a file
* <code>makeDirectory: remotePath</code> — create a directory (including parent directories)

These operations work over the bridge's existing connection (including SSL if enabled).

= Step-by-Step Problem Finding/Fixing =

=== Ensure that the cBridge executable is present and can be executed ===
* goto the expecco installation folder (typically somewhere under "<code>c:\Program Files\exept\expecco\</code>"), and look for files named "<code>cBridge.exe</code>" or "<code>cBridge32.exe</code>" or "<code>cBridge</code>" (under Unix/Linux). It is typically found in a sub folder named "<code>packages/expecco/bridgeFramework/cBridge</code>".
* open a shell- or cmd window (and navigate there).
* type "<code>cBridge --help</code>" (with powershell: "<code>.\cBridge --help</code>")
:: if that fails (does not output some useful help text), make sure that it can be executed. Maybe your security policy is too strict ot the installation is incomplete.
* start the bridge with "<code>cBridge --log</code>"
:: it should output some messages, the last being "<code>... listening on port xxxx</code>"
* if the cBridge is to run on a machine different from the one expecco is running on, make sure that the firewall allows for connections between the two machines (at the desired port nr)
* if required, use another port (i.e. run it with "<code>cBridge --log --port <Nr></code>")
:: now we have a cBridge running, ready to accept connections from expecco at the given port nr.
* keep the shell/cmd window open; we will need it later (and also to see any diagnostic output)

=== Ensure that the cBridge is reachable from expecco ===
for this, we first try to connect to that already running bridge (instead of letting expecco start it itself)
* in expecco, open the settings and navigate to the cBridge settings:
:: "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''CBridge''"
* check the "''Connect to already Running Bridge''" box.
:: enter CBridge Host and Port as "<code>localhost</code>" and the above port number (default is 8855)
* close the settings dialog (without saving the settings for now, when asked)
* open a new project. The default project will contain a sample "Hello World" C-action, which can be used for the smoke test.
* in the expecco tree, find the "<code>Simple Elementary Action (C)</code>" (under the "Activities" group).
* run it
:: if the error states that no connection could be setup, check your security policy, firewall etc. and repeat
:: if the error states that the compilation failed, the bridge connection works, but the compilation script setup is wrong. Proceed.

=== Ensure that the compilation works ===
the cBridge needs a C-compiler for its operation; to verify,
* stop the manually started C-bridge (in the shell/cmd window) by pressing CTRL-C there
* depending on the C-compiler you intend to use, one of the "compile_xxx.bat" or "compile_xxx.sh" script files will be used. The task to be performed by these scripts is to compile a given C-file.
* check which compiler you installed and intent to use (MSVC, Mingw, gcc, clang or bcc), and look for a corresponding script file.
* check if the compiler is correctly installed (especially MSVC and MINGW sometimes make trouble here).
:: one particular problem with MSVC is when deinstalling and reinstalling another version. There seem to be leftover files and/or registry entries which may break the installation (this happend to one of our customers, and also to us when upgrading)
* Enter the compile-command ("cl", "cc", "gcc" or "clang") on a command line (cmd or shell)
:: check that you get an answer
:: try to compile a one-liner (eg. "<code>main() { printf("hello\n"); }</code>" and run it to see if it links correctly. Run it!
* check if the bridge's cc script file works by running "<code>cBridge --log --ccScript <scriptfilename> --testCompile</code>"
:: if required, make a copy of one of the script files (the one you think is best to start with) and fix any path inside. If required, add echo statements to show what is going on. Keep the original script and create a new one.
:: under Windows: in the script, the PATH to the compiler is typically searched and set; for example by calling the vcvarsall.bat script which is provided by microsoft. If required, change the line which calls this (you can also add this batch-call to your autoexec.bat and remove the line from the script). In any case: at the end, the "cl" command should be found along your path.
* the --testCompile will generate a piece of code which outputs "here is foo"; i.e. on your system (we use mingw), the command is "<code>cBridge --log --ccScript compile_windows_mingw.bat" --testCompile</code>", and the output is "here is foo" - "void pointer size: 8", followed by the usual "listening on port" message.

=== Change the Settings in expecco ===
* open the cBridge settings again
* uncheck the "''Connect to already running bridge''" box
* enter the name of the compile script into the "CC-script" field (possibly the name of the new script)
* shutdown any already running bridge
* try executing the expecco-C action again
* if you get a green outcome, save your expecco settings.

Remote Access/en

2026-05-26T18:52:47Z

Sv: Fold the Automatic-Refresh bullets onto single physical lines

{{Languages|Remote Access/en|label=English}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation in <code>exept:libcrypt/ssh</code>; no external dependency on OpenSSL or libssh. Use this for anything that touches credentials or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine. Used for local-tool integration and for the local end of a remote workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No encryption, passwords on the wire in clear. Use only when the target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code> subclass that lets the rest of ST/X treat a remote SFTP path the same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>.

The '''Refresh''' button in the toolbar (the round-arrow icon
between ''Forward'' and ''DirectoryUp'') re-reads both the
directory tree and the contents pane on demand. Works uniformly
for local and SFTP paths; for SFTP it also flushes the per-file
STAT cache, so changes made directly on the remote side become
visible immediately rather than waiting for the 5-second cache TTL
to expire.

The small arrow next to the Refresh icon opens a dropdown with a
single checkbox, '''Automatic Refresh''', controlling the
background polling task that walks every expanded tree item to
detect external changes. The default depends on the current root:

* Local filesystem → '''on''' (10-second cycle, matches the long-standing behaviour).
* SFTP → '''off'''. Each cycle costs one STAT round-trip per child, which is fine for a handful of local directories but painful over the network. Click Refresh manually when you need to pick up remote changes.

When you navigate between local and SFTP roots the toggle flips
automatically — but only if you haven't overridden it for
the previous root. An explicit user choice is preserved across
navigations.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a remote host.
* '''SFTP Connect...''' — points this browser tab at a remote filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of the filesystem holding the currently displayed directory. Works uniformly for local paths and SFTP paths; for SFTP it requires the server to advertise the <code>statvfs@openssh.com</code> extension (every modern OpenSSH does). Sizes are reported in IEC binary units (MiB, GiB, TiB) — the largest unit yielding a value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB'' rather than ''10240 GiB''.

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code> (or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only; gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file unencrypted (agent-only mode ignores the passphrase, since the OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to '''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally; a ST/X on the Windows side does not. Bridging needs a helper like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's walkback plus each waiter's, formatted as plain text. Use when a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed (e.g. legacy PEM, encrypted-without-agent) — the file is skipped, others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime), no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On servers that advertise <code>posix-rename@openssh.com</code> (every modern OpenSSH does), overwrite is atomic; on the rare server that does not, the receiver is emulated as delete-then-rename and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always returns <code>#isDirectory</code> (the accurate answer would cost three round-trips per directory icon, which made the original tree expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link. Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe, EOF, MNU on nil socket) evicts the dead pool entry, opens a fresh client, retries the request '''once'''. Application-level SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP + one SFTP channel per host means N concurrent requests serialise. Pipelining over multiple SshClients in the pool (preferred), or a transport-level reader process demultiplexing to per-channel inboxes, would let the tree pane keep listing while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (first batch only) + CLOSE — three RTTs per probe; needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style canonicalisation. (Atomic-overwrite rename is already handled via the OpenSSH <code>posix-rename@openssh.com</code> extension; see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]

Remote Access

2026-05-26T18:52:45Z

Sv: Fold the Automatic-Refresh bullets onto single physical lines

{{Languages|Remote Access|label=Deutsch}}

'''Fernzugriff''' bezeichnet die Möglichkeit, einen entfernten
Rechner oder ein entferntes Netzwerk aus diesem expecco-Image heraus
zu bedienen — Shells zu öffnen, Befehle abzusetzen, Dateien zu
verschieben oder ein Testgerät anzusteuern. Drei Protokoll-Familien
sind unterstützt, in absteigender Empfehlungsreihenfolge:

* '''SSH und SFTP''' (empfohlen) — verschlüsselte Shell und sichere Dateiübertragung über einen SSH-2-Tunnel. Reine Smalltalk-Implementierung in <code>exept:libcrypt/ssh</code>; keine externe Abhängigkeit von OpenSSL oder libssh. Für alles mit Zugangsdaten oder sensiblen Nutzdaten.
* '''Lokale Kommando-Shell''' — fork + exec auf der lokalen Maschine. Für die Anbindung lokaler Werkzeuge und für die lokale Seite eines hybriden Workflows.
* '''Telnet''' (veraltet) — Klartext-Terminalsitzung. Keine Verschlüsselung, Passwörter im Klartext auf der Leitung. Nur einsetzen, wenn die Gegenstelle keine Alternative bietet.

= SSH und SFTP =

Der SSH-Stack deckt das vollständige SSH-2-Protokoll ab
(RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) inklusive der
chacha20-poly1305-Transportchiffrierung von OpenSSH sowie das
SFTP-v3-Subsystem (draft-ietf-secsh-filexfer-02). Zwei Schichten:

* '''<code>SSH::Client</code>''' — programmatischer SSH-Zugriff (entferntes <code>exec</code>, TTY-Shell, Agent-Weiterleitung, ProxyJump-Bastion).
* '''<code>SSH::SftpFilename</code>''' — eine
<code>Filename</code>-Unterklasse, die es dem restlichen ST/X
erlaubt, einen entfernten SFTP-Pfad zu behandeln wie eine lokale
Datei.

Die folgenden Abschnitte sind nutzeraufgaben-zuerst aufgebaut:
zuerst das, was der Anwender sieht und tut, darunter die
expecco-Bibliotheks-Anbindung, ganz unten Implementierungsdetails
für Interessierte.

== Aus dem FileBrowserV2 ==

Im Adress-Dropdown eine <code>sftp://</code>-URL einfügen. Der
Browser-Tab füllt sich wie bei einem lokalen Pfad.
Baum-Ausklappen, Spaltensortierung (Name / Größe / mtime),
Vorschau und Doppelklick zum Öffnen im Editor verhalten sich
normal. Der erste Klick auf einen Host dauert ~200–500 ms
(TCP + KEX + Auth); folgende Klicks nutzen die gepoolte
Verbindung weiter.

URL-Syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

Fehlt <code>user</code>, wird der lokale Login-Name verwendet, Port
ist standardmäßig 22, Pfad standardmäßig <code>/</code>.

Die Schaltfläche '''Refresh''' in der Symbolleiste
(Pfeil-Kreis-Symbol zwischen ''Forward'' und ''DirectoryUp'') liest
Baum und Inhalts-Panel auf Anforderung neu ein. Funktioniert
einheitlich für lokale und SFTP-Pfade; bei SFTP wird zusätzlich der
per-Datei-STAT-Cache geleert, sodass Änderungen, die direkt auf
der Gegenseite gemacht wurden, sofort sichtbar werden — ohne auf
den Ablauf der 5-Sekunden-Cache-TTL zu warten.

Der kleine Pfeil neben dem Refresh-Symbol öffnet ein Aufklappmenü
mit einem einzelnen Kontrollkästchen, '''Automatic Refresh''', das
den Hintergrund-Task an- bzw. abschaltet, der alle expandierten
Baumeinträge auf externe Änderungen prüft. Die Vorgabe richtet
sich nach der aktuellen Wurzel:

* Lokales Dateisystem → '''an''' (10-Sekunden-Zyklus, entspricht dem bisherigen Verhalten).
* SFTP → '''aus'''. Jeder Zyklus kostet einen STAT-Roundtrip pro Kind — für eine Handvoll lokaler Verzeichnisse harmlos, über das Netz schmerzhaft. Bei Bedarf manuell auf Refresh klicken, um Änderungen zu sehen.

Beim Wechsel zwischen lokalen und SFTP-Wurzeln wird der Schalter
automatisch umgelegt — aber nur, sofern man ihn für die
vorherige Wurzel nicht selbst verstellt hat. Eine explizite
Benutzerwahl bleibt über Navigationen hinweg erhalten.

Das Menü '''Tools''' im FileBrowserV2 bietet vier Aktionen — die
drei SSH-spezifischen sind nur bei geladener SSH-Bibliothek
sichtbar:

* '''Generate SSH Key Pair...''' — öffnet den Schlüsselerzeugungs-Dialog, siehe [[#Einen SSH-Schlüssel erzeugen]] unten.
* '''SSH Connect...''' — öffnet ein interaktives VT100-Terminal zu einem entfernten Host.
* '''SFTP Connect...''' — navigiert diesen Browser-Tab über SFTP auf ein entferntes Dateisystem.
* '''Filesystem Info...''' — zeigt Größe, freien Platz und Belegung des Dateisystems, das das aktuell angezeigte Verzeichnis enthält. Funktioniert einheitlich für lokale und SFTP-Pfade; bei SFTP setzt der Aufruf voraus, daß der Server die Erweiterung
<code>statvfs@openssh.com</code> ankündigt (jedes moderne OpenSSH
tut das). Größen werden in IEC-Binäreinheiten ausgegeben (MiB,
GiB, TiB) — gewählt wird die größte Einheit, die einen Wert ≥ 1
liefert, damit ein TB-großes Volume als ''X TiB'' statt
''10240 GiB'' erscheint.

== Aus expecco-Aktionen ==

Das Expecco-RemoteAccess-Plugin
([[Expecco::RemoteAccessImportPlugin]]) stellt folgende Testaktionen
in der expecco-Aktionspalette bereit:

* '''CmdShell - Open SSH Remote Connection''' — öffnet eine SSH-Sitzung über das plattformeigene <code>ssh</code>-Binary (PuTTYs <code>plink</code> unter Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — dasselbe, jedoch mit expliziter Public-Key-Authentifizierung.

Voraussetzung: ein eingerichtetes Schlüsselpaar (privater
Schlüssel auf dieser Maschine, öffentlicher Teil in der
<code>~/.ssh/authorized_keys</code> des Zielhosts). Schlüssel
erzeugen entweder über den Dialog unten oder über
<code>ssh-keygen</code>.

Das Plugin fügt zusätzlich eine Settings-Seite hinzu:
'''Extras → Settings → Plugins → Remote Access — SSH Keys''' mit
einer einzelnen Schaltfläche '''Generate SSH Key Pair...''', die
denselben Dialog öffnet.

== Einen SSH-Schlüssel erzeugen ==

=== Der Dialog (FileBrowserV2 / Settings-Seite) ===

Der Dialog fragt alle Parameter in einem Formular ab:

* '''Comment''' — wird in den erzeugten Schlüssel eingebettet (Voreinstellung <code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — schreibt
<code>~/.ssh/id_ed25519_stx</code> (oder wohin man will) samt
zugehöriger <code>.pub</code>-Datei daneben.
** ''Save to disk AND load into ssh-agent'' — schreibt die Datei UND übergibt den Schlüssel dem laufenden ssh-agent.
** ''Load into ssh-agent only'' — der Schlüssel lebt nur im Speicher des Agents; nach Agent-Neustart ist er verloren.
* '''Private key file''' — vollständiger Pfad; ausgegraut im Agent-only-Modus.
* '''Passphrase / Confirm''' — leer lässt die On-Disk-Datei unverschlüsselt (Agent-only-Modus ignoriert die Passphrase, da das OpenSSH-Agent-Wire-Protokoll nur den entschlüsselten Schlüssel transportiert).

Bei '''Generate''' wird die Public-Key-Zeile (dieselbe
<code>ssh-ed25519 AAAA... comment</code>-Zeichenfolge, die
ssh-keygen ausgibt) in die System-Zwischenablage kopiert — zum
direkten Einfügen in die <code>~/.ssh/authorized_keys</code> des
Zielhosts.

=== Aus einem Workspace ===

Für Headless-Deployments, Sandbox-Builds oder Skripte stellt
<code>SSH::Client</code> einen reinen Smalltalk-Schlüsselgenerator
bereit, dessen Ausgabe bit-kompatibel zu
<code>ssh-keygen -t ed25519</code> ist:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Passphrase-verschlüsselt auf Platte speichern"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ UND in den laufenden Agent laden"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Public-Key-Zeile zum Einfügen in authorized_keys ausgeben"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Die so erzeugten Schlüssel sind mit den OpenSSH-Werkzeugen voll
interoperabel (<code>ssh-keygen -y -f ...</code> rekonstruiert den
öffentlichen Schlüssel, <code>ssh-keygen -p -f ...</code> ändert
die Passphrase usw.).

=== Mit den Shell-Werkzeugen ===

Der klassische Weg funktioniert weiterhin:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== ssh-agent vorbereiten ==

Der Weg über den Agent ist dem direkten Lesen von Schlüsseldateien
deutlich vorzuziehen: er hält verschlüsselte private Schlüssel
einmal pro Sitzung entsperrt und kann Identitäten verwalten
(hardware-tokengestützte Schlüssel, KeePassXC-Einträge), die ST/X
nie direkt sehen soll.

ST/X erkennt den Agent-Pfad automatisch, sobald
<code>$SSH_AUTH_SOCK</code> '''zum Zeitpunkt des Starts von stx'''
in der Prozessumgebung gesetzt ist. Eine spätere Zuweisung aus
einem Workspace nützt nichts.

=== Linux / macOS ===

Die meisten Desktop-Distributionen starten einen Agent automatisch
beim Login (gnome-keyring unter GNOME, ssh-agent.service unter
systemd, KWallet unter KDE). Prüfen im Terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh oder ähnlich
ssh-add -l # listet geladene Identitäten
ssh-add ~/.ssh/id_ed25519 # eigene laden, falls nicht da
</pre>

Läuft gar kein Agent, dieses Snippet in die Shell-rc-Datei
aufnehmen:

<pre>
# ~/.bashrc oder ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X muss aus einer Shell gestartet werden, die diese rc bereits
gelesen hat — ein Desktop-Launcher aus dem Dateimanager erbt die
Variable nicht. Empfehlung: ein kleines Wrapper-Skript unter
<code>~/.local/bin/</code>, das die rc sourcet und dann stx
startet.

Die Settings-Seite ('''Extras → Settings → Plugins → Remote
Access — SSH Keys''') zeigt an, ob das laufende Image einen
Agent sieht.

==== Permanente Einrichtung via systemd ====

Für einen wirklich sitzungsübergreifenden Agent (überlebt Desktop-
Abmeldung, kommt beim nächsten Login wieder hoch) die bei den
meisten Distros mit dem Paket <code>openssh-clients</code>
ausgelieferte Per-User-systemd-Unit aktivieren:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Anschließend <code>SSH_AUTH_SOCK</code> in der Shell-rc auf den
User-Service-Socket zeigen lassen (ersetzt das
<code>eval $(ssh-agent -s)</code>-Snippet oben):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Schlüssel automatisch beim ersten Einsatz laden ====

Um den manuellen <code>ssh-add</code>-Schritt zu sparen, kann
OpenSSH Schlüssel beim ersten Bedarf selbst in den Agent laden.
In <code>~/.ssh/config</code> eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

Die erste SSH-Verbindung fragt dann einmal nach der Passphrase und
übergibt den entsperrten Schlüssel an den Agent; weitere
Verbindungen nutzen die gespeicherte Identität ohne Prompt.

=== Windows ===

Windows 10+ bringt das native OpenSSH inklusive Agent-Dienst mit.
Einmalige Einrichtung:

# '''Dienste''' (<code>services.msc</code>) als Administrator öffnen.
# '''OpenSSH Authentication Agent''' suchen, Starttyp auf '''Automatisch''' setzen, '''Starten''' anklicken.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Prüfen: <code>ssh-add -l</code>.

Der Windows-OpenSSH-Agent lauscht auf einer Named Pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), nicht auf einem
Unix-Socket. ST/X unterstützt beide Transporte, jedoch setzt das
Windows-ssh-add <code>SSH_AUTH_SOCK</code> '''nicht''' selbst.
Daher einmalig systemweit setzen:

# {{Key|Win}} drücken → "Umgebungsvariablen" → „Systemumgebungs- variablen bearbeiten".
# '''Umgebungsvariablen''' → unter '''Benutzervariablen''', '''Neu''' klicken.
# Name: <code>SSH_AUTH_SOCK</code>
# Wert: <code>\\.\pipe\openssh-ssh-agent</code>
# Ab- und wieder anmelden (oder stx neu starten), damit die neue Umgebung übernommen wird.

==== PowerShell-Schnelleinrichtung ====

Derselbe Aufbau aus einer '''Administrator-PowerShell''' heraus,
z.B. für Skripte oder unbeaufsichtigte Bereitstellung:

<pre>
# Agent jetzt und bei jedem Neustart starten (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# SSH_AUTH_SOCK dauerhaft für den Benutzer setzen (übersteht Reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Schlüssel laden (fragt nach Passphrase, falls die Datei verschlüsselt ist).
ssh-add $HOME\.ssh\id_ed25519
</pre>

Für einen einmaligen Agent-Start ohne dauerhafte Aktivierung
(z.B. Einzelsitzung) die <code>Set-Service</code>-Zeile weglassen
und nur <code>Start-Service ssh-agent</code> ausführen. Die
env-var-Zeile lässt sich ebenfalls weglassen, wenn
<code>SSH_AUTH_SOCK</code> nur in der aktuellen Shell gebraucht
wird — dann statt der <code>[Environment]</code>-Variante
<code>$env:SSH_AUTH_SOCK = '...'</code> verwenden.

Auf stark abgespeckten Windows-Installationen ist der
ssh-agent-Dienst eventuell nicht vorhanden. Einmalig nachrüsten
über '''Einstellungen → Apps → Optionale Features → OpenSSH-
Client'''.

Alternative Agenten:

* '''PuTTY pageant''' — eigenes Protokoll; von ST/X's
<code>SSH::Agent</code> '''nicht''' unterstützt. Schlüssel zu
OpenSSH migrieren.
* '''Git für Windows ssh-agent''' — funktioniert;
<code>SSH_AUTH_SOCK</code> auf den dort veröffentlichten Socket
zeigen lassen.
* '''WSL 2''' — ein ST/X innerhalb der WSL sieht den WSL-eigenen Agent normal; ein ST/X auf der Windows-Seite nicht. Eine Brücke per <code>npiperelay</code> + <code>socat</code> ist möglich.

Prüfung über die Settings-Seite
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
die Anzeige dort meldet, ob das laufende Image den Agent sieht.

==== Schlüssel automatisch beim ersten Einsatz laden ====

Windows-OpenSSH speichert agent-geladene Schlüssel '''nicht'''
über Agent-Neustarts hinweg. Um nicht nach jedem Reboot manuell
<code>ssh-add</code> aufrufen zu müssen, dieselbe Lazy-Load-
Konfiguration in <code>%USERPROFILE%\.ssh\config</code>
eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH lädt den Schlüssel dann beim ersten Einsatz in den Agent
(fragt einmal nach der Passphrase) und nutzt ihn für die übrige
Sitzung weiter.

== Konfiguration ==

Alle Stellschrauben sind klassenseitig auf
<code>SSH::SftpFilename</code> erreichbar:

{| class="wikitable"
! Accessor !! Voreinstellung !! Steuert
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 Min) || Wie lange
eine gepoolte Verbindung im Leerlauf liegen darf, bevor sie beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet wird.
Liegt knapp unter dem typischen
<code>ClientAliveInterval × ClientAliveCountMax</code> des sshd,
damit wir uns recyceln, bevor der Server uns mit TCP-RESET
trennt. <code>nil</code> setzt auf Voreinstellung zurück.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Maximales Alter (s)
eines gecachten STAT, bevor <code>#ensureAttrs</code> neu am
Server fragt. Eltern-listDir stempelt ohnehin frische Attribute
auf alle Kinder, daher zahlt das Navigieren im offenen
Verzeichnis das TTL nicht. <code>0</code> schaltet den Cache
ab.
|-
| <code>#closeAllConnections</code> || (Aktion) || Reißt jede
gepoolte Verbindung ab. Nützlich nach einem bekannt schlechten
Netzereignis, vor einem bewussten Identitätswechsel oder zum
sauberen Image-Shutdown.
|}

== Diagnose ==

=== SemaphoreMonitor ===

<code>SemaphoreMonitor</code> über das Untermenü „Status" des
Launchers öffnen. Der pro-Host-SFTP-Mutex erscheint als
<code>SFTP/<user@host:port></code>, der pool-weite Mutex als
<code>SFTP/pool</code>. Per Rechtsklick:

* '''Copy Waiters Stack to Clipboard''' — schreibt den Walkback des letzten Eigners samt aller Waiter als Text in die Zwischenablage. Unverzichtbar, wenn ein Prozess in
<code>readWait</code> innerhalb von
<code>withSftpClientDo:</code> klemmt.
* '''Copy List to Clipboard''' — die ganze Tabelle, ideal für eine E-Mail-Diagnose.
* '''Detect Deadlocks''' — DFS über den Wait-for-Graph, meldet Zyklen.

=== Logger ===

Interessante Ereignisse werden über <code>Logger</code> geloggt:

* <code>warning:</code> bei automatischem Reconnect nach toter Verbindung.
* <code>warning:</code> bei Idle-Verdrängung eines Pool-Eintrags.
* <code>warning:</code> wenn eine SSH-Schlüsseldatei nicht geparst werden konnte — die Datei wird übersprungen.

== Einschränkungen ==

* '''Nur SFTP v3.''' Kein SETSTAT (kein entferntes chmod / chown / utime), kein SSH_FXP_READLINK exponiert (<code>#isSymbolicLink</code> liefert immer <code>false</code>,
<code>#linkInfo</code> die normale stat-Info). Einige
SFTPv5+-Annehmlichkeiten werden dennoch über OpenSSH-spezifische
SSH_FXP_EXTENDED-Aufrufe nutzbar — siehe
[[#OpenSSH-SFTP-Erweiterungen]] weiter unten.
* '''Serialisierung pro Host.''' Zwei gleichzeitige Operationen am selben Host stehen am Host-Mutex an. Siehe [[#Ausblick]].
* '''<code>#renameTo:</code>-Fallback hat ein TOCTOU-Fenster.''' Bei Servern, die <code>posix-rename@openssh.com</code> ankündigen (jedes moderne OpenSSH tut das), ist das Überschreiben atomar. Beim seltenen Server, der das nicht tut, wird auf Delete-dann-Rename ausgewichen und ein anderer Prozess kann sich dazwischenschieben.
* '''<code>#isNonEmptyDirectory</code> ist eine Heuristik.''' Liefert immer <code>#isDirectory</code> (die genaue Antwort würde drei Roundtrips pro Verzeichnis-Symbol kosten, was das ursprüngliche Baum-Ausklappen unerträglich gebremst hatte).

== Implementierungsdetails ==

Für Leser, die die Architektur verstehen wollen. Fünf Klassen,
von oben nach unten:

{| class="wikitable"
! Klasse !! Aufgabe
|-
| <code>SSH::SftpFilename</code> || Filename-Unterklasse, die
öffentliche API. Bildet <code>sftp://...</code>-URLs auf
entfernte Dateien ab und stellt <code>directoryContents</code>,
<code>readingFileDo:</code>, <code>renameTo:</code> usw. bereit.
|-
| <code>SSH::SftpClient</code> || SFTP-v3-Protokoll
(Request/Response-Codec, listDir, stat, open, read, write, mkdir).
Wird von SftpFilename angesteuert.
|-
| <code>SSH::Channel</code> || SSH-Kanal-Multiplexer (CHANNEL_OPEN,
DATA, EOF, CLOSE, WINDOW_ADJUST). Eine logische Sitzung pro
Channel-Instanz.
|-
| <code>SSH::Client</code> || High-Level-SSH-Client: öffnet den
Transport, führt KEX, Hostschlüssel-Prüfung und userauth durch und
verteilt anschließend Kanäle.
|-
| <code>SSH::Transport</code> || Drahtschicht. Banner- und
KEXINIT-Austausch, ChaCha20-Poly1305-Paket-Framing, sendSeq /
recvSeq, Heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH-SFTP-Erweiterungen ===

SFTP v3 (Entwurf draft-ietf-secsh-filexfer-02) ist bewusst
minimal gehalten. OpenSSH bringt einen offenen
Erweiterungsmechanismus mit: der Server listet im
<code>SSH_FXP_VERSION</code>-Reply die Erweiterungsnamen auf, die
er versteht, und der Client ruft sie über
<code>SSH_FXP_EXTENDED(200)</code>-Pakete mit dem
Erweiterungsnamen als erstem String auf. Jede Erweiterung wird
über <code>SSH::SftpClient>>supportsExtension:</code>
feature-detektiert; Aufrufer fallen zurück, wenn der Server sie
nicht ankündigt.

Der Stack nutzt heute vier OpenSSH-Erweiterungen:

* <code>posix-rename@openssh.com</code> — atomares rename-mit-Überschreiben. Wird automatisch von
<code>SftpFilename>>renameTo:</code> aufgegriffen; die
Delete-dann-Rename-Fallback-Variante kommt nur bei Servern zum
Einsatz, die die Erweiterung nicht haben.
* <code>hardlink@openssh.com</code> — Erzeugt einen POSIX-Hardlink. Verfügbar als <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX-
<code>statvfs(3)</code>-typische Dateisystem-Statistik.
Verfügbar als <code>SftpFilename>>fileSystemInfo</code>;
das Ergebnis ist form-kompatibel zu
<code>OperatingSystem getDiskInfoOf:</code>, sodass Aufrufer
lokale und entfernte Pfade einheitlich behandeln können.
Treibt den Menü-Eintrag '''Tools → Filesystem Info...''' an,
der am Anfang dieser Seite beschrieben ist.
* <code>fsync@openssh.com</code> — schreibt den serverseitigen Schreibpuffer eines geöffneten Handles auf Platte. Liegt als
<code>SftpClient>>fsyncHandle:</code> bereit; noch nicht
in eine "Durable-Write"-API auf Filename-Ebene eingebunden.

Die verbleibenden OpenSSH-Erweiterungen
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
werden in der angekündigten Liste erkannt, aber nicht auf
Filename-Ebene gekapselt — es gibt dafür noch keinen
Filename-seitigen Aufrufer.

=== Verbindungs-Pooling ===

Alle <code>SftpFilename</code>-Instanzen, die auf dasselbe Tripel
<code>user@host:port</code> zeigen, teilen sich einen
<code>SSH::Client</code> samt einem <code>SSH::SftpClient</code>.
Der Pool ist klassenseitig und wird von einem einzigen
<code>ConnectionPoolMutex</code> bewacht:

* '''Lazy-Aufbau''' — TCP + KEX + userauth + SFTP-INIT laufen erst beim ersten SFTP-Aufruf, nicht in <code>forUrl:</code>.
* '''Serialisierung pro Host''' — SFTP-Anfragen an einen bestimmten Host werden durch einen <code>RecursionLock</code> mit dem Namen <code>SFTP/<user@host:port></code> serialisiert (sichtbar im SemaphoreMonitor).
* '''Idle-Verdrängung''' — ein Pool-Eintrag, der länger als
<code>idleEvictionSeconds</code> ungenutzt liegt, wird beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet.
* '''Automatischer Reconnect''' — ein Fehler auf Transportebene (Broken Pipe, EOF, MNU auf nil-Socket) verdrängt den Pool-Eintrag, öffnet einen frischen Client und wiederholt die Anfrage '''einmal'''. Anwendungsfehler aus SFTP-STATUS-Antworten werden sofort durchgereicht.

== Ausblick ==

Geplant, aber noch nicht umgesetzt:

* '''Multi-Channel-Parallelität pro Host''' — aktuell bedeutet eine TCP- plus eine SFTP-Verbindung pro Host, dass N gleichzeitige Anfragen serialisieren. Pipelining über mehrere SshClients im Pool (bevorzugt) oder ein transport-seitiger Reader-Prozess, der eingehende Pakete in Pro-Kanal-Postfächer demultiplext, würde es dem Baum-Panel erlauben, weiter aufzulisten, während das Inhalts-Panel eine große Datei liest.
* '''Genaues <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (nur erstes Batch) + CLOSE — drei Roundtrips pro Sondierung; lohnt erst, wenn der SftpClient Anfragen pipelinen kann.
* '''SFTP-v5/v6-Aushandlung''' für erweiterte Attribute und FTP-artige Kanonisierung. (Atomares Überschreibungs-rename ist bereits über die OpenSSH-Erweiterung
<code>posix-rename@openssh.com</code> abgedeckt; siehe
[[#OpenSSH-SFTP-Erweiterungen]].)

= Kommando-Shell =

Lokale Kommando-Shell auf dieser expecco-Maschine. Typische
Anwendungen: lokale Kommandozeile, lokales Hilfsprogramm,
Brücke zwischen entferntem Workflow und lokalem Tool.

Das RemoteAccess-Plugin stellt bereit:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

Keine Zugangsdaten, kein Netzwerk — läuft als der Benutzer des
expecco-Prozesses. Ausgaben gehen in das expecco-Log.

= Telnet =

[[File:Warning.svg|24px|Warnung]] '''Telnet ist ein veraltetes
Protokoll ohne Verschlüsselung.''' Passwörter werden im Klartext
über die Leitung übertragen; jeder im Netzpfad kann sie lesen.
Telnet NUR einsetzen, wenn die Gegenstelle keine Alternative
bietet (typisch: alte Industriesteuerungen, Laborgeräte,
eingebettete Messgeräte ohne SSH-Stack). Für alles andere
[[#SSH und SFTP]] verwenden.

Das expecco-Plugin stellt bereit:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (interne Demo)

Das Telnet-Protokoll (RFC 854) ist ein bidirektionaler
8-Bit-Byte-Strom über TCP, mit In-Band-Steuersequenzen für
Terminal-Optionen. Verbindungsaufbau zum Ziel-Host:Port; nach
optionalem In-Band-Login können beide Seiten Daten senden.

= Siehe auch =

* [[SSH Client|SSH::Client]] — die SSH-Schicht (exec, TTY, Agent-Weiterleitung, ProxyJump).
* [[FileBrowserV2]] — die Haupt-UI dieses Stacks.
* [[ClaudeCode plugin|Claude Code]] — nutzt denselben SSH-Stack als HTTPS-Transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Netz]]
[[Category:SSH]]

Remote Access/en

2026-05-26T18:50:31Z

Sv: Document the Automatic Refresh dropdown toggle and its root-type default

{{Languages|Remote Access/en|label=English}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation in <code>exept:libcrypt/ssh</code>; no external dependency on OpenSSL or libssh. Use this for anything that touches credentials or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine. Used for local-tool integration and for the local end of a remote workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No encryption, passwords on the wire in clear. Use only when the target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code> subclass that lets the rest of ST/X treat a remote SFTP path the same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>.

The '''Refresh''' button in the toolbar (the round-arrow icon
between ''Forward'' and ''DirectoryUp'') re-reads both the
directory tree and the contents pane on demand. Works uniformly
for local and SFTP paths; for SFTP it also flushes the per-file
STAT cache, so changes made directly on the remote side become
visible immediately rather than waiting for the 5-second cache TTL
to expire.

The small arrow next to the Refresh icon opens a dropdown with a
single checkbox, '''Automatic Refresh''', controlling the
background polling task that walks every expanded tree item to
detect external changes. The default depends on the current root:

* Local filesystem → '''on''' (10-second cycle, matches the
long-standing behaviour).
* SFTP → '''off'''. Each cycle costs one STAT round-trip
per child, which is fine for a handful of local directories but
painful over the network. Click Refresh manually when you need
to pick up remote changes.

When you navigate between local and SFTP roots the toggle flips
automatically — but only if you haven't overridden it for
the previous root. An explicit user choice is preserved across
navigations.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a remote host.
* '''SFTP Connect...''' — points this browser tab at a remote filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of the filesystem holding the currently displayed directory. Works uniformly for local paths and SFTP paths; for SFTP it requires the server to advertise the <code>statvfs@openssh.com</code> extension (every modern OpenSSH does). Sizes are reported in IEC binary units (MiB, GiB, TiB) — the largest unit yielding a value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB'' rather than ''10240 GiB''.

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code> (or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only; gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file unencrypted (agent-only mode ignores the passphrase, since the OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to '''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally; a ST/X on the Windows side does not. Bridging needs a helper like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's walkback plus each waiter's, formatted as plain text. Use when a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed (e.g. legacy PEM, encrypted-without-agent) — the file is skipped, others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime), no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On servers that advertise <code>posix-rename@openssh.com</code> (every modern OpenSSH does), overwrite is atomic; on the rare server that does not, the receiver is emulated as delete-then-rename and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always returns <code>#isDirectory</code> (the accurate answer would cost three round-trips per directory icon, which made the original tree expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link. Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe, EOF, MNU on nil socket) evicts the dead pool entry, opens a fresh client, retries the request '''once'''. Application-level SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP + one SFTP channel per host means N concurrent requests serialise. Pipelining over multiple SshClients in the pool (preferred), or a transport-level reader process demultiplexing to per-channel inboxes, would let the tree pane keep listing while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (first batch only) + CLOSE — three RTTs per probe; needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style canonicalisation. (Atomic-overwrite rename is already handled via the OpenSSH <code>posix-rename@openssh.com</code> extension; see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]

Remote Access

2026-05-26T18:50:28Z

Sv: Document the Automatic Refresh dropdown toggle and its root-type default

{{Languages|Remote Access|label=Deutsch}}

'''Fernzugriff''' bezeichnet die Möglichkeit, einen entfernten
Rechner oder ein entferntes Netzwerk aus diesem expecco-Image heraus
zu bedienen — Shells zu öffnen, Befehle abzusetzen, Dateien zu
verschieben oder ein Testgerät anzusteuern. Drei Protokoll-Familien
sind unterstützt, in absteigender Empfehlungsreihenfolge:

* '''SSH und SFTP''' (empfohlen) — verschlüsselte Shell und sichere Dateiübertragung über einen SSH-2-Tunnel. Reine Smalltalk-Implementierung in <code>exept:libcrypt/ssh</code>; keine externe Abhängigkeit von OpenSSL oder libssh. Für alles mit Zugangsdaten oder sensiblen Nutzdaten.
* '''Lokale Kommando-Shell''' — fork + exec auf der lokalen Maschine. Für die Anbindung lokaler Werkzeuge und für die lokale Seite eines hybriden Workflows.
* '''Telnet''' (veraltet) — Klartext-Terminalsitzung. Keine Verschlüsselung, Passwörter im Klartext auf der Leitung. Nur einsetzen, wenn die Gegenstelle keine Alternative bietet.

= SSH und SFTP =

Der SSH-Stack deckt das vollständige SSH-2-Protokoll ab
(RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) inklusive der
chacha20-poly1305-Transportchiffrierung von OpenSSH sowie das
SFTP-v3-Subsystem (draft-ietf-secsh-filexfer-02). Zwei Schichten:

* '''<code>SSH::Client</code>''' — programmatischer SSH-Zugriff (entferntes <code>exec</code>, TTY-Shell, Agent-Weiterleitung, ProxyJump-Bastion).
* '''<code>SSH::SftpFilename</code>''' — eine
<code>Filename</code>-Unterklasse, die es dem restlichen ST/X
erlaubt, einen entfernten SFTP-Pfad zu behandeln wie eine lokale
Datei.

Die folgenden Abschnitte sind nutzeraufgaben-zuerst aufgebaut:
zuerst das, was der Anwender sieht und tut, darunter die
expecco-Bibliotheks-Anbindung, ganz unten Implementierungsdetails
für Interessierte.

== Aus dem FileBrowserV2 ==

Im Adress-Dropdown eine <code>sftp://</code>-URL einfügen. Der
Browser-Tab füllt sich wie bei einem lokalen Pfad.
Baum-Ausklappen, Spaltensortierung (Name / Größe / mtime),
Vorschau und Doppelklick zum Öffnen im Editor verhalten sich
normal. Der erste Klick auf einen Host dauert ~200–500 ms
(TCP + KEX + Auth); folgende Klicks nutzen die gepoolte
Verbindung weiter.

URL-Syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

Fehlt <code>user</code>, wird der lokale Login-Name verwendet, Port
ist standardmäßig 22, Pfad standardmäßig <code>/</code>.

Die Schaltfläche '''Refresh''' in der Symbolleiste
(Pfeil-Kreis-Symbol zwischen ''Forward'' und ''DirectoryUp'') liest
Baum und Inhalts-Panel auf Anforderung neu ein. Funktioniert
einheitlich für lokale und SFTP-Pfade; bei SFTP wird zusätzlich der
per-Datei-STAT-Cache geleert, sodass Änderungen, die direkt auf
der Gegenseite gemacht wurden, sofort sichtbar werden — ohne auf
den Ablauf der 5-Sekunden-Cache-TTL zu warten.

Der kleine Pfeil neben dem Refresh-Symbol öffnet ein Aufklappmenü
mit einem einzelnen Kontrollkästchen, '''Automatic Refresh''', das
den Hintergrund-Task an- bzw. abschaltet, der alle expandierten
Baumeinträge auf externe Änderungen prüft. Die Vorgabe richtet
sich nach der aktuellen Wurzel:

* Lokales Dateisystem → '''an''' (10-Sekunden-Zyklus,
entspricht dem bisherigen Verhalten).
* SFTP → '''aus'''. Jeder Zyklus kostet einen
STAT-Roundtrip pro Kind — für eine Handvoll lokaler
Verzeichnisse harmlos, über das Netz schmerzhaft. Bei Bedarf
manuell auf Refresh klicken, um Änderungen zu sehen.

Beim Wechsel zwischen lokalen und SFTP-Wurzeln wird der Schalter
automatisch umgelegt — aber nur, sofern man ihn für die
vorherige Wurzel nicht selbst verstellt hat. Eine explizite
Benutzerwahl bleibt über Navigationen hinweg erhalten.

Das Menü '''Tools''' im FileBrowserV2 bietet vier Aktionen — die
drei SSH-spezifischen sind nur bei geladener SSH-Bibliothek
sichtbar:

* '''Generate SSH Key Pair...''' — öffnet den Schlüsselerzeugungs-Dialog, siehe [[#Einen SSH-Schlüssel erzeugen]] unten.
* '''SSH Connect...''' — öffnet ein interaktives VT100-Terminal zu einem entfernten Host.
* '''SFTP Connect...''' — navigiert diesen Browser-Tab über SFTP auf ein entferntes Dateisystem.
* '''Filesystem Info...''' — zeigt Größe, freien Platz und Belegung des Dateisystems, das das aktuell angezeigte Verzeichnis enthält. Funktioniert einheitlich für lokale und SFTP-Pfade; bei SFTP setzt der Aufruf voraus, daß der Server die Erweiterung
<code>statvfs@openssh.com</code> ankündigt (jedes moderne OpenSSH
tut das). Größen werden in IEC-Binäreinheiten ausgegeben (MiB,
GiB, TiB) — gewählt wird die größte Einheit, die einen Wert ≥ 1
liefert, damit ein TB-großes Volume als ''X TiB'' statt
''10240 GiB'' erscheint.

== Aus expecco-Aktionen ==

Das Expecco-RemoteAccess-Plugin
([[Expecco::RemoteAccessImportPlugin]]) stellt folgende Testaktionen
in der expecco-Aktionspalette bereit:

* '''CmdShell - Open SSH Remote Connection''' — öffnet eine SSH-Sitzung über das plattformeigene <code>ssh</code>-Binary (PuTTYs <code>plink</code> unter Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — dasselbe, jedoch mit expliziter Public-Key-Authentifizierung.

Voraussetzung: ein eingerichtetes Schlüsselpaar (privater
Schlüssel auf dieser Maschine, öffentlicher Teil in der
<code>~/.ssh/authorized_keys</code> des Zielhosts). Schlüssel
erzeugen entweder über den Dialog unten oder über
<code>ssh-keygen</code>.

Das Plugin fügt zusätzlich eine Settings-Seite hinzu:
'''Extras → Settings → Plugins → Remote Access — SSH Keys''' mit
einer einzelnen Schaltfläche '''Generate SSH Key Pair...''', die
denselben Dialog öffnet.

== Einen SSH-Schlüssel erzeugen ==

=== Der Dialog (FileBrowserV2 / Settings-Seite) ===

Der Dialog fragt alle Parameter in einem Formular ab:

* '''Comment''' — wird in den erzeugten Schlüssel eingebettet (Voreinstellung <code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — schreibt
<code>~/.ssh/id_ed25519_stx</code> (oder wohin man will) samt
zugehöriger <code>.pub</code>-Datei daneben.
** ''Save to disk AND load into ssh-agent'' — schreibt die Datei UND übergibt den Schlüssel dem laufenden ssh-agent.
** ''Load into ssh-agent only'' — der Schlüssel lebt nur im Speicher des Agents; nach Agent-Neustart ist er verloren.
* '''Private key file''' — vollständiger Pfad; ausgegraut im Agent-only-Modus.
* '''Passphrase / Confirm''' — leer lässt die On-Disk-Datei unverschlüsselt (Agent-only-Modus ignoriert die Passphrase, da das OpenSSH-Agent-Wire-Protokoll nur den entschlüsselten Schlüssel transportiert).

Bei '''Generate''' wird die Public-Key-Zeile (dieselbe
<code>ssh-ed25519 AAAA... comment</code>-Zeichenfolge, die
ssh-keygen ausgibt) in die System-Zwischenablage kopiert — zum
direkten Einfügen in die <code>~/.ssh/authorized_keys</code> des
Zielhosts.

=== Aus einem Workspace ===

Für Headless-Deployments, Sandbox-Builds oder Skripte stellt
<code>SSH::Client</code> einen reinen Smalltalk-Schlüsselgenerator
bereit, dessen Ausgabe bit-kompatibel zu
<code>ssh-keygen -t ed25519</code> ist:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Passphrase-verschlüsselt auf Platte speichern"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ UND in den laufenden Agent laden"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Public-Key-Zeile zum Einfügen in authorized_keys ausgeben"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Die so erzeugten Schlüssel sind mit den OpenSSH-Werkzeugen voll
interoperabel (<code>ssh-keygen -y -f ...</code> rekonstruiert den
öffentlichen Schlüssel, <code>ssh-keygen -p -f ...</code> ändert
die Passphrase usw.).

=== Mit den Shell-Werkzeugen ===

Der klassische Weg funktioniert weiterhin:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== ssh-agent vorbereiten ==

Der Weg über den Agent ist dem direkten Lesen von Schlüsseldateien
deutlich vorzuziehen: er hält verschlüsselte private Schlüssel
einmal pro Sitzung entsperrt und kann Identitäten verwalten
(hardware-tokengestützte Schlüssel, KeePassXC-Einträge), die ST/X
nie direkt sehen soll.

ST/X erkennt den Agent-Pfad automatisch, sobald
<code>$SSH_AUTH_SOCK</code> '''zum Zeitpunkt des Starts von stx'''
in der Prozessumgebung gesetzt ist. Eine spätere Zuweisung aus
einem Workspace nützt nichts.

=== Linux / macOS ===

Die meisten Desktop-Distributionen starten einen Agent automatisch
beim Login (gnome-keyring unter GNOME, ssh-agent.service unter
systemd, KWallet unter KDE). Prüfen im Terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh oder ähnlich
ssh-add -l # listet geladene Identitäten
ssh-add ~/.ssh/id_ed25519 # eigene laden, falls nicht da
</pre>

Läuft gar kein Agent, dieses Snippet in die Shell-rc-Datei
aufnehmen:

<pre>
# ~/.bashrc oder ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X muss aus einer Shell gestartet werden, die diese rc bereits
gelesen hat — ein Desktop-Launcher aus dem Dateimanager erbt die
Variable nicht. Empfehlung: ein kleines Wrapper-Skript unter
<code>~/.local/bin/</code>, das die rc sourcet und dann stx
startet.

Die Settings-Seite ('''Extras → Settings → Plugins → Remote
Access — SSH Keys''') zeigt an, ob das laufende Image einen
Agent sieht.

==== Permanente Einrichtung via systemd ====

Für einen wirklich sitzungsübergreifenden Agent (überlebt Desktop-
Abmeldung, kommt beim nächsten Login wieder hoch) die bei den
meisten Distros mit dem Paket <code>openssh-clients</code>
ausgelieferte Per-User-systemd-Unit aktivieren:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Anschließend <code>SSH_AUTH_SOCK</code> in der Shell-rc auf den
User-Service-Socket zeigen lassen (ersetzt das
<code>eval $(ssh-agent -s)</code>-Snippet oben):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Schlüssel automatisch beim ersten Einsatz laden ====

Um den manuellen <code>ssh-add</code>-Schritt zu sparen, kann
OpenSSH Schlüssel beim ersten Bedarf selbst in den Agent laden.
In <code>~/.ssh/config</code> eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

Die erste SSH-Verbindung fragt dann einmal nach der Passphrase und
übergibt den entsperrten Schlüssel an den Agent; weitere
Verbindungen nutzen die gespeicherte Identität ohne Prompt.

=== Windows ===

Windows 10+ bringt das native OpenSSH inklusive Agent-Dienst mit.
Einmalige Einrichtung:

# '''Dienste''' (<code>services.msc</code>) als Administrator öffnen.
# '''OpenSSH Authentication Agent''' suchen, Starttyp auf '''Automatisch''' setzen, '''Starten''' anklicken.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Prüfen: <code>ssh-add -l</code>.

Der Windows-OpenSSH-Agent lauscht auf einer Named Pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), nicht auf einem
Unix-Socket. ST/X unterstützt beide Transporte, jedoch setzt das
Windows-ssh-add <code>SSH_AUTH_SOCK</code> '''nicht''' selbst.
Daher einmalig systemweit setzen:

# {{Key|Win}} drücken → "Umgebungsvariablen" → „Systemumgebungs- variablen bearbeiten".
# '''Umgebungsvariablen''' → unter '''Benutzervariablen''', '''Neu''' klicken.
# Name: <code>SSH_AUTH_SOCK</code>
# Wert: <code>\\.\pipe\openssh-ssh-agent</code>
# Ab- und wieder anmelden (oder stx neu starten), damit die neue Umgebung übernommen wird.

==== PowerShell-Schnelleinrichtung ====

Derselbe Aufbau aus einer '''Administrator-PowerShell''' heraus,
z.B. für Skripte oder unbeaufsichtigte Bereitstellung:

<pre>
# Agent jetzt und bei jedem Neustart starten (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# SSH_AUTH_SOCK dauerhaft für den Benutzer setzen (übersteht Reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Schlüssel laden (fragt nach Passphrase, falls die Datei verschlüsselt ist).
ssh-add $HOME\.ssh\id_ed25519
</pre>

Für einen einmaligen Agent-Start ohne dauerhafte Aktivierung
(z.B. Einzelsitzung) die <code>Set-Service</code>-Zeile weglassen
und nur <code>Start-Service ssh-agent</code> ausführen. Die
env-var-Zeile lässt sich ebenfalls weglassen, wenn
<code>SSH_AUTH_SOCK</code> nur in der aktuellen Shell gebraucht
wird — dann statt der <code>[Environment]</code>-Variante
<code>$env:SSH_AUTH_SOCK = '...'</code> verwenden.

Auf stark abgespeckten Windows-Installationen ist der
ssh-agent-Dienst eventuell nicht vorhanden. Einmalig nachrüsten
über '''Einstellungen → Apps → Optionale Features → OpenSSH-
Client'''.

Alternative Agenten:

* '''PuTTY pageant''' — eigenes Protokoll; von ST/X's
<code>SSH::Agent</code> '''nicht''' unterstützt. Schlüssel zu
OpenSSH migrieren.
* '''Git für Windows ssh-agent''' — funktioniert;
<code>SSH_AUTH_SOCK</code> auf den dort veröffentlichten Socket
zeigen lassen.
* '''WSL 2''' — ein ST/X innerhalb der WSL sieht den WSL-eigenen Agent normal; ein ST/X auf der Windows-Seite nicht. Eine Brücke per <code>npiperelay</code> + <code>socat</code> ist möglich.

Prüfung über die Settings-Seite
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
die Anzeige dort meldet, ob das laufende Image den Agent sieht.

==== Schlüssel automatisch beim ersten Einsatz laden ====

Windows-OpenSSH speichert agent-geladene Schlüssel '''nicht'''
über Agent-Neustarts hinweg. Um nicht nach jedem Reboot manuell
<code>ssh-add</code> aufrufen zu müssen, dieselbe Lazy-Load-
Konfiguration in <code>%USERPROFILE%\.ssh\config</code>
eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH lädt den Schlüssel dann beim ersten Einsatz in den Agent
(fragt einmal nach der Passphrase) und nutzt ihn für die übrige
Sitzung weiter.

== Konfiguration ==

Alle Stellschrauben sind klassenseitig auf
<code>SSH::SftpFilename</code> erreichbar:

{| class="wikitable"
! Accessor !! Voreinstellung !! Steuert
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 Min) || Wie lange
eine gepoolte Verbindung im Leerlauf liegen darf, bevor sie beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet wird.
Liegt knapp unter dem typischen
<code>ClientAliveInterval × ClientAliveCountMax</code> des sshd,
damit wir uns recyceln, bevor der Server uns mit TCP-RESET
trennt. <code>nil</code> setzt auf Voreinstellung zurück.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Maximales Alter (s)
eines gecachten STAT, bevor <code>#ensureAttrs</code> neu am
Server fragt. Eltern-listDir stempelt ohnehin frische Attribute
auf alle Kinder, daher zahlt das Navigieren im offenen
Verzeichnis das TTL nicht. <code>0</code> schaltet den Cache
ab.
|-
| <code>#closeAllConnections</code> || (Aktion) || Reißt jede
gepoolte Verbindung ab. Nützlich nach einem bekannt schlechten
Netzereignis, vor einem bewussten Identitätswechsel oder zum
sauberen Image-Shutdown.
|}

== Diagnose ==

=== SemaphoreMonitor ===

<code>SemaphoreMonitor</code> über das Untermenü „Status" des
Launchers öffnen. Der pro-Host-SFTP-Mutex erscheint als
<code>SFTP/<user@host:port></code>, der pool-weite Mutex als
<code>SFTP/pool</code>. Per Rechtsklick:

* '''Copy Waiters Stack to Clipboard''' — schreibt den Walkback des letzten Eigners samt aller Waiter als Text in die Zwischenablage. Unverzichtbar, wenn ein Prozess in
<code>readWait</code> innerhalb von
<code>withSftpClientDo:</code> klemmt.
* '''Copy List to Clipboard''' — die ganze Tabelle, ideal für eine E-Mail-Diagnose.
* '''Detect Deadlocks''' — DFS über den Wait-for-Graph, meldet Zyklen.

=== Logger ===

Interessante Ereignisse werden über <code>Logger</code> geloggt:

* <code>warning:</code> bei automatischem Reconnect nach toter Verbindung.
* <code>warning:</code> bei Idle-Verdrängung eines Pool-Eintrags.
* <code>warning:</code> wenn eine SSH-Schlüsseldatei nicht geparst werden konnte — die Datei wird übersprungen.

== Einschränkungen ==

* '''Nur SFTP v3.''' Kein SETSTAT (kein entferntes chmod / chown / utime), kein SSH_FXP_READLINK exponiert (<code>#isSymbolicLink</code> liefert immer <code>false</code>,
<code>#linkInfo</code> die normale stat-Info). Einige
SFTPv5+-Annehmlichkeiten werden dennoch über OpenSSH-spezifische
SSH_FXP_EXTENDED-Aufrufe nutzbar — siehe
[[#OpenSSH-SFTP-Erweiterungen]] weiter unten.
* '''Serialisierung pro Host.''' Zwei gleichzeitige Operationen am selben Host stehen am Host-Mutex an. Siehe [[#Ausblick]].
* '''<code>#renameTo:</code>-Fallback hat ein TOCTOU-Fenster.''' Bei Servern, die <code>posix-rename@openssh.com</code> ankündigen (jedes moderne OpenSSH tut das), ist das Überschreiben atomar. Beim seltenen Server, der das nicht tut, wird auf Delete-dann-Rename ausgewichen und ein anderer Prozess kann sich dazwischenschieben.
* '''<code>#isNonEmptyDirectory</code> ist eine Heuristik.''' Liefert immer <code>#isDirectory</code> (die genaue Antwort würde drei Roundtrips pro Verzeichnis-Symbol kosten, was das ursprüngliche Baum-Ausklappen unerträglich gebremst hatte).

== Implementierungsdetails ==

Für Leser, die die Architektur verstehen wollen. Fünf Klassen,
von oben nach unten:

{| class="wikitable"
! Klasse !! Aufgabe
|-
| <code>SSH::SftpFilename</code> || Filename-Unterklasse, die
öffentliche API. Bildet <code>sftp://...</code>-URLs auf
entfernte Dateien ab und stellt <code>directoryContents</code>,
<code>readingFileDo:</code>, <code>renameTo:</code> usw. bereit.
|-
| <code>SSH::SftpClient</code> || SFTP-v3-Protokoll
(Request/Response-Codec, listDir, stat, open, read, write, mkdir).
Wird von SftpFilename angesteuert.
|-
| <code>SSH::Channel</code> || SSH-Kanal-Multiplexer (CHANNEL_OPEN,
DATA, EOF, CLOSE, WINDOW_ADJUST). Eine logische Sitzung pro
Channel-Instanz.
|-
| <code>SSH::Client</code> || High-Level-SSH-Client: öffnet den
Transport, führt KEX, Hostschlüssel-Prüfung und userauth durch und
verteilt anschließend Kanäle.
|-
| <code>SSH::Transport</code> || Drahtschicht. Banner- und
KEXINIT-Austausch, ChaCha20-Poly1305-Paket-Framing, sendSeq /
recvSeq, Heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH-SFTP-Erweiterungen ===

SFTP v3 (Entwurf draft-ietf-secsh-filexfer-02) ist bewusst
minimal gehalten. OpenSSH bringt einen offenen
Erweiterungsmechanismus mit: der Server listet im
<code>SSH_FXP_VERSION</code>-Reply die Erweiterungsnamen auf, die
er versteht, und der Client ruft sie über
<code>SSH_FXP_EXTENDED(200)</code>-Pakete mit dem
Erweiterungsnamen als erstem String auf. Jede Erweiterung wird
über <code>SSH::SftpClient>>supportsExtension:</code>
feature-detektiert; Aufrufer fallen zurück, wenn der Server sie
nicht ankündigt.

Der Stack nutzt heute vier OpenSSH-Erweiterungen:

* <code>posix-rename@openssh.com</code> — atomares rename-mit-Überschreiben. Wird automatisch von
<code>SftpFilename>>renameTo:</code> aufgegriffen; die
Delete-dann-Rename-Fallback-Variante kommt nur bei Servern zum
Einsatz, die die Erweiterung nicht haben.
* <code>hardlink@openssh.com</code> — Erzeugt einen POSIX-Hardlink. Verfügbar als <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX-
<code>statvfs(3)</code>-typische Dateisystem-Statistik.
Verfügbar als <code>SftpFilename>>fileSystemInfo</code>;
das Ergebnis ist form-kompatibel zu
<code>OperatingSystem getDiskInfoOf:</code>, sodass Aufrufer
lokale und entfernte Pfade einheitlich behandeln können.
Treibt den Menü-Eintrag '''Tools → Filesystem Info...''' an,
der am Anfang dieser Seite beschrieben ist.
* <code>fsync@openssh.com</code> — schreibt den serverseitigen Schreibpuffer eines geöffneten Handles auf Platte. Liegt als
<code>SftpClient>>fsyncHandle:</code> bereit; noch nicht
in eine "Durable-Write"-API auf Filename-Ebene eingebunden.

Die verbleibenden OpenSSH-Erweiterungen
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
werden in der angekündigten Liste erkannt, aber nicht auf
Filename-Ebene gekapselt — es gibt dafür noch keinen
Filename-seitigen Aufrufer.

=== Verbindungs-Pooling ===

Alle <code>SftpFilename</code>-Instanzen, die auf dasselbe Tripel
<code>user@host:port</code> zeigen, teilen sich einen
<code>SSH::Client</code> samt einem <code>SSH::SftpClient</code>.
Der Pool ist klassenseitig und wird von einem einzigen
<code>ConnectionPoolMutex</code> bewacht:

* '''Lazy-Aufbau''' — TCP + KEX + userauth + SFTP-INIT laufen erst beim ersten SFTP-Aufruf, nicht in <code>forUrl:</code>.
* '''Serialisierung pro Host''' — SFTP-Anfragen an einen bestimmten Host werden durch einen <code>RecursionLock</code> mit dem Namen <code>SFTP/<user@host:port></code> serialisiert (sichtbar im SemaphoreMonitor).
* '''Idle-Verdrängung''' — ein Pool-Eintrag, der länger als
<code>idleEvictionSeconds</code> ungenutzt liegt, wird beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet.
* '''Automatischer Reconnect''' — ein Fehler auf Transportebene (Broken Pipe, EOF, MNU auf nil-Socket) verdrängt den Pool-Eintrag, öffnet einen frischen Client und wiederholt die Anfrage '''einmal'''. Anwendungsfehler aus SFTP-STATUS-Antworten werden sofort durchgereicht.

== Ausblick ==

Geplant, aber noch nicht umgesetzt:

* '''Multi-Channel-Parallelität pro Host''' — aktuell bedeutet eine TCP- plus eine SFTP-Verbindung pro Host, dass N gleichzeitige Anfragen serialisieren. Pipelining über mehrere SshClients im Pool (bevorzugt) oder ein transport-seitiger Reader-Prozess, der eingehende Pakete in Pro-Kanal-Postfächer demultiplext, würde es dem Baum-Panel erlauben, weiter aufzulisten, während das Inhalts-Panel eine große Datei liest.
* '''Genaues <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (nur erstes Batch) + CLOSE — drei Roundtrips pro Sondierung; lohnt erst, wenn der SftpClient Anfragen pipelinen kann.
* '''SFTP-v5/v6-Aushandlung''' für erweiterte Attribute und FTP-artige Kanonisierung. (Atomares Überschreibungs-rename ist bereits über die OpenSSH-Erweiterung
<code>posix-rename@openssh.com</code> abgedeckt; siehe
[[#OpenSSH-SFTP-Erweiterungen]].)

= Kommando-Shell =

Lokale Kommando-Shell auf dieser expecco-Maschine. Typische
Anwendungen: lokale Kommandozeile, lokales Hilfsprogramm,
Brücke zwischen entferntem Workflow und lokalem Tool.

Das RemoteAccess-Plugin stellt bereit:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

Keine Zugangsdaten, kein Netzwerk — läuft als der Benutzer des
expecco-Prozesses. Ausgaben gehen in das expecco-Log.

= Telnet =

[[File:Warning.svg|24px|Warnung]] '''Telnet ist ein veraltetes
Protokoll ohne Verschlüsselung.''' Passwörter werden im Klartext
über die Leitung übertragen; jeder im Netzpfad kann sie lesen.
Telnet NUR einsetzen, wenn die Gegenstelle keine Alternative
bietet (typisch: alte Industriesteuerungen, Laborgeräte,
eingebettete Messgeräte ohne SSH-Stack). Für alles andere
[[#SSH und SFTP]] verwenden.

Das expecco-Plugin stellt bereit:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (interne Demo)

Das Telnet-Protokoll (RFC 854) ist ein bidirektionaler
8-Bit-Byte-Strom über TCP, mit In-Band-Steuersequenzen für
Terminal-Optionen. Verbindungsaufbau zum Ziel-Host:Port; nach
optionalem In-Band-Login können beide Seiten Daten senden.

= Siehe auch =

* [[SSH Client|SSH::Client]] — die SSH-Schicht (exec, TTY, Agent-Weiterleitung, ProxyJump).
* [[FileBrowserV2]] — die Haupt-UI dieses Stacks.
* [[ClaudeCode plugin|Claude Code]] — nutzt denselben SSH-Stack als HTTPS-Transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Netz]]
[[Category:SSH]]

Release Notes 26.x

2026-05-26T14:42:30Z

Sv: update bridge features: SSL for all bridges incl. Dart+Smalltalk, getFile/putFile/makeDirectory for all bridges, defineFunction/callFunction for NodeJS/Ruby/Smalltalk

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==

== Release 26.1 (Q2 2026) ==

* Feature: '''NEW''' [[KI Coding Plugin|'''AI Coding''']] plugin (chat-assistant integration for the activity editor and class browser):
** supports both '''Anthropic Claude''', '''OpenAI ChatGPT''' or '''Llama''' as backends, switchable from the settings dialog (Plugins → AI Coding); API keys are stored per provider so you can flip between them without re-entering
** Toolbar / class-browser menu adapts to the active provider — reads "''Ask Claude''" or "''Ask ChatGPT''", updates live when the provider is switched
** Menu actions: Explain code/method, Suggest improvement, Generate test, Generate doc-comment (fills the Documentation tab and pin comments), Find bugs, Custom prompt; "[Apply]" can install proposed code directly into the activity body or compile a proposed helper method into a class
** Chat window streams responses live (Server-Sent Events) and shows running token count + estimated cost in the title; supports image attachments (screenshots / PNG-JPG files)
** model, API key, endpoint and max-tokens are configurable via the Claude settings dialog
* Feature: SSL1.3 support (without external SSL library)
* Feature: SSL support for C, Python, NodeJS, Ruby, Dart and Smalltalk bridges (combined cert+key PEM files supported)
* Feature: SSH builtin, plus SSH and SFTP clients (both via FileBrowser)
* Feature: public/private keypair generation via a FileBrowser menu (for easy SSH setup)
* Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.
* Feature: Improved/Fixed Number stack:
** Enhanced multiprecision numbers (eg. <float>q, <float>Q constants in freeze values)
** Float32 numbers (<float>f)
** Integer freezeValues in exponential notation (eg. 1e5)
** Recognize type specific infinities eg. "inf.0", "inf.0f", "inf.0q" etc. (useful when parsing/receiving values from the outside world)
** Recognize type specific NaNs eg. "nan.0", "nan.0f", "nan.0q" etc. (useful when parsing/receiving values from the outside world)
** fixed/added missing trigonometric functions for multiprecision floats and complex numbers (eg. arcTan)
** inspector (and activitylog as a consequence) show the type of a float (suffix 'f', 'q', 'Q' etc.)

* Feature: Workflow editor — improved orthogonal routing of connections:
** connections now detour around blocks, freeze values and annotation boxes instead of cutting through them
** connections from a compound block's input-pin descriptions are bundled into a bus column next to the source pin
** end-stub avoidance no longer fires on near-misses (strict overlap check, no clearance margin)
** routing prefers the source-side bend when the source step has multiple sibling pins
* Feature: Workflow editor — improved naïve autolayout: added horizontal and vertical expansion passes that spread adjacent blocks apart for clearer connection routing
* Feature: file transfer (getFile/putFile) and makeDirectory for all bridges (C, Python, NodeJS, Ruby, Dart, Smalltalk)
* Feature: defineFunction/callFunction support for NodeJS, Ruby and Smalltalk bridges
* Performance: execution of elementary Smalltalk and JavaScript actions tuned for speed (Jitter improvements)
* Feature: OLE for 64 bit architectures
* Feature: optional HTTPS for the AIDYMO and license server — drop a PEM cert+key into <code>--workDir</code> (combined <code>server.pem</code>, or split<code>fullchain.pem</code>+<code>privkey.pem</code> / <code>cert.pem</code>+<code>key.pem</code>) and the service binds TLS automatically; informational hostname is derived from the certificate (SAN-aware, wildcard- and multi-SAN-safe)
* Feature: more search options in the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example | MethodFinder]].
*Fix: many fixes related to DPI scaling. I.e. when multiple monitors are configured with different scaling (especially different from 100%). Includes scaling of fonts, bitmap and UI components (widgets).
*Fix: display of very long lines in a text editor/inspector (workaround a Windows 16bit line limit)
*Fix: due to a bug in enumeration datatypes, the size of ".ets" files grew over time to huge sizes (some information was redundantly and identically written twice). This had no effect on the execution, but made load/save times almost unacceptably long by storing/reloading unneeded data. When loaded and saved again, this will fix those ets files automatically (there is also a patch for older versions)

Remote Access/en

2026-05-26T13:46:08Z

Sv: Document the Refresh toolbar button (and the disabled tree auto-poll)

{{Languages|Remote Access/en|label=English}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation in <code>exept:libcrypt/ssh</code>; no external dependency on OpenSSL or libssh. Use this for anything that touches credentials or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine. Used for local-tool integration and for the local end of a remote workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No encryption, passwords on the wire in clear. Use only when the target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code> subclass that lets the rest of ST/X treat a remote SFTP path the same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>.

The directory tree does '''not''' auto-update: previously a background
task walked every expanded item every 10 seconds, which over SFTP
meant one STAT round-trip per child on every cycle. Click the
'''Refresh''' button in the toolbar (the round-arrow icon between
''Forward'' and ''DirectoryUp'') to re-read the tree and the
contents pane on demand. Refresh works uniformly for local and
SFTP paths; for SFTP it also flushes the per-file STAT cache, so
changes made directly on the remote side become visible
immediately rather than waiting for the 5-second cache TTL to
expire.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a remote host.
* '''SFTP Connect...''' — points this browser tab at a remote filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of the filesystem holding the currently displayed directory. Works uniformly for local paths and SFTP paths; for SFTP it requires the server to advertise the <code>statvfs@openssh.com</code> extension (every modern OpenSSH does). Sizes are reported in IEC binary units (MiB, GiB, TiB) — the largest unit yielding a value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB'' rather than ''10240 GiB''.

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code> (or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only; gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file unencrypted (agent-only mode ignores the passphrase, since the OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to '''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally; a ST/X on the Windows side does not. Bridging needs a helper like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's walkback plus each waiter's, formatted as plain text. Use when a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed (e.g. legacy PEM, encrypted-without-agent) — the file is skipped, others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime), no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On servers that advertise <code>posix-rename@openssh.com</code> (every modern OpenSSH does), overwrite is atomic; on the rare server that does not, the receiver is emulated as delete-then-rename and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always returns <code>#isDirectory</code> (the accurate answer would cost three round-trips per directory icon, which made the original tree expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link. Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe, EOF, MNU on nil socket) evicts the dead pool entry, opens a fresh client, retries the request '''once'''. Application-level SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP + one SFTP channel per host means N concurrent requests serialise. Pipelining over multiple SshClients in the pool (preferred), or a transport-level reader process demultiplexing to per-channel inboxes, would let the tree pane keep listing while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (first batch only) + CLOSE — three RTTs per probe; needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style canonicalisation. (Atomic-overwrite rename is already handled via the OpenSSH <code>posix-rename@openssh.com</code> extension; see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]

Remote Access

2026-05-26T13:46:07Z

Sv: Document the Refresh toolbar button (and the disabled tree auto-poll)

{{Languages|Remote Access|label=Deutsch}}

'''Fernzugriff''' bezeichnet die Möglichkeit, einen entfernten
Rechner oder ein entferntes Netzwerk aus diesem expecco-Image heraus
zu bedienen — Shells zu öffnen, Befehle abzusetzen, Dateien zu
verschieben oder ein Testgerät anzusteuern. Drei Protokoll-Familien
sind unterstützt, in absteigender Empfehlungsreihenfolge:

* '''SSH und SFTP''' (empfohlen) — verschlüsselte Shell und sichere Dateiübertragung über einen SSH-2-Tunnel. Reine Smalltalk-Implementierung in <code>exept:libcrypt/ssh</code>; keine externe Abhängigkeit von OpenSSL oder libssh. Für alles mit Zugangsdaten oder sensiblen Nutzdaten.
* '''Lokale Kommando-Shell''' — fork + exec auf der lokalen Maschine. Für die Anbindung lokaler Werkzeuge und für die lokale Seite eines hybriden Workflows.
* '''Telnet''' (veraltet) — Klartext-Terminalsitzung. Keine Verschlüsselung, Passwörter im Klartext auf der Leitung. Nur einsetzen, wenn die Gegenstelle keine Alternative bietet.

= SSH und SFTP =

Der SSH-Stack deckt das vollständige SSH-2-Protokoll ab
(RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) inklusive der
chacha20-poly1305-Transportchiffrierung von OpenSSH sowie das
SFTP-v3-Subsystem (draft-ietf-secsh-filexfer-02). Zwei Schichten:

* '''<code>SSH::Client</code>''' — programmatischer SSH-Zugriff (entferntes <code>exec</code>, TTY-Shell, Agent-Weiterleitung, ProxyJump-Bastion).
* '''<code>SSH::SftpFilename</code>''' — eine
<code>Filename</code>-Unterklasse, die es dem restlichen ST/X
erlaubt, einen entfernten SFTP-Pfad zu behandeln wie eine lokale
Datei.

Die folgenden Abschnitte sind nutzeraufgaben-zuerst aufgebaut:
zuerst das, was der Anwender sieht und tut, darunter die
expecco-Bibliotheks-Anbindung, ganz unten Implementierungsdetails
für Interessierte.

== Aus dem FileBrowserV2 ==

Im Adress-Dropdown eine <code>sftp://</code>-URL einfügen. Der
Browser-Tab füllt sich wie bei einem lokalen Pfad.
Baum-Ausklappen, Spaltensortierung (Name / Größe / mtime),
Vorschau und Doppelklick zum Öffnen im Editor verhalten sich
normal. Der erste Klick auf einen Host dauert ~200–500 ms
(TCP + KEX + Auth); folgende Klicks nutzen die gepoolte
Verbindung weiter.

URL-Syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

Fehlt <code>user</code>, wird der lokale Login-Name verwendet, Port
ist standardmäßig 22, Pfad standardmäßig <code>/</code>.

Der Verzeichnisbaum aktualisiert sich '''nicht''' automatisch:
früher lief im Hintergrund alle 10 Sekunden ein Task über jeden
expandierten Eintrag, was bei SFTP einen STAT-Roundtrip pro Kind
und Zyklus bedeutete. Mit der Schaltfläche '''Refresh''' in der
Symbolleiste (Pfeil-Kreis-Symbol zwischen ''Forward'' und
''DirectoryUp'') werden Baum und Inhalts-Panel auf Anforderung
neu eingelesen. Refresh funktioniert einheitlich für lokale und
SFTP-Pfade; bei SFTP wird zusätzlich der per-Datei-STAT-Cache
geleert, sodass Änderungen, die direkt auf der Gegenseite
gemacht wurden, sofort sichtbar werden — ohne auf den Ablauf der
5-Sekunden-Cache-TTL zu warten.

Das Menü '''Tools''' im FileBrowserV2 bietet vier Aktionen — die
drei SSH-spezifischen sind nur bei geladener SSH-Bibliothek
sichtbar:

* '''Generate SSH Key Pair...''' — öffnet den Schlüsselerzeugungs-Dialog, siehe [[#Einen SSH-Schlüssel erzeugen]] unten.
* '''SSH Connect...''' — öffnet ein interaktives VT100-Terminal zu einem entfernten Host.
* '''SFTP Connect...''' — navigiert diesen Browser-Tab über SFTP auf ein entferntes Dateisystem.
* '''Filesystem Info...''' — zeigt Größe, freien Platz und Belegung des Dateisystems, das das aktuell angezeigte Verzeichnis enthält. Funktioniert einheitlich für lokale und SFTP-Pfade; bei SFTP setzt der Aufruf voraus, daß der Server die Erweiterung
<code>statvfs@openssh.com</code> ankündigt (jedes moderne OpenSSH
tut das). Größen werden in IEC-Binäreinheiten ausgegeben (MiB,
GiB, TiB) — gewählt wird die größte Einheit, die einen Wert ≥ 1
liefert, damit ein TB-großes Volume als ''X TiB'' statt
''10240 GiB'' erscheint.

== Aus expecco-Aktionen ==

Das Expecco-RemoteAccess-Plugin
([[Expecco::RemoteAccessImportPlugin]]) stellt folgende Testaktionen
in der expecco-Aktionspalette bereit:

* '''CmdShell - Open SSH Remote Connection''' — öffnet eine SSH-Sitzung über das plattformeigene <code>ssh</code>-Binary (PuTTYs <code>plink</code> unter Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — dasselbe, jedoch mit expliziter Public-Key-Authentifizierung.

Voraussetzung: ein eingerichtetes Schlüsselpaar (privater
Schlüssel auf dieser Maschine, öffentlicher Teil in der
<code>~/.ssh/authorized_keys</code> des Zielhosts). Schlüssel
erzeugen entweder über den Dialog unten oder über
<code>ssh-keygen</code>.

Das Plugin fügt zusätzlich eine Settings-Seite hinzu:
'''Extras → Settings → Plugins → Remote Access — SSH Keys''' mit
einer einzelnen Schaltfläche '''Generate SSH Key Pair...''', die
denselben Dialog öffnet.

== Einen SSH-Schlüssel erzeugen ==

=== Der Dialog (FileBrowserV2 / Settings-Seite) ===

Der Dialog fragt alle Parameter in einem Formular ab:

* '''Comment''' — wird in den erzeugten Schlüssel eingebettet (Voreinstellung <code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — schreibt
<code>~/.ssh/id_ed25519_stx</code> (oder wohin man will) samt
zugehöriger <code>.pub</code>-Datei daneben.
** ''Save to disk AND load into ssh-agent'' — schreibt die Datei UND übergibt den Schlüssel dem laufenden ssh-agent.
** ''Load into ssh-agent only'' — der Schlüssel lebt nur im Speicher des Agents; nach Agent-Neustart ist er verloren.
* '''Private key file''' — vollständiger Pfad; ausgegraut im Agent-only-Modus.
* '''Passphrase / Confirm''' — leer lässt die On-Disk-Datei unverschlüsselt (Agent-only-Modus ignoriert die Passphrase, da das OpenSSH-Agent-Wire-Protokoll nur den entschlüsselten Schlüssel transportiert).

Bei '''Generate''' wird die Public-Key-Zeile (dieselbe
<code>ssh-ed25519 AAAA... comment</code>-Zeichenfolge, die
ssh-keygen ausgibt) in die System-Zwischenablage kopiert — zum
direkten Einfügen in die <code>~/.ssh/authorized_keys</code> des
Zielhosts.

=== Aus einem Workspace ===

Für Headless-Deployments, Sandbox-Builds oder Skripte stellt
<code>SSH::Client</code> einen reinen Smalltalk-Schlüsselgenerator
bereit, dessen Ausgabe bit-kompatibel zu
<code>ssh-keygen -t ed25519</code> ist:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Passphrase-verschlüsselt auf Platte speichern"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ UND in den laufenden Agent laden"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Public-Key-Zeile zum Einfügen in authorized_keys ausgeben"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Die so erzeugten Schlüssel sind mit den OpenSSH-Werkzeugen voll
interoperabel (<code>ssh-keygen -y -f ...</code> rekonstruiert den
öffentlichen Schlüssel, <code>ssh-keygen -p -f ...</code> ändert
die Passphrase usw.).

=== Mit den Shell-Werkzeugen ===

Der klassische Weg funktioniert weiterhin:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== ssh-agent vorbereiten ==

Der Weg über den Agent ist dem direkten Lesen von Schlüsseldateien
deutlich vorzuziehen: er hält verschlüsselte private Schlüssel
einmal pro Sitzung entsperrt und kann Identitäten verwalten
(hardware-tokengestützte Schlüssel, KeePassXC-Einträge), die ST/X
nie direkt sehen soll.

ST/X erkennt den Agent-Pfad automatisch, sobald
<code>$SSH_AUTH_SOCK</code> '''zum Zeitpunkt des Starts von stx'''
in der Prozessumgebung gesetzt ist. Eine spätere Zuweisung aus
einem Workspace nützt nichts.

=== Linux / macOS ===

Die meisten Desktop-Distributionen starten einen Agent automatisch
beim Login (gnome-keyring unter GNOME, ssh-agent.service unter
systemd, KWallet unter KDE). Prüfen im Terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh oder ähnlich
ssh-add -l # listet geladene Identitäten
ssh-add ~/.ssh/id_ed25519 # eigene laden, falls nicht da
</pre>

Läuft gar kein Agent, dieses Snippet in die Shell-rc-Datei
aufnehmen:

<pre>
# ~/.bashrc oder ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X muss aus einer Shell gestartet werden, die diese rc bereits
gelesen hat — ein Desktop-Launcher aus dem Dateimanager erbt die
Variable nicht. Empfehlung: ein kleines Wrapper-Skript unter
<code>~/.local/bin/</code>, das die rc sourcet und dann stx
startet.

Die Settings-Seite ('''Extras → Settings → Plugins → Remote
Access — SSH Keys''') zeigt an, ob das laufende Image einen
Agent sieht.

==== Permanente Einrichtung via systemd ====

Für einen wirklich sitzungsübergreifenden Agent (überlebt Desktop-
Abmeldung, kommt beim nächsten Login wieder hoch) die bei den
meisten Distros mit dem Paket <code>openssh-clients</code>
ausgelieferte Per-User-systemd-Unit aktivieren:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Anschließend <code>SSH_AUTH_SOCK</code> in der Shell-rc auf den
User-Service-Socket zeigen lassen (ersetzt das
<code>eval $(ssh-agent -s)</code>-Snippet oben):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Schlüssel automatisch beim ersten Einsatz laden ====

Um den manuellen <code>ssh-add</code>-Schritt zu sparen, kann
OpenSSH Schlüssel beim ersten Bedarf selbst in den Agent laden.
In <code>~/.ssh/config</code> eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

Die erste SSH-Verbindung fragt dann einmal nach der Passphrase und
übergibt den entsperrten Schlüssel an den Agent; weitere
Verbindungen nutzen die gespeicherte Identität ohne Prompt.

=== Windows ===

Windows 10+ bringt das native OpenSSH inklusive Agent-Dienst mit.
Einmalige Einrichtung:

# '''Dienste''' (<code>services.msc</code>) als Administrator öffnen.
# '''OpenSSH Authentication Agent''' suchen, Starttyp auf '''Automatisch''' setzen, '''Starten''' anklicken.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Prüfen: <code>ssh-add -l</code>.

Der Windows-OpenSSH-Agent lauscht auf einer Named Pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), nicht auf einem
Unix-Socket. ST/X unterstützt beide Transporte, jedoch setzt das
Windows-ssh-add <code>SSH_AUTH_SOCK</code> '''nicht''' selbst.
Daher einmalig systemweit setzen:

# {{Key|Win}} drücken → "Umgebungsvariablen" → „Systemumgebungs- variablen bearbeiten".
# '''Umgebungsvariablen''' → unter '''Benutzervariablen''', '''Neu''' klicken.
# Name: <code>SSH_AUTH_SOCK</code>
# Wert: <code>\\.\pipe\openssh-ssh-agent</code>
# Ab- und wieder anmelden (oder stx neu starten), damit die neue Umgebung übernommen wird.

==== PowerShell-Schnelleinrichtung ====

Derselbe Aufbau aus einer '''Administrator-PowerShell''' heraus,
z.B. für Skripte oder unbeaufsichtigte Bereitstellung:

<pre>
# Agent jetzt und bei jedem Neustart starten (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# SSH_AUTH_SOCK dauerhaft für den Benutzer setzen (übersteht Reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Schlüssel laden (fragt nach Passphrase, falls die Datei verschlüsselt ist).
ssh-add $HOME\.ssh\id_ed25519
</pre>

Für einen einmaligen Agent-Start ohne dauerhafte Aktivierung
(z.B. Einzelsitzung) die <code>Set-Service</code>-Zeile weglassen
und nur <code>Start-Service ssh-agent</code> ausführen. Die
env-var-Zeile lässt sich ebenfalls weglassen, wenn
<code>SSH_AUTH_SOCK</code> nur in der aktuellen Shell gebraucht
wird — dann statt der <code>[Environment]</code>-Variante
<code>$env:SSH_AUTH_SOCK = '...'</code> verwenden.

Auf stark abgespeckten Windows-Installationen ist der
ssh-agent-Dienst eventuell nicht vorhanden. Einmalig nachrüsten
über '''Einstellungen → Apps → Optionale Features → OpenSSH-
Client'''.

Alternative Agenten:

* '''PuTTY pageant''' — eigenes Protokoll; von ST/X's
<code>SSH::Agent</code> '''nicht''' unterstützt. Schlüssel zu
OpenSSH migrieren.
* '''Git für Windows ssh-agent''' — funktioniert;
<code>SSH_AUTH_SOCK</code> auf den dort veröffentlichten Socket
zeigen lassen.
* '''WSL 2''' — ein ST/X innerhalb der WSL sieht den WSL-eigenen Agent normal; ein ST/X auf der Windows-Seite nicht. Eine Brücke per <code>npiperelay</code> + <code>socat</code> ist möglich.

Prüfung über die Settings-Seite
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
die Anzeige dort meldet, ob das laufende Image den Agent sieht.

==== Schlüssel automatisch beim ersten Einsatz laden ====

Windows-OpenSSH speichert agent-geladene Schlüssel '''nicht'''
über Agent-Neustarts hinweg. Um nicht nach jedem Reboot manuell
<code>ssh-add</code> aufrufen zu müssen, dieselbe Lazy-Load-
Konfiguration in <code>%USERPROFILE%\.ssh\config</code>
eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH lädt den Schlüssel dann beim ersten Einsatz in den Agent
(fragt einmal nach der Passphrase) und nutzt ihn für die übrige
Sitzung weiter.

== Konfiguration ==

Alle Stellschrauben sind klassenseitig auf
<code>SSH::SftpFilename</code> erreichbar:

{| class="wikitable"
! Accessor !! Voreinstellung !! Steuert
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 Min) || Wie lange
eine gepoolte Verbindung im Leerlauf liegen darf, bevor sie beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet wird.
Liegt knapp unter dem typischen
<code>ClientAliveInterval × ClientAliveCountMax</code> des sshd,
damit wir uns recyceln, bevor der Server uns mit TCP-RESET
trennt. <code>nil</code> setzt auf Voreinstellung zurück.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Maximales Alter (s)
eines gecachten STAT, bevor <code>#ensureAttrs</code> neu am
Server fragt. Eltern-listDir stempelt ohnehin frische Attribute
auf alle Kinder, daher zahlt das Navigieren im offenen
Verzeichnis das TTL nicht. <code>0</code> schaltet den Cache
ab.
|-
| <code>#closeAllConnections</code> || (Aktion) || Reißt jede
gepoolte Verbindung ab. Nützlich nach einem bekannt schlechten
Netzereignis, vor einem bewussten Identitätswechsel oder zum
sauberen Image-Shutdown.
|}

== Diagnose ==

=== SemaphoreMonitor ===

<code>SemaphoreMonitor</code> über das Untermenü „Status" des
Launchers öffnen. Der pro-Host-SFTP-Mutex erscheint als
<code>SFTP/<user@host:port></code>, der pool-weite Mutex als
<code>SFTP/pool</code>. Per Rechtsklick:

* '''Copy Waiters Stack to Clipboard''' — schreibt den Walkback des letzten Eigners samt aller Waiter als Text in die Zwischenablage. Unverzichtbar, wenn ein Prozess in
<code>readWait</code> innerhalb von
<code>withSftpClientDo:</code> klemmt.
* '''Copy List to Clipboard''' — die ganze Tabelle, ideal für eine E-Mail-Diagnose.
* '''Detect Deadlocks''' — DFS über den Wait-for-Graph, meldet Zyklen.

=== Logger ===

Interessante Ereignisse werden über <code>Logger</code> geloggt:

* <code>warning:</code> bei automatischem Reconnect nach toter Verbindung.
* <code>warning:</code> bei Idle-Verdrängung eines Pool-Eintrags.
* <code>warning:</code> wenn eine SSH-Schlüsseldatei nicht geparst werden konnte — die Datei wird übersprungen.

== Einschränkungen ==

* '''Nur SFTP v3.''' Kein SETSTAT (kein entferntes chmod / chown / utime), kein SSH_FXP_READLINK exponiert (<code>#isSymbolicLink</code> liefert immer <code>false</code>,
<code>#linkInfo</code> die normale stat-Info). Einige
SFTPv5+-Annehmlichkeiten werden dennoch über OpenSSH-spezifische
SSH_FXP_EXTENDED-Aufrufe nutzbar — siehe
[[#OpenSSH-SFTP-Erweiterungen]] weiter unten.
* '''Serialisierung pro Host.''' Zwei gleichzeitige Operationen am selben Host stehen am Host-Mutex an. Siehe [[#Ausblick]].
* '''<code>#renameTo:</code>-Fallback hat ein TOCTOU-Fenster.''' Bei Servern, die <code>posix-rename@openssh.com</code> ankündigen (jedes moderne OpenSSH tut das), ist das Überschreiben atomar. Beim seltenen Server, der das nicht tut, wird auf Delete-dann-Rename ausgewichen und ein anderer Prozess kann sich dazwischenschieben.
* '''<code>#isNonEmptyDirectory</code> ist eine Heuristik.''' Liefert immer <code>#isDirectory</code> (die genaue Antwort würde drei Roundtrips pro Verzeichnis-Symbol kosten, was das ursprüngliche Baum-Ausklappen unerträglich gebremst hatte).

== Implementierungsdetails ==

Für Leser, die die Architektur verstehen wollen. Fünf Klassen,
von oben nach unten:

{| class="wikitable"
! Klasse !! Aufgabe
|-
| <code>SSH::SftpFilename</code> || Filename-Unterklasse, die
öffentliche API. Bildet <code>sftp://...</code>-URLs auf
entfernte Dateien ab und stellt <code>directoryContents</code>,
<code>readingFileDo:</code>, <code>renameTo:</code> usw. bereit.
|-
| <code>SSH::SftpClient</code> || SFTP-v3-Protokoll
(Request/Response-Codec, listDir, stat, open, read, write, mkdir).
Wird von SftpFilename angesteuert.
|-
| <code>SSH::Channel</code> || SSH-Kanal-Multiplexer (CHANNEL_OPEN,
DATA, EOF, CLOSE, WINDOW_ADJUST). Eine logische Sitzung pro
Channel-Instanz.
|-
| <code>SSH::Client</code> || High-Level-SSH-Client: öffnet den
Transport, führt KEX, Hostschlüssel-Prüfung und userauth durch und
verteilt anschließend Kanäle.
|-
| <code>SSH::Transport</code> || Drahtschicht. Banner- und
KEXINIT-Austausch, ChaCha20-Poly1305-Paket-Framing, sendSeq /
recvSeq, Heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH-SFTP-Erweiterungen ===

SFTP v3 (Entwurf draft-ietf-secsh-filexfer-02) ist bewusst
minimal gehalten. OpenSSH bringt einen offenen
Erweiterungsmechanismus mit: der Server listet im
<code>SSH_FXP_VERSION</code>-Reply die Erweiterungsnamen auf, die
er versteht, und der Client ruft sie über
<code>SSH_FXP_EXTENDED(200)</code>-Pakete mit dem
Erweiterungsnamen als erstem String auf. Jede Erweiterung wird
über <code>SSH::SftpClient>>supportsExtension:</code>
feature-detektiert; Aufrufer fallen zurück, wenn der Server sie
nicht ankündigt.

Der Stack nutzt heute vier OpenSSH-Erweiterungen:

* <code>posix-rename@openssh.com</code> — atomares rename-mit-Überschreiben. Wird automatisch von
<code>SftpFilename>>renameTo:</code> aufgegriffen; die
Delete-dann-Rename-Fallback-Variante kommt nur bei Servern zum
Einsatz, die die Erweiterung nicht haben.
* <code>hardlink@openssh.com</code> — Erzeugt einen POSIX-Hardlink. Verfügbar als <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX-
<code>statvfs(3)</code>-typische Dateisystem-Statistik.
Verfügbar als <code>SftpFilename>>fileSystemInfo</code>;
das Ergebnis ist form-kompatibel zu
<code>OperatingSystem getDiskInfoOf:</code>, sodass Aufrufer
lokale und entfernte Pfade einheitlich behandeln können.
Treibt den Menü-Eintrag '''Tools → Filesystem Info...''' an,
der am Anfang dieser Seite beschrieben ist.
* <code>fsync@openssh.com</code> — schreibt den serverseitigen Schreibpuffer eines geöffneten Handles auf Platte. Liegt als
<code>SftpClient>>fsyncHandle:</code> bereit; noch nicht
in eine "Durable-Write"-API auf Filename-Ebene eingebunden.

Die verbleibenden OpenSSH-Erweiterungen
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
werden in der angekündigten Liste erkannt, aber nicht auf
Filename-Ebene gekapselt — es gibt dafür noch keinen
Filename-seitigen Aufrufer.

=== Verbindungs-Pooling ===

Alle <code>SftpFilename</code>-Instanzen, die auf dasselbe Tripel
<code>user@host:port</code> zeigen, teilen sich einen
<code>SSH::Client</code> samt einem <code>SSH::SftpClient</code>.
Der Pool ist klassenseitig und wird von einem einzigen
<code>ConnectionPoolMutex</code> bewacht:

* '''Lazy-Aufbau''' — TCP + KEX + userauth + SFTP-INIT laufen erst beim ersten SFTP-Aufruf, nicht in <code>forUrl:</code>.
* '''Serialisierung pro Host''' — SFTP-Anfragen an einen bestimmten Host werden durch einen <code>RecursionLock</code> mit dem Namen <code>SFTP/<user@host:port></code> serialisiert (sichtbar im SemaphoreMonitor).
* '''Idle-Verdrängung''' — ein Pool-Eintrag, der länger als
<code>idleEvictionSeconds</code> ungenutzt liegt, wird beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet.
* '''Automatischer Reconnect''' — ein Fehler auf Transportebene (Broken Pipe, EOF, MNU auf nil-Socket) verdrängt den Pool-Eintrag, öffnet einen frischen Client und wiederholt die Anfrage '''einmal'''. Anwendungsfehler aus SFTP-STATUS-Antworten werden sofort durchgereicht.

== Ausblick ==

Geplant, aber noch nicht umgesetzt:

* '''Multi-Channel-Parallelität pro Host''' — aktuell bedeutet eine TCP- plus eine SFTP-Verbindung pro Host, dass N gleichzeitige Anfragen serialisieren. Pipelining über mehrere SshClients im Pool (bevorzugt) oder ein transport-seitiger Reader-Prozess, der eingehende Pakete in Pro-Kanal-Postfächer demultiplext, würde es dem Baum-Panel erlauben, weiter aufzulisten, während das Inhalts-Panel eine große Datei liest.
* '''Genaues <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (nur erstes Batch) + CLOSE — drei Roundtrips pro Sondierung; lohnt erst, wenn der SftpClient Anfragen pipelinen kann.
* '''SFTP-v5/v6-Aushandlung''' für erweiterte Attribute und FTP-artige Kanonisierung. (Atomares Überschreibungs-rename ist bereits über die OpenSSH-Erweiterung
<code>posix-rename@openssh.com</code> abgedeckt; siehe
[[#OpenSSH-SFTP-Erweiterungen]].)

= Kommando-Shell =

Lokale Kommando-Shell auf dieser expecco-Maschine. Typische
Anwendungen: lokale Kommandozeile, lokales Hilfsprogramm,
Brücke zwischen entferntem Workflow und lokalem Tool.

Das RemoteAccess-Plugin stellt bereit:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

Keine Zugangsdaten, kein Netzwerk — läuft als der Benutzer des
expecco-Prozesses. Ausgaben gehen in das expecco-Log.

= Telnet =

[[File:Warning.svg|24px|Warnung]] '''Telnet ist ein veraltetes
Protokoll ohne Verschlüsselung.''' Passwörter werden im Klartext
über die Leitung übertragen; jeder im Netzpfad kann sie lesen.
Telnet NUR einsetzen, wenn die Gegenstelle keine Alternative
bietet (typisch: alte Industriesteuerungen, Laborgeräte,
eingebettete Messgeräte ohne SSH-Stack). Für alles andere
[[#SSH und SFTP]] verwenden.

Das expecco-Plugin stellt bereit:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (interne Demo)

Das Telnet-Protokoll (RFC 854) ist ein bidirektionaler
8-Bit-Byte-Strom über TCP, mit In-Band-Steuersequenzen für
Terminal-Optionen. Verbindungsaufbau zum Ziel-Host:Port; nach
optionalem In-Band-Login können beide Seiten Daten senden.

= Siehe auch =

* [[SSH Client|SSH::Client]] — die SSH-Schicht (exec, TTY, Agent-Weiterleitung, ProxyJump).
* [[FileBrowserV2]] — die Haupt-UI dieses Stacks.
* [[ClaudeCode plugin|Claude Code]] — nutzt denselben SSH-Stack als HTTPS-Transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Netz]]
[[Category:SSH]]

Remote Access/en

2026-05-26T10:33:01Z

Sv: Fold bullet continuation lines onto a single physical line so MediaWiki keeps them inside <li>

{{Languages|Remote Access/en|label=English}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation in <code>exept:libcrypt/ssh</code>; no external dependency on OpenSSL or libssh. Use this for anything that touches credentials or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine. Used for local-tool integration and for the local end of a remote workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No encryption, passwords on the wire in clear. Use only when the target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code> subclass that lets the rest of ST/X treat a remote SFTP path the same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a remote host.
* '''SFTP Connect...''' — points this browser tab at a remote filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of the filesystem holding the currently displayed directory. Works uniformly for local paths and SFTP paths; for SFTP it requires the server to advertise the <code>statvfs@openssh.com</code> extension (every modern OpenSSH does). Sizes are reported in IEC binary units (MiB, GiB, TiB) — the largest unit yielding a value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB'' rather than ''10240 GiB''.

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code> (or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only; gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file unencrypted (agent-only mode ignores the passphrase, since the OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to '''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally; a ST/X on the Windows side does not. Bridging needs a helper like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's walkback plus each waiter's, formatted as plain text. Use when a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed (e.g. legacy PEM, encrypted-without-agent) — the file is skipped, others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime), no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On servers that advertise <code>posix-rename@openssh.com</code> (every modern OpenSSH does), overwrite is atomic; on the rare server that does not, the receiver is emulated as delete-then-rename and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always returns <code>#isDirectory</code> (the accurate answer would cost three round-trips per directory icon, which made the original tree expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link. Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe, EOF, MNU on nil socket) evicts the dead pool entry, opens a fresh client, retries the request '''once'''. Application-level SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP + one SFTP channel per host means N concurrent requests serialise. Pipelining over multiple SshClients in the pool (preferred), or a transport-level reader process demultiplexing to per-channel inboxes, would let the tree pane keep listing while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (first batch only) + CLOSE — three RTTs per probe; needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style canonicalisation. (Atomic-overwrite rename is already handled via the OpenSSH <code>posix-rename@openssh.com</code> extension; see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]

Remote Access

2026-05-26T10:33:00Z

Sv: Fold bullet continuation lines onto a single physical line so MediaWiki keeps them inside <li>

{{Languages|Remote Access|label=Deutsch}}

'''Fernzugriff''' bezeichnet die Möglichkeit, einen entfernten
Rechner oder ein entferntes Netzwerk aus diesem expecco-Image heraus
zu bedienen — Shells zu öffnen, Befehle abzusetzen, Dateien zu
verschieben oder ein Testgerät anzusteuern. Drei Protokoll-Familien
sind unterstützt, in absteigender Empfehlungsreihenfolge:

* '''SSH und SFTP''' (empfohlen) — verschlüsselte Shell und sichere Dateiübertragung über einen SSH-2-Tunnel. Reine Smalltalk-Implementierung in <code>exept:libcrypt/ssh</code>; keine externe Abhängigkeit von OpenSSL oder libssh. Für alles mit Zugangsdaten oder sensiblen Nutzdaten.
* '''Lokale Kommando-Shell''' — fork + exec auf der lokalen Maschine. Für die Anbindung lokaler Werkzeuge und für die lokale Seite eines hybriden Workflows.
* '''Telnet''' (veraltet) — Klartext-Terminalsitzung. Keine Verschlüsselung, Passwörter im Klartext auf der Leitung. Nur einsetzen, wenn die Gegenstelle keine Alternative bietet.

= SSH und SFTP =

Der SSH-Stack deckt das vollständige SSH-2-Protokoll ab
(RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) inklusive der
chacha20-poly1305-Transportchiffrierung von OpenSSH sowie das
SFTP-v3-Subsystem (draft-ietf-secsh-filexfer-02). Zwei Schichten:

* '''<code>SSH::Client</code>''' — programmatischer SSH-Zugriff (entferntes <code>exec</code>, TTY-Shell, Agent-Weiterleitung, ProxyJump-Bastion).
* '''<code>SSH::SftpFilename</code>''' — eine
<code>Filename</code>-Unterklasse, die es dem restlichen ST/X
erlaubt, einen entfernten SFTP-Pfad zu behandeln wie eine lokale
Datei.

Die folgenden Abschnitte sind nutzeraufgaben-zuerst aufgebaut:
zuerst das, was der Anwender sieht und tut, darunter die
expecco-Bibliotheks-Anbindung, ganz unten Implementierungsdetails
für Interessierte.

== Aus dem FileBrowserV2 ==

Im Adress-Dropdown eine <code>sftp://</code>-URL einfügen. Der
Browser-Tab füllt sich wie bei einem lokalen Pfad.
Baum-Ausklappen, Spaltensortierung (Name / Größe / mtime),
Vorschau und Doppelklick zum Öffnen im Editor verhalten sich
normal. Der erste Klick auf einen Host dauert ~200–500 ms
(TCP + KEX + Auth); folgende Klicks nutzen die gepoolte
Verbindung weiter.

URL-Syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

Fehlt <code>user</code>, wird der lokale Login-Name verwendet, Port
ist standardmäßig 22, Pfad standardmäßig <code>/</code>.

Das Menü '''Tools''' im FileBrowserV2 bietet vier Aktionen — die
drei SSH-spezifischen sind nur bei geladener SSH-Bibliothek
sichtbar:

* '''Generate SSH Key Pair...''' — öffnet den Schlüsselerzeugungs-Dialog, siehe [[#Einen SSH-Schlüssel erzeugen]] unten.
* '''SSH Connect...''' — öffnet ein interaktives VT100-Terminal zu einem entfernten Host.
* '''SFTP Connect...''' — navigiert diesen Browser-Tab über SFTP auf ein entferntes Dateisystem.
* '''Filesystem Info...''' — zeigt Größe, freien Platz und Belegung des Dateisystems, das das aktuell angezeigte Verzeichnis enthält. Funktioniert einheitlich für lokale und SFTP-Pfade; bei SFTP setzt der Aufruf voraus, daß der Server die Erweiterung
<code>statvfs@openssh.com</code> ankündigt (jedes moderne OpenSSH
tut das). Größen werden in IEC-Binäreinheiten ausgegeben (MiB,
GiB, TiB) — gewählt wird die größte Einheit, die einen Wert ≥ 1
liefert, damit ein TB-großes Volume als ''X TiB'' statt
''10240 GiB'' erscheint.

== Aus expecco-Aktionen ==

Das Expecco-RemoteAccess-Plugin
([[Expecco::RemoteAccessImportPlugin]]) stellt folgende Testaktionen
in der expecco-Aktionspalette bereit:

* '''CmdShell - Open SSH Remote Connection''' — öffnet eine SSH-Sitzung über das plattformeigene <code>ssh</code>-Binary (PuTTYs <code>plink</code> unter Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — dasselbe, jedoch mit expliziter Public-Key-Authentifizierung.

Voraussetzung: ein eingerichtetes Schlüsselpaar (privater
Schlüssel auf dieser Maschine, öffentlicher Teil in der
<code>~/.ssh/authorized_keys</code> des Zielhosts). Schlüssel
erzeugen entweder über den Dialog unten oder über
<code>ssh-keygen</code>.

Das Plugin fügt zusätzlich eine Settings-Seite hinzu:
'''Extras → Settings → Plugins → Remote Access — SSH Keys''' mit
einer einzelnen Schaltfläche '''Generate SSH Key Pair...''', die
denselben Dialog öffnet.

== Einen SSH-Schlüssel erzeugen ==

=== Der Dialog (FileBrowserV2 / Settings-Seite) ===

Der Dialog fragt alle Parameter in einem Formular ab:

* '''Comment''' — wird in den erzeugten Schlüssel eingebettet (Voreinstellung <code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — schreibt
<code>~/.ssh/id_ed25519_stx</code> (oder wohin man will) samt
zugehöriger <code>.pub</code>-Datei daneben.
** ''Save to disk AND load into ssh-agent'' — schreibt die Datei UND übergibt den Schlüssel dem laufenden ssh-agent.
** ''Load into ssh-agent only'' — der Schlüssel lebt nur im Speicher des Agents; nach Agent-Neustart ist er verloren.
* '''Private key file''' — vollständiger Pfad; ausgegraut im Agent-only-Modus.
* '''Passphrase / Confirm''' — leer lässt die On-Disk-Datei unverschlüsselt (Agent-only-Modus ignoriert die Passphrase, da das OpenSSH-Agent-Wire-Protokoll nur den entschlüsselten Schlüssel transportiert).

Bei '''Generate''' wird die Public-Key-Zeile (dieselbe
<code>ssh-ed25519 AAAA... comment</code>-Zeichenfolge, die
ssh-keygen ausgibt) in die System-Zwischenablage kopiert — zum
direkten Einfügen in die <code>~/.ssh/authorized_keys</code> des
Zielhosts.

=== Aus einem Workspace ===

Für Headless-Deployments, Sandbox-Builds oder Skripte stellt
<code>SSH::Client</code> einen reinen Smalltalk-Schlüsselgenerator
bereit, dessen Ausgabe bit-kompatibel zu
<code>ssh-keygen -t ed25519</code> ist:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Passphrase-verschlüsselt auf Platte speichern"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ UND in den laufenden Agent laden"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Public-Key-Zeile zum Einfügen in authorized_keys ausgeben"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Die so erzeugten Schlüssel sind mit den OpenSSH-Werkzeugen voll
interoperabel (<code>ssh-keygen -y -f ...</code> rekonstruiert den
öffentlichen Schlüssel, <code>ssh-keygen -p -f ...</code> ändert
die Passphrase usw.).

=== Mit den Shell-Werkzeugen ===

Der klassische Weg funktioniert weiterhin:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== ssh-agent vorbereiten ==

Der Weg über den Agent ist dem direkten Lesen von Schlüsseldateien
deutlich vorzuziehen: er hält verschlüsselte private Schlüssel
einmal pro Sitzung entsperrt und kann Identitäten verwalten
(hardware-tokengestützte Schlüssel, KeePassXC-Einträge), die ST/X
nie direkt sehen soll.

ST/X erkennt den Agent-Pfad automatisch, sobald
<code>$SSH_AUTH_SOCK</code> '''zum Zeitpunkt des Starts von stx'''
in der Prozessumgebung gesetzt ist. Eine spätere Zuweisung aus
einem Workspace nützt nichts.

=== Linux / macOS ===

Die meisten Desktop-Distributionen starten einen Agent automatisch
beim Login (gnome-keyring unter GNOME, ssh-agent.service unter
systemd, KWallet unter KDE). Prüfen im Terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh oder ähnlich
ssh-add -l # listet geladene Identitäten
ssh-add ~/.ssh/id_ed25519 # eigene laden, falls nicht da
</pre>

Läuft gar kein Agent, dieses Snippet in die Shell-rc-Datei
aufnehmen:

<pre>
# ~/.bashrc oder ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X muss aus einer Shell gestartet werden, die diese rc bereits
gelesen hat — ein Desktop-Launcher aus dem Dateimanager erbt die
Variable nicht. Empfehlung: ein kleines Wrapper-Skript unter
<code>~/.local/bin/</code>, das die rc sourcet und dann stx
startet.

Die Settings-Seite ('''Extras → Settings → Plugins → Remote
Access — SSH Keys''') zeigt an, ob das laufende Image einen
Agent sieht.

==== Permanente Einrichtung via systemd ====

Für einen wirklich sitzungsübergreifenden Agent (überlebt Desktop-
Abmeldung, kommt beim nächsten Login wieder hoch) die bei den
meisten Distros mit dem Paket <code>openssh-clients</code>
ausgelieferte Per-User-systemd-Unit aktivieren:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Anschließend <code>SSH_AUTH_SOCK</code> in der Shell-rc auf den
User-Service-Socket zeigen lassen (ersetzt das
<code>eval $(ssh-agent -s)</code>-Snippet oben):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Schlüssel automatisch beim ersten Einsatz laden ====

Um den manuellen <code>ssh-add</code>-Schritt zu sparen, kann
OpenSSH Schlüssel beim ersten Bedarf selbst in den Agent laden.
In <code>~/.ssh/config</code> eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

Die erste SSH-Verbindung fragt dann einmal nach der Passphrase und
übergibt den entsperrten Schlüssel an den Agent; weitere
Verbindungen nutzen die gespeicherte Identität ohne Prompt.

=== Windows ===

Windows 10+ bringt das native OpenSSH inklusive Agent-Dienst mit.
Einmalige Einrichtung:

# '''Dienste''' (<code>services.msc</code>) als Administrator öffnen.
# '''OpenSSH Authentication Agent''' suchen, Starttyp auf '''Automatisch''' setzen, '''Starten''' anklicken.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Prüfen: <code>ssh-add -l</code>.

Der Windows-OpenSSH-Agent lauscht auf einer Named Pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), nicht auf einem
Unix-Socket. ST/X unterstützt beide Transporte, jedoch setzt das
Windows-ssh-add <code>SSH_AUTH_SOCK</code> '''nicht''' selbst.
Daher einmalig systemweit setzen:

# {{Key|Win}} drücken → "Umgebungsvariablen" → „Systemumgebungs- variablen bearbeiten".
# '''Umgebungsvariablen''' → unter '''Benutzervariablen''', '''Neu''' klicken.
# Name: <code>SSH_AUTH_SOCK</code>
# Wert: <code>\\.\pipe\openssh-ssh-agent</code>
# Ab- und wieder anmelden (oder stx neu starten), damit die neue Umgebung übernommen wird.

==== PowerShell-Schnelleinrichtung ====

Derselbe Aufbau aus einer '''Administrator-PowerShell''' heraus,
z.B. für Skripte oder unbeaufsichtigte Bereitstellung:

<pre>
# Agent jetzt und bei jedem Neustart starten (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# SSH_AUTH_SOCK dauerhaft für den Benutzer setzen (übersteht Reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Schlüssel laden (fragt nach Passphrase, falls die Datei verschlüsselt ist).
ssh-add $HOME\.ssh\id_ed25519
</pre>

Für einen einmaligen Agent-Start ohne dauerhafte Aktivierung
(z.B. Einzelsitzung) die <code>Set-Service</code>-Zeile weglassen
und nur <code>Start-Service ssh-agent</code> ausführen. Die
env-var-Zeile lässt sich ebenfalls weglassen, wenn
<code>SSH_AUTH_SOCK</code> nur in der aktuellen Shell gebraucht
wird — dann statt der <code>[Environment]</code>-Variante
<code>$env:SSH_AUTH_SOCK = '...'</code> verwenden.

Auf stark abgespeckten Windows-Installationen ist der
ssh-agent-Dienst eventuell nicht vorhanden. Einmalig nachrüsten
über '''Einstellungen → Apps → Optionale Features → OpenSSH-
Client'''.

Alternative Agenten:

* '''PuTTY pageant''' — eigenes Protokoll; von ST/X's
<code>SSH::Agent</code> '''nicht''' unterstützt. Schlüssel zu
OpenSSH migrieren.
* '''Git für Windows ssh-agent''' — funktioniert;
<code>SSH_AUTH_SOCK</code> auf den dort veröffentlichten Socket
zeigen lassen.
* '''WSL 2''' — ein ST/X innerhalb der WSL sieht den WSL-eigenen Agent normal; ein ST/X auf der Windows-Seite nicht. Eine Brücke per <code>npiperelay</code> + <code>socat</code> ist möglich.

Prüfung über die Settings-Seite
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
die Anzeige dort meldet, ob das laufende Image den Agent sieht.

==== Schlüssel automatisch beim ersten Einsatz laden ====

Windows-OpenSSH speichert agent-geladene Schlüssel '''nicht'''
über Agent-Neustarts hinweg. Um nicht nach jedem Reboot manuell
<code>ssh-add</code> aufrufen zu müssen, dieselbe Lazy-Load-
Konfiguration in <code>%USERPROFILE%\.ssh\config</code>
eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH lädt den Schlüssel dann beim ersten Einsatz in den Agent
(fragt einmal nach der Passphrase) und nutzt ihn für die übrige
Sitzung weiter.

== Konfiguration ==

Alle Stellschrauben sind klassenseitig auf
<code>SSH::SftpFilename</code> erreichbar:

{| class="wikitable"
! Accessor !! Voreinstellung !! Steuert
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 Min) || Wie lange
eine gepoolte Verbindung im Leerlauf liegen darf, bevor sie beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet wird.
Liegt knapp unter dem typischen
<code>ClientAliveInterval × ClientAliveCountMax</code> des sshd,
damit wir uns recyceln, bevor der Server uns mit TCP-RESET
trennt. <code>nil</code> setzt auf Voreinstellung zurück.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Maximales Alter (s)
eines gecachten STAT, bevor <code>#ensureAttrs</code> neu am
Server fragt. Eltern-listDir stempelt ohnehin frische Attribute
auf alle Kinder, daher zahlt das Navigieren im offenen
Verzeichnis das TTL nicht. <code>0</code> schaltet den Cache
ab.
|-
| <code>#closeAllConnections</code> || (Aktion) || Reißt jede
gepoolte Verbindung ab. Nützlich nach einem bekannt schlechten
Netzereignis, vor einem bewussten Identitätswechsel oder zum
sauberen Image-Shutdown.
|}

== Diagnose ==

=== SemaphoreMonitor ===

<code>SemaphoreMonitor</code> über das Untermenü „Status" des
Launchers öffnen. Der pro-Host-SFTP-Mutex erscheint als
<code>SFTP/<user@host:port></code>, der pool-weite Mutex als
<code>SFTP/pool</code>. Per Rechtsklick:

* '''Copy Waiters Stack to Clipboard''' — schreibt den Walkback des letzten Eigners samt aller Waiter als Text in die Zwischenablage. Unverzichtbar, wenn ein Prozess in
<code>readWait</code> innerhalb von
<code>withSftpClientDo:</code> klemmt.
* '''Copy List to Clipboard''' — die ganze Tabelle, ideal für eine E-Mail-Diagnose.
* '''Detect Deadlocks''' — DFS über den Wait-for-Graph, meldet Zyklen.

=== Logger ===

Interessante Ereignisse werden über <code>Logger</code> geloggt:

* <code>warning:</code> bei automatischem Reconnect nach toter Verbindung.
* <code>warning:</code> bei Idle-Verdrängung eines Pool-Eintrags.
* <code>warning:</code> wenn eine SSH-Schlüsseldatei nicht geparst werden konnte — die Datei wird übersprungen.

== Einschränkungen ==

* '''Nur SFTP v3.''' Kein SETSTAT (kein entferntes chmod / chown / utime), kein SSH_FXP_READLINK exponiert (<code>#isSymbolicLink</code> liefert immer <code>false</code>,
<code>#linkInfo</code> die normale stat-Info). Einige
SFTPv5+-Annehmlichkeiten werden dennoch über OpenSSH-spezifische
SSH_FXP_EXTENDED-Aufrufe nutzbar — siehe
[[#OpenSSH-SFTP-Erweiterungen]] weiter unten.
* '''Serialisierung pro Host.''' Zwei gleichzeitige Operationen am selben Host stehen am Host-Mutex an. Siehe [[#Ausblick]].
* '''<code>#renameTo:</code>-Fallback hat ein TOCTOU-Fenster.''' Bei Servern, die <code>posix-rename@openssh.com</code> ankündigen (jedes moderne OpenSSH tut das), ist das Überschreiben atomar. Beim seltenen Server, der das nicht tut, wird auf Delete-dann-Rename ausgewichen und ein anderer Prozess kann sich dazwischenschieben.
* '''<code>#isNonEmptyDirectory</code> ist eine Heuristik.''' Liefert immer <code>#isDirectory</code> (die genaue Antwort würde drei Roundtrips pro Verzeichnis-Symbol kosten, was das ursprüngliche Baum-Ausklappen unerträglich gebremst hatte).

== Implementierungsdetails ==

Für Leser, die die Architektur verstehen wollen. Fünf Klassen,
von oben nach unten:

{| class="wikitable"
! Klasse !! Aufgabe
|-
| <code>SSH::SftpFilename</code> || Filename-Unterklasse, die
öffentliche API. Bildet <code>sftp://...</code>-URLs auf
entfernte Dateien ab und stellt <code>directoryContents</code>,
<code>readingFileDo:</code>, <code>renameTo:</code> usw. bereit.
|-
| <code>SSH::SftpClient</code> || SFTP-v3-Protokoll
(Request/Response-Codec, listDir, stat, open, read, write, mkdir).
Wird von SftpFilename angesteuert.
|-
| <code>SSH::Channel</code> || SSH-Kanal-Multiplexer (CHANNEL_OPEN,
DATA, EOF, CLOSE, WINDOW_ADJUST). Eine logische Sitzung pro
Channel-Instanz.
|-
| <code>SSH::Client</code> || High-Level-SSH-Client: öffnet den
Transport, führt KEX, Hostschlüssel-Prüfung und userauth durch und
verteilt anschließend Kanäle.
|-
| <code>SSH::Transport</code> || Drahtschicht. Banner- und
KEXINIT-Austausch, ChaCha20-Poly1305-Paket-Framing, sendSeq /
recvSeq, Heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH-SFTP-Erweiterungen ===

SFTP v3 (Entwurf draft-ietf-secsh-filexfer-02) ist bewusst
minimal gehalten. OpenSSH bringt einen offenen
Erweiterungsmechanismus mit: der Server listet im
<code>SSH_FXP_VERSION</code>-Reply die Erweiterungsnamen auf, die
er versteht, und der Client ruft sie über
<code>SSH_FXP_EXTENDED(200)</code>-Pakete mit dem
Erweiterungsnamen als erstem String auf. Jede Erweiterung wird
über <code>SSH::SftpClient>>supportsExtension:</code>
feature-detektiert; Aufrufer fallen zurück, wenn der Server sie
nicht ankündigt.

Der Stack nutzt heute vier OpenSSH-Erweiterungen:

* <code>posix-rename@openssh.com</code> — atomares rename-mit-Überschreiben. Wird automatisch von
<code>SftpFilename>>renameTo:</code> aufgegriffen; die
Delete-dann-Rename-Fallback-Variante kommt nur bei Servern zum
Einsatz, die die Erweiterung nicht haben.
* <code>hardlink@openssh.com</code> — Erzeugt einen POSIX-Hardlink. Verfügbar als <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX-
<code>statvfs(3)</code>-typische Dateisystem-Statistik.
Verfügbar als <code>SftpFilename>>fileSystemInfo</code>;
das Ergebnis ist form-kompatibel zu
<code>OperatingSystem getDiskInfoOf:</code>, sodass Aufrufer
lokale und entfernte Pfade einheitlich behandeln können.
Treibt den Menü-Eintrag '''Tools → Filesystem Info...''' an,
der am Anfang dieser Seite beschrieben ist.
* <code>fsync@openssh.com</code> — schreibt den serverseitigen Schreibpuffer eines geöffneten Handles auf Platte. Liegt als
<code>SftpClient>>fsyncHandle:</code> bereit; noch nicht
in eine "Durable-Write"-API auf Filename-Ebene eingebunden.

Die verbleibenden OpenSSH-Erweiterungen
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
werden in der angekündigten Liste erkannt, aber nicht auf
Filename-Ebene gekapselt — es gibt dafür noch keinen
Filename-seitigen Aufrufer.

=== Verbindungs-Pooling ===

Alle <code>SftpFilename</code>-Instanzen, die auf dasselbe Tripel
<code>user@host:port</code> zeigen, teilen sich einen
<code>SSH::Client</code> samt einem <code>SSH::SftpClient</code>.
Der Pool ist klassenseitig und wird von einem einzigen
<code>ConnectionPoolMutex</code> bewacht:

* '''Lazy-Aufbau''' — TCP + KEX + userauth + SFTP-INIT laufen erst beim ersten SFTP-Aufruf, nicht in <code>forUrl:</code>.
* '''Serialisierung pro Host''' — SFTP-Anfragen an einen bestimmten Host werden durch einen <code>RecursionLock</code> mit dem Namen <code>SFTP/<user@host:port></code> serialisiert (sichtbar im SemaphoreMonitor).
* '''Idle-Verdrängung''' — ein Pool-Eintrag, der länger als
<code>idleEvictionSeconds</code> ungenutzt liegt, wird beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet.
* '''Automatischer Reconnect''' — ein Fehler auf Transportebene (Broken Pipe, EOF, MNU auf nil-Socket) verdrängt den Pool-Eintrag, öffnet einen frischen Client und wiederholt die Anfrage '''einmal'''. Anwendungsfehler aus SFTP-STATUS-Antworten werden sofort durchgereicht.

== Ausblick ==

Geplant, aber noch nicht umgesetzt:

* '''Multi-Channel-Parallelität pro Host''' — aktuell bedeutet eine TCP- plus eine SFTP-Verbindung pro Host, dass N gleichzeitige Anfragen serialisieren. Pipelining über mehrere SshClients im Pool (bevorzugt) oder ein transport-seitiger Reader-Prozess, der eingehende Pakete in Pro-Kanal-Postfächer demultiplext, würde es dem Baum-Panel erlauben, weiter aufzulisten, während das Inhalts-Panel eine große Datei liest.
* '''Genaues <code>#isNonEmptyDirectory</code>''' via OPEN_DIR + READ_DIR (nur erstes Batch) + CLOSE — drei Roundtrips pro Sondierung; lohnt erst, wenn der SftpClient Anfragen pipelinen kann.
* '''SFTP-v5/v6-Aushandlung''' für erweiterte Attribute und FTP-artige Kanonisierung. (Atomares Überschreibungs-rename ist bereits über die OpenSSH-Erweiterung
<code>posix-rename@openssh.com</code> abgedeckt; siehe
[[#OpenSSH-SFTP-Erweiterungen]].)

= Kommando-Shell =

Lokale Kommando-Shell auf dieser expecco-Maschine. Typische
Anwendungen: lokale Kommandozeile, lokales Hilfsprogramm,
Brücke zwischen entferntem Workflow und lokalem Tool.

Das RemoteAccess-Plugin stellt bereit:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

Keine Zugangsdaten, kein Netzwerk — läuft als der Benutzer des
expecco-Prozesses. Ausgaben gehen in das expecco-Log.

= Telnet =

[[File:Warning.svg|24px|Warnung]] '''Telnet ist ein veraltetes
Protokoll ohne Verschlüsselung.''' Passwörter werden im Klartext
über die Leitung übertragen; jeder im Netzpfad kann sie lesen.
Telnet NUR einsetzen, wenn die Gegenstelle keine Alternative
bietet (typisch: alte Industriesteuerungen, Laborgeräte,
eingebettete Messgeräte ohne SSH-Stack). Für alles andere
[[#SSH und SFTP]] verwenden.

Das expecco-Plugin stellt bereit:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (interne Demo)

Das Telnet-Protokoll (RFC 854) ist ein bidirektionaler
8-Bit-Byte-Strom über TCP, mit In-Band-Steuersequenzen für
Terminal-Optionen. Verbindungsaufbau zum Ziel-Host:Port; nach
optionalem In-Band-Login können beide Seiten Daten senden.

= Siehe auch =

* [[SSH Client|SSH::Client]] — die SSH-Schicht (exec, TTY, Agent-Weiterleitung, ProxyJump).
* [[FileBrowserV2]] — die Haupt-UI dieses Stacks.
* [[ClaudeCode plugin|Claude Code]] — nutzt denselben SSH-Stack als HTTPS-Transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Netz]]
[[Category:SSH]]

Remote Access/en

2026-05-26T10:29:04Z

Sv: Remove 2-space continuation-line indent (was triggering MediaWiki <pre>)

{{Languages|Remote Access/en|label=English}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure
file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation
in <code>exept:libcrypt/ssh</code>; no external dependency on
OpenSSL or libssh. Use this for anything that touches credentials
or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine.
Used for local-tool integration and for the local end of a remote
workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No
encryption, passwords on the wire in clear. Use only when the
target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code>
subclass that lets the rest of ST/X treat a remote SFTP path the
same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation
dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a
remote host.
* '''SFTP Connect...''' — points this browser tab at a remote
filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of
the filesystem holding the currently displayed directory. Works
uniformly for local paths and SFTP paths; for SFTP it requires
the server to advertise the <code>statvfs@openssh.com</code>
extension (every modern OpenSSH does). Sizes are reported in
IEC binary units (MiB, GiB, TiB) — the largest unit yielding a
value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB''
rather than ''10240 GiB''.

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session
via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same
but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code>
(or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and
also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only;
gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file
unencrypted (agent-only mode ignores the passphrase, since the
OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to
'''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by
ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally;
a ST/X on the Windows side does not. Bridging needs a helper
like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's
walkback plus each waiter's, formatted as plain text. Use when
a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an
email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports
cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed
(e.g. legacy PEM, encrypted-without-agent) — the file is skipped,
others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime),
no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the
same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On
servers that advertise <code>posix-rename@openssh.com</code> (every
modern OpenSSH does), overwrite is atomic; on the rare server
that does not, the receiver is emulated as delete-then-rename
and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always
returns <code>#isDirectory</code> (the accurate answer would cost
three round-trips per directory icon, which made the original tree
expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic
rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link.
Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer
to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens
on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host
are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe,
EOF, MNU on nil socket) evicts the dead pool entry, opens a
fresh client, retries the request '''once'''. Application-level
SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP +
one SFTP channel per host means N concurrent requests
serialise. Pipelining over multiple SshClients in the pool
(preferred), or a transport-level reader process demultiplexing
to per-channel inboxes, would let the tree pane keep listing
while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR
+ READ_DIR (first batch only) + CLOSE — three RTTs per probe;
needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style
canonicalisation. (Atomic-overwrite rename is already handled
via the OpenSSH <code>posix-rename@openssh.com</code> extension;
see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent
forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of
this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack
for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]

Remote Access

2026-05-26T10:29:02Z

Sv: Remove 2-space continuation-line indent (was triggering MediaWiki <pre>)

{{Languages|Remote Access|label=Deutsch}}

'''Fernzugriff''' bezeichnet die Möglichkeit, einen entfernten
Rechner oder ein entferntes Netzwerk aus diesem expecco-Image heraus
zu bedienen — Shells zu öffnen, Befehle abzusetzen, Dateien zu
verschieben oder ein Testgerät anzusteuern. Drei Protokoll-Familien
sind unterstützt, in absteigender Empfehlungsreihenfolge:

* '''SSH und SFTP''' (empfohlen) — verschlüsselte Shell und sichere
Dateiübertragung über einen SSH-2-Tunnel. Reine
Smalltalk-Implementierung in <code>exept:libcrypt/ssh</code>;
keine externe Abhängigkeit von OpenSSL oder libssh. Für alles
mit Zugangsdaten oder sensiblen Nutzdaten.
* '''Lokale Kommando-Shell''' — fork + exec auf der lokalen
Maschine. Für die Anbindung lokaler Werkzeuge und für die
lokale Seite eines hybriden Workflows.
* '''Telnet''' (veraltet) — Klartext-Terminalsitzung. Keine
Verschlüsselung, Passwörter im Klartext auf der Leitung. Nur
einsetzen, wenn die Gegenstelle keine Alternative bietet.

= SSH und SFTP =

Der SSH-Stack deckt das vollständige SSH-2-Protokoll ab
(RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) inklusive der
chacha20-poly1305-Transportchiffrierung von OpenSSH sowie das
SFTP-v3-Subsystem (draft-ietf-secsh-filexfer-02). Zwei Schichten:

* '''<code>SSH::Client</code>''' — programmatischer SSH-Zugriff
(entferntes <code>exec</code>, TTY-Shell, Agent-Weiterleitung,
ProxyJump-Bastion).
* '''<code>SSH::SftpFilename</code>''' — eine
<code>Filename</code>-Unterklasse, die es dem restlichen ST/X
erlaubt, einen entfernten SFTP-Pfad zu behandeln wie eine lokale
Datei.

Die folgenden Abschnitte sind nutzeraufgaben-zuerst aufgebaut:
zuerst das, was der Anwender sieht und tut, darunter die
expecco-Bibliotheks-Anbindung, ganz unten Implementierungsdetails
für Interessierte.

== Aus dem FileBrowserV2 ==

Im Adress-Dropdown eine <code>sftp://</code>-URL einfügen. Der
Browser-Tab füllt sich wie bei einem lokalen Pfad.
Baum-Ausklappen, Spaltensortierung (Name / Größe / mtime),
Vorschau und Doppelklick zum Öffnen im Editor verhalten sich
normal. Der erste Klick auf einen Host dauert ~200–500 ms
(TCP + KEX + Auth); folgende Klicks nutzen die gepoolte
Verbindung weiter.

URL-Syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

Fehlt <code>user</code>, wird der lokale Login-Name verwendet, Port
ist standardmäßig 22, Pfad standardmäßig <code>/</code>.

Das Menü '''Tools''' im FileBrowserV2 bietet vier Aktionen — die
drei SSH-spezifischen sind nur bei geladener SSH-Bibliothek
sichtbar:

* '''Generate SSH Key Pair...''' — öffnet den
Schlüsselerzeugungs-Dialog, siehe
[[#Einen SSH-Schlüssel erzeugen]] unten.
* '''SSH Connect...''' — öffnet ein interaktives VT100-Terminal
zu einem entfernten Host.
* '''SFTP Connect...''' — navigiert diesen Browser-Tab über SFTP
auf ein entferntes Dateisystem.
* '''Filesystem Info...''' — zeigt Größe, freien Platz und Belegung
des Dateisystems, das das aktuell angezeigte Verzeichnis enthält.
Funktioniert einheitlich für lokale und SFTP-Pfade; bei SFTP
setzt der Aufruf voraus, daß der Server die Erweiterung
<code>statvfs@openssh.com</code> ankündigt (jedes moderne OpenSSH
tut das). Größen werden in IEC-Binäreinheiten ausgegeben (MiB,
GiB, TiB) — gewählt wird die größte Einheit, die einen Wert ≥ 1
liefert, damit ein TB-großes Volume als ''X TiB'' statt
''10240 GiB'' erscheint.

== Aus expecco-Aktionen ==

Das Expecco-RemoteAccess-Plugin
([[Expecco::RemoteAccessImportPlugin]]) stellt folgende Testaktionen
in der expecco-Aktionspalette bereit:

* '''CmdShell - Open SSH Remote Connection''' — öffnet eine
SSH-Sitzung über das plattformeigene <code>ssh</code>-Binary
(PuTTYs <code>plink</code> unter Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' —
dasselbe, jedoch mit expliziter Public-Key-Authentifizierung.

Voraussetzung: ein eingerichtetes Schlüsselpaar (privater
Schlüssel auf dieser Maschine, öffentlicher Teil in der
<code>~/.ssh/authorized_keys</code> des Zielhosts). Schlüssel
erzeugen entweder über den Dialog unten oder über
<code>ssh-keygen</code>.

Das Plugin fügt zusätzlich eine Settings-Seite hinzu:
'''Extras → Settings → Plugins → Remote Access — SSH Keys''' mit
einer einzelnen Schaltfläche '''Generate SSH Key Pair...''', die
denselben Dialog öffnet.

== Einen SSH-Schlüssel erzeugen ==

=== Der Dialog (FileBrowserV2 / Settings-Seite) ===

Der Dialog fragt alle Parameter in einem Formular ab:

* '''Comment''' — wird in den erzeugten Schlüssel eingebettet
(Voreinstellung <code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — schreibt
<code>~/.ssh/id_ed25519_stx</code> (oder wohin man will) samt
zugehöriger <code>.pub</code>-Datei daneben.
** ''Save to disk AND load into ssh-agent'' — schreibt die Datei
UND übergibt den Schlüssel dem laufenden ssh-agent.
** ''Load into ssh-agent only'' — der Schlüssel lebt nur im
Speicher des Agents; nach Agent-Neustart ist er verloren.
* '''Private key file''' — vollständiger Pfad; ausgegraut im
Agent-only-Modus.
* '''Passphrase / Confirm''' — leer lässt die On-Disk-Datei
unverschlüsselt (Agent-only-Modus ignoriert die Passphrase, da
das OpenSSH-Agent-Wire-Protokoll nur den entschlüsselten
Schlüssel transportiert).

Bei '''Generate''' wird die Public-Key-Zeile (dieselbe
<code>ssh-ed25519 AAAA... comment</code>-Zeichenfolge, die
ssh-keygen ausgibt) in die System-Zwischenablage kopiert — zum
direkten Einfügen in die <code>~/.ssh/authorized_keys</code> des
Zielhosts.

=== Aus einem Workspace ===

Für Headless-Deployments, Sandbox-Builds oder Skripte stellt
<code>SSH::Client</code> einen reinen Smalltalk-Schlüsselgenerator
bereit, dessen Ausgabe bit-kompatibel zu
<code>ssh-keygen -t ed25519</code> ist:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Passphrase-verschlüsselt auf Platte speichern"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ UND in den laufenden Agent laden"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Public-Key-Zeile zum Einfügen in authorized_keys ausgeben"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Die so erzeugten Schlüssel sind mit den OpenSSH-Werkzeugen voll
interoperabel (<code>ssh-keygen -y -f ...</code> rekonstruiert den
öffentlichen Schlüssel, <code>ssh-keygen -p -f ...</code> ändert
die Passphrase usw.).

=== Mit den Shell-Werkzeugen ===

Der klassische Weg funktioniert weiterhin:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== ssh-agent vorbereiten ==

Der Weg über den Agent ist dem direkten Lesen von Schlüsseldateien
deutlich vorzuziehen: er hält verschlüsselte private Schlüssel
einmal pro Sitzung entsperrt und kann Identitäten verwalten
(hardware-tokengestützte Schlüssel, KeePassXC-Einträge), die ST/X
nie direkt sehen soll.

ST/X erkennt den Agent-Pfad automatisch, sobald
<code>$SSH_AUTH_SOCK</code> '''zum Zeitpunkt des Starts von stx'''
in der Prozessumgebung gesetzt ist. Eine spätere Zuweisung aus
einem Workspace nützt nichts.

=== Linux / macOS ===

Die meisten Desktop-Distributionen starten einen Agent automatisch
beim Login (gnome-keyring unter GNOME, ssh-agent.service unter
systemd, KWallet unter KDE). Prüfen im Terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh oder ähnlich
ssh-add -l # listet geladene Identitäten
ssh-add ~/.ssh/id_ed25519 # eigene laden, falls nicht da
</pre>

Läuft gar kein Agent, dieses Snippet in die Shell-rc-Datei
aufnehmen:

<pre>
# ~/.bashrc oder ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X muss aus einer Shell gestartet werden, die diese rc bereits
gelesen hat — ein Desktop-Launcher aus dem Dateimanager erbt die
Variable nicht. Empfehlung: ein kleines Wrapper-Skript unter
<code>~/.local/bin/</code>, das die rc sourcet und dann stx
startet.

Die Settings-Seite ('''Extras → Settings → Plugins → Remote
Access — SSH Keys''') zeigt an, ob das laufende Image einen
Agent sieht.

==== Permanente Einrichtung via systemd ====

Für einen wirklich sitzungsübergreifenden Agent (überlebt Desktop-
Abmeldung, kommt beim nächsten Login wieder hoch) die bei den
meisten Distros mit dem Paket <code>openssh-clients</code>
ausgelieferte Per-User-systemd-Unit aktivieren:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Anschließend <code>SSH_AUTH_SOCK</code> in der Shell-rc auf den
User-Service-Socket zeigen lassen (ersetzt das
<code>eval $(ssh-agent -s)</code>-Snippet oben):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Schlüssel automatisch beim ersten Einsatz laden ====

Um den manuellen <code>ssh-add</code>-Schritt zu sparen, kann
OpenSSH Schlüssel beim ersten Bedarf selbst in den Agent laden.
In <code>~/.ssh/config</code> eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

Die erste SSH-Verbindung fragt dann einmal nach der Passphrase und
übergibt den entsperrten Schlüssel an den Agent; weitere
Verbindungen nutzen die gespeicherte Identität ohne Prompt.

=== Windows ===

Windows 10+ bringt das native OpenSSH inklusive Agent-Dienst mit.
Einmalige Einrichtung:

# '''Dienste''' (<code>services.msc</code>) als Administrator öffnen.
# '''OpenSSH Authentication Agent''' suchen, Starttyp auf
'''Automatisch''' setzen, '''Starten''' anklicken.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Prüfen: <code>ssh-add -l</code>.

Der Windows-OpenSSH-Agent lauscht auf einer Named Pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), nicht auf einem
Unix-Socket. ST/X unterstützt beide Transporte, jedoch setzt das
Windows-ssh-add <code>SSH_AUTH_SOCK</code> '''nicht''' selbst.
Daher einmalig systemweit setzen:

# {{Key|Win}} drücken → "Umgebungsvariablen" → „Systemumgebungs-
variablen bearbeiten".
# '''Umgebungsvariablen''' → unter '''Benutzervariablen''',
'''Neu''' klicken.
# Name: <code>SSH_AUTH_SOCK</code>
# Wert: <code>\\.\pipe\openssh-ssh-agent</code>
# Ab- und wieder anmelden (oder stx neu starten), damit die neue
Umgebung übernommen wird.

==== PowerShell-Schnelleinrichtung ====

Derselbe Aufbau aus einer '''Administrator-PowerShell''' heraus,
z.B. für Skripte oder unbeaufsichtigte Bereitstellung:

<pre>
# Agent jetzt und bei jedem Neustart starten (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# SSH_AUTH_SOCK dauerhaft für den Benutzer setzen (übersteht Reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Schlüssel laden (fragt nach Passphrase, falls die Datei verschlüsselt ist).
ssh-add $HOME\.ssh\id_ed25519
</pre>

Für einen einmaligen Agent-Start ohne dauerhafte Aktivierung
(z.B. Einzelsitzung) die <code>Set-Service</code>-Zeile weglassen
und nur <code>Start-Service ssh-agent</code> ausführen. Die
env-var-Zeile lässt sich ebenfalls weglassen, wenn
<code>SSH_AUTH_SOCK</code> nur in der aktuellen Shell gebraucht
wird — dann statt der <code>[Environment]</code>-Variante
<code>$env:SSH_AUTH_SOCK = '...'</code> verwenden.

Auf stark abgespeckten Windows-Installationen ist der
ssh-agent-Dienst eventuell nicht vorhanden. Einmalig nachrüsten
über '''Einstellungen → Apps → Optionale Features → OpenSSH-
Client'''.

Alternative Agenten:

* '''PuTTY pageant''' — eigenes Protokoll; von ST/X's
<code>SSH::Agent</code> '''nicht''' unterstützt. Schlüssel zu
OpenSSH migrieren.
* '''Git für Windows ssh-agent''' — funktioniert;
<code>SSH_AUTH_SOCK</code> auf den dort veröffentlichten Socket
zeigen lassen.
* '''WSL 2''' — ein ST/X innerhalb der WSL sieht den WSL-eigenen
Agent normal; ein ST/X auf der Windows-Seite nicht. Eine
Brücke per <code>npiperelay</code> + <code>socat</code> ist
möglich.

Prüfung über die Settings-Seite
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
die Anzeige dort meldet, ob das laufende Image den Agent sieht.

==== Schlüssel automatisch beim ersten Einsatz laden ====

Windows-OpenSSH speichert agent-geladene Schlüssel '''nicht'''
über Agent-Neustarts hinweg. Um nicht nach jedem Reboot manuell
<code>ssh-add</code> aufrufen zu müssen, dieselbe Lazy-Load-
Konfiguration in <code>%USERPROFILE%\.ssh\config</code>
eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH lädt den Schlüssel dann beim ersten Einsatz in den Agent
(fragt einmal nach der Passphrase) und nutzt ihn für die übrige
Sitzung weiter.

== Konfiguration ==

Alle Stellschrauben sind klassenseitig auf
<code>SSH::SftpFilename</code> erreichbar:

{| class="wikitable"
! Accessor !! Voreinstellung !! Steuert
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 Min) || Wie lange
eine gepoolte Verbindung im Leerlauf liegen darf, bevor sie beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet wird.
Liegt knapp unter dem typischen
<code>ClientAliveInterval × ClientAliveCountMax</code> des sshd,
damit wir uns recyceln, bevor der Server uns mit TCP-RESET
trennt. <code>nil</code> setzt auf Voreinstellung zurück.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Maximales Alter (s)
eines gecachten STAT, bevor <code>#ensureAttrs</code> neu am
Server fragt. Eltern-listDir stempelt ohnehin frische Attribute
auf alle Kinder, daher zahlt das Navigieren im offenen
Verzeichnis das TTL nicht. <code>0</code> schaltet den Cache
ab.
|-
| <code>#closeAllConnections</code> || (Aktion) || Reißt jede
gepoolte Verbindung ab. Nützlich nach einem bekannt schlechten
Netzereignis, vor einem bewussten Identitätswechsel oder zum
sauberen Image-Shutdown.
|}

== Diagnose ==

=== SemaphoreMonitor ===

<code>SemaphoreMonitor</code> über das Untermenü „Status" des
Launchers öffnen. Der pro-Host-SFTP-Mutex erscheint als
<code>SFTP/<user@host:port></code>, der pool-weite Mutex als
<code>SFTP/pool</code>. Per Rechtsklick:

* '''Copy Waiters Stack to Clipboard''' — schreibt den Walkback
des letzten Eigners samt aller Waiter als Text in die
Zwischenablage. Unverzichtbar, wenn ein Prozess in
<code>readWait</code> innerhalb von
<code>withSftpClientDo:</code> klemmt.
* '''Copy List to Clipboard''' — die ganze Tabelle, ideal für eine
E-Mail-Diagnose.
* '''Detect Deadlocks''' — DFS über den Wait-for-Graph, meldet
Zyklen.

=== Logger ===

Interessante Ereignisse werden über <code>Logger</code> geloggt:

* <code>warning:</code> bei automatischem Reconnect nach toter
Verbindung.
* <code>warning:</code> bei Idle-Verdrängung eines Pool-Eintrags.
* <code>warning:</code> wenn eine SSH-Schlüsseldatei nicht
geparst werden konnte — die Datei wird übersprungen.

== Einschränkungen ==

* '''Nur SFTP v3.''' Kein SETSTAT (kein entferntes
chmod / chown / utime), kein SSH_FXP_READLINK exponiert
(<code>#isSymbolicLink</code> liefert immer <code>false</code>,
<code>#linkInfo</code> die normale stat-Info). Einige
SFTPv5+-Annehmlichkeiten werden dennoch über OpenSSH-spezifische
SSH_FXP_EXTENDED-Aufrufe nutzbar — siehe
[[#OpenSSH-SFTP-Erweiterungen]] weiter unten.
* '''Serialisierung pro Host.''' Zwei gleichzeitige Operationen
am selben Host stehen am Host-Mutex an. Siehe [[#Ausblick]].
* '''<code>#renameTo:</code>-Fallback hat ein TOCTOU-Fenster.'''
Bei Servern, die <code>posix-rename@openssh.com</code> ankündigen
(jedes moderne OpenSSH tut das), ist das Überschreiben atomar.
Beim seltenen Server, der das nicht tut, wird auf
Delete-dann-Rename ausgewichen und ein anderer Prozess kann sich
dazwischenschieben.
* '''<code>#isNonEmptyDirectory</code> ist eine Heuristik.'''
Liefert immer <code>#isDirectory</code> (die genaue Antwort
würde drei Roundtrips pro Verzeichnis-Symbol kosten, was das
ursprüngliche Baum-Ausklappen unerträglich gebremst hatte).

== Implementierungsdetails ==

Für Leser, die die Architektur verstehen wollen. Fünf Klassen,
von oben nach unten:

{| class="wikitable"
! Klasse !! Aufgabe
|-
| <code>SSH::SftpFilename</code> || Filename-Unterklasse, die
öffentliche API. Bildet <code>sftp://...</code>-URLs auf
entfernte Dateien ab und stellt <code>directoryContents</code>,
<code>readingFileDo:</code>, <code>renameTo:</code> usw. bereit.
|-
| <code>SSH::SftpClient</code> || SFTP-v3-Protokoll
(Request/Response-Codec, listDir, stat, open, read, write, mkdir).
Wird von SftpFilename angesteuert.
|-
| <code>SSH::Channel</code> || SSH-Kanal-Multiplexer (CHANNEL_OPEN,
DATA, EOF, CLOSE, WINDOW_ADJUST). Eine logische Sitzung pro
Channel-Instanz.
|-
| <code>SSH::Client</code> || High-Level-SSH-Client: öffnet den
Transport, führt KEX, Hostschlüssel-Prüfung und userauth durch und
verteilt anschließend Kanäle.
|-
| <code>SSH::Transport</code> || Drahtschicht. Banner- und
KEXINIT-Austausch, ChaCha20-Poly1305-Paket-Framing, sendSeq /
recvSeq, Heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH-SFTP-Erweiterungen ===

SFTP v3 (Entwurf draft-ietf-secsh-filexfer-02) ist bewusst
minimal gehalten. OpenSSH bringt einen offenen
Erweiterungsmechanismus mit: der Server listet im
<code>SSH_FXP_VERSION</code>-Reply die Erweiterungsnamen auf, die
er versteht, und der Client ruft sie über
<code>SSH_FXP_EXTENDED(200)</code>-Pakete mit dem
Erweiterungsnamen als erstem String auf. Jede Erweiterung wird
über <code>SSH::SftpClient>>supportsExtension:</code>
feature-detektiert; Aufrufer fallen zurück, wenn der Server sie
nicht ankündigt.

Der Stack nutzt heute vier OpenSSH-Erweiterungen:

* <code>posix-rename@openssh.com</code> — atomares
rename-mit-Überschreiben. Wird automatisch von
<code>SftpFilename>>renameTo:</code> aufgegriffen; die
Delete-dann-Rename-Fallback-Variante kommt nur bei Servern zum
Einsatz, die die Erweiterung nicht haben.
* <code>hardlink@openssh.com</code> — Erzeugt einen POSIX-Hardlink.
Verfügbar als <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX-
<code>statvfs(3)</code>-typische Dateisystem-Statistik.
Verfügbar als <code>SftpFilename>>fileSystemInfo</code>;
das Ergebnis ist form-kompatibel zu
<code>OperatingSystem getDiskInfoOf:</code>, sodass Aufrufer
lokale und entfernte Pfade einheitlich behandeln können.
Treibt den Menü-Eintrag '''Tools → Filesystem Info...''' an,
der am Anfang dieser Seite beschrieben ist.
* <code>fsync@openssh.com</code> — schreibt den
serverseitigen Schreibpuffer eines geöffneten Handles auf
Platte. Liegt als
<code>SftpClient>>fsyncHandle:</code> bereit; noch nicht
in eine "Durable-Write"-API auf Filename-Ebene eingebunden.

Die verbleibenden OpenSSH-Erweiterungen
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
werden in der angekündigten Liste erkannt, aber nicht auf
Filename-Ebene gekapselt — es gibt dafür noch keinen
Filename-seitigen Aufrufer.

=== Verbindungs-Pooling ===

Alle <code>SftpFilename</code>-Instanzen, die auf dasselbe Tripel
<code>user@host:port</code> zeigen, teilen sich einen
<code>SSH::Client</code> samt einem <code>SSH::SftpClient</code>.
Der Pool ist klassenseitig und wird von einem einzigen
<code>ConnectionPoolMutex</code> bewacht:

* '''Lazy-Aufbau''' — TCP + KEX + userauth + SFTP-INIT laufen
erst beim ersten SFTP-Aufruf, nicht in <code>forUrl:</code>.
* '''Serialisierung pro Host''' — SFTP-Anfragen an einen
bestimmten Host werden durch einen <code>RecursionLock</code>
mit dem Namen <code>SFTP/<user@host:port></code>
serialisiert (sichtbar im SemaphoreMonitor).
* '''Idle-Verdrängung''' — ein Pool-Eintrag, der länger als
<code>idleEvictionSeconds</code> ungenutzt liegt, wird beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet.
* '''Automatischer Reconnect''' — ein Fehler auf Transportebene
(Broken Pipe, EOF, MNU auf nil-Socket) verdrängt den
Pool-Eintrag, öffnet einen frischen Client und wiederholt die
Anfrage '''einmal'''. Anwendungsfehler aus
SFTP-STATUS-Antworten werden sofort durchgereicht.

== Ausblick ==

Geplant, aber noch nicht umgesetzt:

* '''Multi-Channel-Parallelität pro Host''' — aktuell bedeutet
eine TCP- plus eine SFTP-Verbindung pro Host, dass N
gleichzeitige Anfragen serialisieren. Pipelining über mehrere
SshClients im Pool (bevorzugt) oder ein transport-seitiger
Reader-Prozess, der eingehende Pakete in
Pro-Kanal-Postfächer demultiplext, würde es dem Baum-Panel
erlauben, weiter aufzulisten, während das Inhalts-Panel eine
große Datei liest.
* '''Genaues <code>#isNonEmptyDirectory</code>''' via OPEN_DIR
+ READ_DIR (nur erstes Batch) + CLOSE — drei Roundtrips pro
Sondierung; lohnt erst, wenn der SftpClient Anfragen pipelinen
kann.
* '''SFTP-v5/v6-Aushandlung''' für erweiterte Attribute und
FTP-artige Kanonisierung. (Atomares Überschreibungs-rename
ist bereits über die OpenSSH-Erweiterung
<code>posix-rename@openssh.com</code> abgedeckt; siehe
[[#OpenSSH-SFTP-Erweiterungen]].)

= Kommando-Shell =

Lokale Kommando-Shell auf dieser expecco-Maschine. Typische
Anwendungen: lokale Kommandozeile, lokales Hilfsprogramm,
Brücke zwischen entferntem Workflow und lokalem Tool.

Das RemoteAccess-Plugin stellt bereit:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

Keine Zugangsdaten, kein Netzwerk — läuft als der Benutzer des
expecco-Prozesses. Ausgaben gehen in das expecco-Log.

= Telnet =

[[File:Warning.svg|24px|Warnung]] '''Telnet ist ein veraltetes
Protokoll ohne Verschlüsselung.''' Passwörter werden im Klartext
über die Leitung übertragen; jeder im Netzpfad kann sie lesen.
Telnet NUR einsetzen, wenn die Gegenstelle keine Alternative
bietet (typisch: alte Industriesteuerungen, Laborgeräte,
eingebettete Messgeräte ohne SSH-Stack). Für alles andere
[[#SSH und SFTP]] verwenden.

Das expecco-Plugin stellt bereit:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (interne Demo)

Das Telnet-Protokoll (RFC 854) ist ein bidirektionaler
8-Bit-Byte-Strom über TCP, mit In-Band-Steuersequenzen für
Terminal-Optionen. Verbindungsaufbau zum Ziel-Host:Port; nach
optionalem In-Band-Login können beide Seiten Daten senden.

= Siehe auch =

* [[SSH Client|SSH::Client]] — die SSH-Schicht (exec, TTY,
Agent-Weiterleitung, ProxyJump).
* [[FileBrowserV2]] — die Haupt-UI dieses Stacks.
* [[ClaudeCode plugin|Claude Code]] — nutzt denselben SSH-Stack
als HTTPS-Transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Netz]]
[[Category:SSH]]

Vorlage:Languages

2026-05-26T10:22:02Z

Sv: Add /en to the enumerated language subpages (for non-English master pages)

{{nmbox
| header = '''[[Project:Language policy|{{Languages/Title|{{SUBPAGENAME}}}}]]'''
| text =
'''[[{{{1|:{{NAMESPACE}}:{{BASEPAGENAME}}}}}|{{{label|English}}}]]''' {{Languages/Lang|af|{{{1|}}}|
}}{{Languages/Lang|ar|{{{1|}}}|
}}{{Languages/Lang|ast|{{{1|}}}|
}}{{Languages/Lang|az|{{{1|}}}|
}}{{Languages/Lang|bcc|{{{1|}}}|
}}{{Languages/Lang|bg|{{{1|}}}|
}}{{Languages/Lang|br|{{{1|}}}|
}}{{Languages/Lang|bn|{{{1|}}}|
}}{{Languages/Lang|bs|{{{1|}}}|
}}{{Languages/Lang|ca|{{{1|}}}|
}}{{Languages/Lang|cs|{{{1|}}}|
}}{{Languages/Lang|da|{{{1|}}}|
}}{{Languages/Lang|de|{{{1|}}}|
}}{{Languages/Lang|diq|{{{1|}}}|
}}{{Languages/Lang|el|{{{1|}}}|
}}{{Languages/Lang|en|{{{1|}}}|
}}{{Languages/Lang|eo|{{{1|}}}|
}}{{Languages/Lang|es|{{{1|}}}|
}}{{Languages/Lang|fa|{{{1|}}}|
}}{{Languages/Lang|fi|{{{1|}}}|
}}{{Languages/Lang|fr|{{{1|}}}|
}}{{Languages/Lang|gl|{{{1|}}}|
}}{{Languages/Lang|gu|{{{1|}}}|
}}{{Languages/Lang|he|{{{1|}}}|
}}{{Languages/Lang|hi|{{{1|}}}|
}}{{Languages/Lang|hu|{{{1|}}}|
}}{{Languages/Lang|hy|{{{1|}}}|
}}{{Languages/Lang|id|{{{1|}}}|
}}{{Languages/Lang|io|{{{1|}}}|
}}{{Languages/Lang|it|{{{1|}}}|
}}{{Languages/Lang|ja|{{{1|}}}|
}}{{Languages/Lang|ka|{{{1|}}}|
}}{{Languages/Lang|kk|{{{1|}}}|
}}{{Languages/Lang|km|{{{1|}}}|
}}{{Languages/Lang|ko|{{{1|}}}|
}}{{Languages/Lang|ksh|{{{1|}}}|
}}{{Languages/Lang|kw|{{{1|}}}|
}}{{Languages/Lang|la|{{{1|}}}|
}}{{Languages/Lang|min|{{{1|}}}|
}}{{Languages/Lang|mk|{{{1|}}}|
}}{{Languages/Lang|ml|{{{1|}}}|
}}{{Languages/Lang|mr|{{{1|}}}|
}}{{Languages/Lang|ms|{{{1|}}}|
}}{{Languages/Lang|nl|{{{1|}}}|
}}{{Languages/Lang|no|{{{1|}}}|
}}{{Languages/Lang|oc|{{{1|}}}|
}}{{Languages/Lang|or|{{{1|}}}|
}}{{Languages/Lang|pl|{{{1|}}}|
}}{{Languages/Lang|pt|{{{1|}}}|
}}{{Languages/Lang|pt-br|{{{1|}}}|
}}{{Languages/Lang|ro|{{{1|}}}|
}}{{Languages/Lang|ru|{{{1|}}}|
}}{{Languages/Lang|si|{{{1|}}}|
}}{{Languages/Lang|sk|{{{1|}}}|
}}{{Languages/Lang|sl|{{{1|}}}|
}}{{Languages/Lang|sq|{{{1|}}}|
}}{{Languages/Lang|sr|{{{1|}}}|
}}{{Languages/Lang|sv|{{{1|}}}|
}}{{Languages/Lang|ta|{{{1|}}}|
}}{{Languages/Lang|th|{{{1|}}}|
}}{{Languages/Lang|tr|{{{1|}}}|
}}{{Languages/Lang|uk|{{{1|}}}|
}}{{Languages/Lang|vi|{{{1|}}}|
}}{{Languages/Lang|yi|{{{1|}}}|
}}{{Languages/Lang|yue|{{{1|}}}|
}}{{Languages/Lang|zh|{{{1|}}}|
}}{{Languages/Lang|zh-hans|{{{1|}}}|
}}{{Languages/Lang|zh-hant|{{{1|}}}|
}}{{Languages/Lang|zh-tw|{{{1|}}}}}|
}}<includeonly>{{#if:{{Languages/Lang|af|{{{1|}}}|
}}{{Languages/Lang|ar|{{{1|}}}|
}}{{Languages/Lang|ast|{{{1|}}}|
}}{{Languages/Lang|az|{{{1|}}}|
}}{{Languages/Lang|bcc|{{{1|}}}|
}}{{Languages/Lang|bg|{{{1|}}}|
}}{{Languages/Lang|br|{{{1|}}}|
}}{{Languages/Lang|bn|{{{1|}}}|
}}{{Languages/Lang|bs|{{{1|}}}|
}}{{Languages/Lang|ca|{{{1|}}}|
}}{{Languages/Lang|cs|{{{1|}}}|
}}{{Languages/Lang|da|{{{1|}}}|
}}{{Languages/Lang|de|{{{1|}}}|
}}{{Languages/Lang|diq|{{{1|}}}|
}}{{Languages/Lang|el|{{{1|}}}|
}}{{Languages/Lang|en|{{{1|}}}|
}}{{Languages/Lang|eo|{{{1|}}}|
}}{{Languages/Lang|es|{{{1|}}}|
}}{{Languages/Lang|fa|{{{1|}}}|
}}{{Languages/Lang|fi|{{{1|}}}|
}}{{Languages/Lang|fr|{{{1|}}}|
}}{{Languages/Lang|gl|{{{1|}}}|
}}{{Languages/Lang|gu|{{{1|}}}|
}}{{Languages/Lang|he|{{{1|}}}|
}}{{Languages/Lang|hi|{{{1|}}}|
}}{{Languages/Lang|hu|{{{1|}}}|
}}{{Languages/Lang|hy|{{{1|}}}|
}}{{Languages/Lang|id|{{{1|}}}|
}}{{Languages/Lang|io|{{{1|}}}|
}}{{Languages/Lang|it|{{{1|}}}|
}}{{Languages/Lang|ja|{{{1|}}}|
}}{{Languages/Lang|ka|{{{1|}}}|
}}{{Languages/Lang|kk|{{{1|}}}|
}}{{Languages/Lang|km|{{{1|}}}|
}}{{Languages/Lang|ko|{{{1|}}}|
}}{{Languages/Lang|ksh|{{{1|}}}|
}}{{Languages/Lang|kw|{{{1|}}}|
}}{{Languages/Lang|la|{{{1|}}}|
}}{{Languages/Lang|min|{{{1|}}}|
}}{{Languages/Lang|mk|{{{1|}}}|
}}{{Languages/Lang|ml|{{{1|}}}|
}}{{Languages/Lang|mr|{{{1|}}}|
}}{{Languages/Lang|ms|{{{1|}}}|
}}{{Languages/Lang|nl|{{{1|}}}|
}}{{Languages/Lang|no|{{{1|}}}|
}}{{Languages/Lang|oc|{{{1|}}}|
}}{{Languages/Lang|or|{{{1|}}}|
}}{{Languages/Lang|pl|{{{1|}}}|
}}{{Languages/Lang|pt|{{{1|}}}|
}}{{Languages/Lang|pt-br|{{{1|}}}|
}}{{Languages/Lang|ro|{{{1|}}}|
}}{{Languages/Lang|ru|{{{1|}}}|
}}{{Languages/Lang|si|{{{1|}}}|
}}{{Languages/Lang|sk|{{{1|}}}|
}}{{Languages/Lang|sl|{{{1|}}}|
}}{{Languages/Lang|sq|{{{1|}}}|
}}{{Languages/Lang|sr|{{{1|}}}|
}}{{Languages/Lang|sv|{{{1|}}}|
}}{{Languages/Lang|ta|{{{1|}}}|
}}{{Languages/Lang|th|{{{1|}}}|
}}{{Languages/Lang|tr|{{{1|}}}|
}}{{Languages/Lang|uk|{{{1|}}}|
}}{{Languages/Lang|vi|{{{1|}}}|
}}{{Languages/Lang|yi|{{{1|}}}|
}}{{Languages/Lang|yue|{{{1|}}}|
}}{{Languages/Lang|zh|{{{1|}}}|
}}{{Languages/Lang|zh-hans|{{{1|}}}|
}}{{Languages/Lang|zh-hant|{{{1|}}}|
}}{{Languages/Lang|zh-tw|{{{1|}}}}}
||[[Category:Languages pages without translations]]}}</includeonly><noinclude>
{{documentation}}
[[Category:Exclude in print]]
</noinclude>

Remote Access/en

2026-05-26T10:20:13Z

Sv: Use label= for the bold language link (after Template:Languages patch)

{{Languages|Remote Access/en|label=English}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure
file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation
in <code>exept:libcrypt/ssh</code>; no external dependency on
OpenSSL or libssh. Use this for anything that touches credentials
or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine.
Used for local-tool integration and for the local end of a remote
workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No
encryption, passwords on the wire in clear. Use only when the
target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code>
subclass that lets the rest of ST/X treat a remote SFTP path the
same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation
dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a
remote host.
* '''SFTP Connect...''' — points this browser tab at a remote
filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of
the filesystem holding the currently displayed directory. Works
uniformly for local paths and SFTP paths; for SFTP it requires
the server to advertise the <code>statvfs@openssh.com</code>
extension (every modern OpenSSH does). Sizes are reported in
IEC binary units (MiB, GiB, TiB) — the largest unit yielding a
value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB''
rather than ''10240 GiB''.

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session
via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same
but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code>
(or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and
also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only;
gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file
unencrypted (agent-only mode ignores the passphrase, since the
OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to
'''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by
ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally;
a ST/X on the Windows side does not. Bridging needs a helper
like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's
walkback plus each waiter's, formatted as plain text. Use when
a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an
email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports
cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed
(e.g. legacy PEM, encrypted-without-agent) — the file is skipped,
others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime),
no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the
same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On
servers that advertise <code>posix-rename@openssh.com</code> (every
modern OpenSSH does), overwrite is atomic; on the rare server
that does not, the receiver is emulated as delete-then-rename
and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always
returns <code>#isDirectory</code> (the accurate answer would cost
three round-trips per directory icon, which made the original tree
expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic
rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link.
Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer
to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens
on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host
are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe,
EOF, MNU on nil socket) evicts the dead pool entry, opens a
fresh client, retries the request '''once'''. Application-level
SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP +
one SFTP channel per host means N concurrent requests
serialise. Pipelining over multiple SshClients in the pool
(preferred), or a transport-level reader process demultiplexing
to per-channel inboxes, would let the tree pane keep listing
while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR
+ READ_DIR (first batch only) + CLOSE — three RTTs per probe;
needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style
canonicalisation. (Atomic-overwrite rename is already handled
via the OpenSSH <code>posix-rename@openssh.com</code> extension;
see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent
forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of
this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack
for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]

Remote Access

2026-05-26T10:20:11Z

Sv: Use label= for the bold language link (after Template:Languages patch)

{{Languages|Remote Access|label=Deutsch}}

'''Fernzugriff''' bezeichnet die Möglichkeit, einen entfernten
Rechner oder ein entferntes Netzwerk aus diesem expecco-Image heraus
zu bedienen — Shells zu öffnen, Befehle abzusetzen, Dateien zu
verschieben oder ein Testgerät anzusteuern. Drei Protokoll-Familien
sind unterstützt, in absteigender Empfehlungsreihenfolge:

* '''SSH und SFTP''' (empfohlen) — verschlüsselte Shell und sichere
Dateiübertragung über einen SSH-2-Tunnel. Reine
Smalltalk-Implementierung in <code>exept:libcrypt/ssh</code>;
keine externe Abhängigkeit von OpenSSL oder libssh. Für alles
mit Zugangsdaten oder sensiblen Nutzdaten.
* '''Lokale Kommando-Shell''' — fork + exec auf der lokalen
Maschine. Für die Anbindung lokaler Werkzeuge und für die
lokale Seite eines hybriden Workflows.
* '''Telnet''' (veraltet) — Klartext-Terminalsitzung. Keine
Verschlüsselung, Passwörter im Klartext auf der Leitung. Nur
einsetzen, wenn die Gegenstelle keine Alternative bietet.

= SSH und SFTP =

Der SSH-Stack deckt das vollständige SSH-2-Protokoll ab
(RFC 4251–4254, RFC 5656, RFC 8709, RFC 8731) inklusive der
chacha20-poly1305-Transportchiffrierung von OpenSSH sowie das
SFTP-v3-Subsystem (draft-ietf-secsh-filexfer-02). Zwei Schichten:

* '''<code>SSH::Client</code>''' — programmatischer SSH-Zugriff
(entferntes <code>exec</code>, TTY-Shell, Agent-Weiterleitung,
ProxyJump-Bastion).
* '''<code>SSH::SftpFilename</code>''' — eine
<code>Filename</code>-Unterklasse, die es dem restlichen ST/X
erlaubt, einen entfernten SFTP-Pfad zu behandeln wie eine lokale
Datei.

Die folgenden Abschnitte sind nutzeraufgaben-zuerst aufgebaut:
zuerst das, was der Anwender sieht und tut, darunter die
expecco-Bibliotheks-Anbindung, ganz unten Implementierungsdetails
für Interessierte.

== Aus dem FileBrowserV2 ==

Im Adress-Dropdown eine <code>sftp://</code>-URL einfügen. Der
Browser-Tab füllt sich wie bei einem lokalen Pfad.
Baum-Ausklappen, Spaltensortierung (Name / Größe / mtime),
Vorschau und Doppelklick zum Öffnen im Editor verhalten sich
normal. Der erste Klick auf einen Host dauert ~200–500 ms
(TCP + KEX + Auth); folgende Klicks nutzen die gepoolte
Verbindung weiter.

URL-Syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

Fehlt <code>user</code>, wird der lokale Login-Name verwendet, Port
ist standardmäßig 22, Pfad standardmäßig <code>/</code>.

Das Menü '''Tools''' im FileBrowserV2 bietet vier Aktionen — die
drei SSH-spezifischen sind nur bei geladener SSH-Bibliothek
sichtbar:

* '''Generate SSH Key Pair...''' — öffnet den
Schlüsselerzeugungs-Dialog, siehe
[[#Einen SSH-Schlüssel erzeugen]] unten.
* '''SSH Connect...''' — öffnet ein interaktives VT100-Terminal
zu einem entfernten Host.
* '''SFTP Connect...''' — navigiert diesen Browser-Tab über SFTP
auf ein entferntes Dateisystem.
* '''Filesystem Info...''' — zeigt Größe, freien Platz und Belegung
des Dateisystems, das das aktuell angezeigte Verzeichnis enthält.
Funktioniert einheitlich für lokale und SFTP-Pfade; bei SFTP
setzt der Aufruf voraus, daß der Server die Erweiterung
<code>statvfs@openssh.com</code> ankündigt (jedes moderne OpenSSH
tut das). Größen werden in IEC-Binäreinheiten ausgegeben (MiB,
GiB, TiB) — gewählt wird die größte Einheit, die einen Wert ≥ 1
liefert, damit ein TB-großes Volume als ''X TiB'' statt
''10240 GiB'' erscheint.

== Aus expecco-Aktionen ==

Das Expecco-RemoteAccess-Plugin
([[Expecco::RemoteAccessImportPlugin]]) stellt folgende Testaktionen
in der expecco-Aktionspalette bereit:

* '''CmdShell - Open SSH Remote Connection''' — öffnet eine
SSH-Sitzung über das plattformeigene <code>ssh</code>-Binary
(PuTTYs <code>plink</code> unter Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' —
dasselbe, jedoch mit expliziter Public-Key-Authentifizierung.

Voraussetzung: ein eingerichtetes Schlüsselpaar (privater
Schlüssel auf dieser Maschine, öffentlicher Teil in der
<code>~/.ssh/authorized_keys</code> des Zielhosts). Schlüssel
erzeugen entweder über den Dialog unten oder über
<code>ssh-keygen</code>.

Das Plugin fügt zusätzlich eine Settings-Seite hinzu:
'''Extras → Settings → Plugins → Remote Access — SSH Keys''' mit
einer einzelnen Schaltfläche '''Generate SSH Key Pair...''', die
denselben Dialog öffnet.

== Einen SSH-Schlüssel erzeugen ==

=== Der Dialog (FileBrowserV2 / Settings-Seite) ===

Der Dialog fragt alle Parameter in einem Formular ab:

* '''Comment''' — wird in den erzeugten Schlüssel eingebettet
(Voreinstellung <code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — schreibt
<code>~/.ssh/id_ed25519_stx</code> (oder wohin man will) samt
zugehöriger <code>.pub</code>-Datei daneben.
** ''Save to disk AND load into ssh-agent'' — schreibt die Datei
UND übergibt den Schlüssel dem laufenden ssh-agent.
** ''Load into ssh-agent only'' — der Schlüssel lebt nur im
Speicher des Agents; nach Agent-Neustart ist er verloren.
* '''Private key file''' — vollständiger Pfad; ausgegraut im
Agent-only-Modus.
* '''Passphrase / Confirm''' — leer lässt die On-Disk-Datei
unverschlüsselt (Agent-only-Modus ignoriert die Passphrase, da
das OpenSSH-Agent-Wire-Protokoll nur den entschlüsselten
Schlüssel transportiert).

Bei '''Generate''' wird die Public-Key-Zeile (dieselbe
<code>ssh-ed25519 AAAA... comment</code>-Zeichenfolge, die
ssh-keygen ausgibt) in die System-Zwischenablage kopiert — zum
direkten Einfügen in die <code>~/.ssh/authorized_keys</code> des
Zielhosts.

=== Aus einem Workspace ===

Für Headless-Deployments, Sandbox-Builds oder Skripte stellt
<code>SSH::Client</code> einen reinen Smalltalk-Schlüsselgenerator
bereit, dessen Ausgabe bit-kompatibel zu
<code>ssh-keygen -t ed25519</code> ist:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Passphrase-verschlüsselt auf Platte speichern"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ UND in den laufenden Agent laden"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Public-Key-Zeile zum Einfügen in authorized_keys ausgeben"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Die so erzeugten Schlüssel sind mit den OpenSSH-Werkzeugen voll
interoperabel (<code>ssh-keygen -y -f ...</code> rekonstruiert den
öffentlichen Schlüssel, <code>ssh-keygen -p -f ...</code> ändert
die Passphrase usw.).

=== Mit den Shell-Werkzeugen ===

Der klassische Weg funktioniert weiterhin:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== ssh-agent vorbereiten ==

Der Weg über den Agent ist dem direkten Lesen von Schlüsseldateien
deutlich vorzuziehen: er hält verschlüsselte private Schlüssel
einmal pro Sitzung entsperrt und kann Identitäten verwalten
(hardware-tokengestützte Schlüssel, KeePassXC-Einträge), die ST/X
nie direkt sehen soll.

ST/X erkennt den Agent-Pfad automatisch, sobald
<code>$SSH_AUTH_SOCK</code> '''zum Zeitpunkt des Starts von stx'''
in der Prozessumgebung gesetzt ist. Eine spätere Zuweisung aus
einem Workspace nützt nichts.

=== Linux / macOS ===

Die meisten Desktop-Distributionen starten einen Agent automatisch
beim Login (gnome-keyring unter GNOME, ssh-agent.service unter
systemd, KWallet unter KDE). Prüfen im Terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh oder ähnlich
ssh-add -l # listet geladene Identitäten
ssh-add ~/.ssh/id_ed25519 # eigene laden, falls nicht da
</pre>

Läuft gar kein Agent, dieses Snippet in die Shell-rc-Datei
aufnehmen:

<pre>
# ~/.bashrc oder ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X muss aus einer Shell gestartet werden, die diese rc bereits
gelesen hat — ein Desktop-Launcher aus dem Dateimanager erbt die
Variable nicht. Empfehlung: ein kleines Wrapper-Skript unter
<code>~/.local/bin/</code>, das die rc sourcet und dann stx
startet.

Die Settings-Seite ('''Extras → Settings → Plugins → Remote
Access — SSH Keys''') zeigt an, ob das laufende Image einen
Agent sieht.

==== Permanente Einrichtung via systemd ====

Für einen wirklich sitzungsübergreifenden Agent (überlebt Desktop-
Abmeldung, kommt beim nächsten Login wieder hoch) die bei den
meisten Distros mit dem Paket <code>openssh-clients</code>
ausgelieferte Per-User-systemd-Unit aktivieren:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Anschließend <code>SSH_AUTH_SOCK</code> in der Shell-rc auf den
User-Service-Socket zeigen lassen (ersetzt das
<code>eval $(ssh-agent -s)</code>-Snippet oben):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Schlüssel automatisch beim ersten Einsatz laden ====

Um den manuellen <code>ssh-add</code>-Schritt zu sparen, kann
OpenSSH Schlüssel beim ersten Bedarf selbst in den Agent laden.
In <code>~/.ssh/config</code> eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

Die erste SSH-Verbindung fragt dann einmal nach der Passphrase und
übergibt den entsperrten Schlüssel an den Agent; weitere
Verbindungen nutzen die gespeicherte Identität ohne Prompt.

=== Windows ===

Windows 10+ bringt das native OpenSSH inklusive Agent-Dienst mit.
Einmalige Einrichtung:

# '''Dienste''' (<code>services.msc</code>) als Administrator öffnen.
# '''OpenSSH Authentication Agent''' suchen, Starttyp auf
'''Automatisch''' setzen, '''Starten''' anklicken.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Prüfen: <code>ssh-add -l</code>.

Der Windows-OpenSSH-Agent lauscht auf einer Named Pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), nicht auf einem
Unix-Socket. ST/X unterstützt beide Transporte, jedoch setzt das
Windows-ssh-add <code>SSH_AUTH_SOCK</code> '''nicht''' selbst.
Daher einmalig systemweit setzen:

# {{Key|Win}} drücken → "Umgebungsvariablen" → „Systemumgebungs-
variablen bearbeiten".
# '''Umgebungsvariablen''' → unter '''Benutzervariablen''',
'''Neu''' klicken.
# Name: <code>SSH_AUTH_SOCK</code>
# Wert: <code>\\.\pipe\openssh-ssh-agent</code>
# Ab- und wieder anmelden (oder stx neu starten), damit die neue
Umgebung übernommen wird.

==== PowerShell-Schnelleinrichtung ====

Derselbe Aufbau aus einer '''Administrator-PowerShell''' heraus,
z.B. für Skripte oder unbeaufsichtigte Bereitstellung:

<pre>
# Agent jetzt und bei jedem Neustart starten (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# SSH_AUTH_SOCK dauerhaft für den Benutzer setzen (übersteht Reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Schlüssel laden (fragt nach Passphrase, falls die Datei verschlüsselt ist).
ssh-add $HOME\.ssh\id_ed25519
</pre>

Für einen einmaligen Agent-Start ohne dauerhafte Aktivierung
(z.B. Einzelsitzung) die <code>Set-Service</code>-Zeile weglassen
und nur <code>Start-Service ssh-agent</code> ausführen. Die
env-var-Zeile lässt sich ebenfalls weglassen, wenn
<code>SSH_AUTH_SOCK</code> nur in der aktuellen Shell gebraucht
wird — dann statt der <code>[Environment]</code>-Variante
<code>$env:SSH_AUTH_SOCK = '...'</code> verwenden.

Auf stark abgespeckten Windows-Installationen ist der
ssh-agent-Dienst eventuell nicht vorhanden. Einmalig nachrüsten
über '''Einstellungen → Apps → Optionale Features → OpenSSH-
Client'''.

Alternative Agenten:

* '''PuTTY pageant''' — eigenes Protokoll; von ST/X's
<code>SSH::Agent</code> '''nicht''' unterstützt. Schlüssel zu
OpenSSH migrieren.
* '''Git für Windows ssh-agent''' — funktioniert;
<code>SSH_AUTH_SOCK</code> auf den dort veröffentlichten Socket
zeigen lassen.
* '''WSL 2''' — ein ST/X innerhalb der WSL sieht den WSL-eigenen
Agent normal; ein ST/X auf der Windows-Seite nicht. Eine
Brücke per <code>npiperelay</code> + <code>socat</code> ist
möglich.

Prüfung über die Settings-Seite
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
die Anzeige dort meldet, ob das laufende Image den Agent sieht.

==== Schlüssel automatisch beim ersten Einsatz laden ====

Windows-OpenSSH speichert agent-geladene Schlüssel '''nicht'''
über Agent-Neustarts hinweg. Um nicht nach jedem Reboot manuell
<code>ssh-add</code> aufrufen zu müssen, dieselbe Lazy-Load-
Konfiguration in <code>%USERPROFILE%\.ssh\config</code>
eintragen:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH lädt den Schlüssel dann beim ersten Einsatz in den Agent
(fragt einmal nach der Passphrase) und nutzt ihn für die übrige
Sitzung weiter.

== Konfiguration ==

Alle Stellschrauben sind klassenseitig auf
<code>SSH::SftpFilename</code> erreichbar:

{| class="wikitable"
! Accessor !! Voreinstellung !! Steuert
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 Min) || Wie lange
eine gepoolte Verbindung im Leerlauf liegen darf, bevor sie beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet wird.
Liegt knapp unter dem typischen
<code>ClientAliveInterval × ClientAliveCountMax</code> des sshd,
damit wir uns recyceln, bevor der Server uns mit TCP-RESET
trennt. <code>nil</code> setzt auf Voreinstellung zurück.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Maximales Alter (s)
eines gecachten STAT, bevor <code>#ensureAttrs</code> neu am
Server fragt. Eltern-listDir stempelt ohnehin frische Attribute
auf alle Kinder, daher zahlt das Navigieren im offenen
Verzeichnis das TTL nicht. <code>0</code> schaltet den Cache
ab.
|-
| <code>#closeAllConnections</code> || (Aktion) || Reißt jede
gepoolte Verbindung ab. Nützlich nach einem bekannt schlechten
Netzereignis, vor einem bewussten Identitätswechsel oder zum
sauberen Image-Shutdown.
|}

== Diagnose ==

=== SemaphoreMonitor ===

<code>SemaphoreMonitor</code> über das Untermenü „Status" des
Launchers öffnen. Der pro-Host-SFTP-Mutex erscheint als
<code>SFTP/<user@host:port></code>, der pool-weite Mutex als
<code>SFTP/pool</code>. Per Rechtsklick:

* '''Copy Waiters Stack to Clipboard''' — schreibt den Walkback
des letzten Eigners samt aller Waiter als Text in die
Zwischenablage. Unverzichtbar, wenn ein Prozess in
<code>readWait</code> innerhalb von
<code>withSftpClientDo:</code> klemmt.
* '''Copy List to Clipboard''' — die ganze Tabelle, ideal für eine
E-Mail-Diagnose.
* '''Detect Deadlocks''' — DFS über den Wait-for-Graph, meldet
Zyklen.

=== Logger ===

Interessante Ereignisse werden über <code>Logger</code> geloggt:

* <code>warning:</code> bei automatischem Reconnect nach toter
Verbindung.
* <code>warning:</code> bei Idle-Verdrängung eines Pool-Eintrags.
* <code>warning:</code> wenn eine SSH-Schlüsseldatei nicht
geparst werden konnte — die Datei wird übersprungen.

== Einschränkungen ==

* '''Nur SFTP v3.''' Kein SETSTAT (kein entferntes
chmod / chown / utime), kein SSH_FXP_READLINK exponiert
(<code>#isSymbolicLink</code> liefert immer <code>false</code>,
<code>#linkInfo</code> die normale stat-Info). Einige
SFTPv5+-Annehmlichkeiten werden dennoch über OpenSSH-spezifische
SSH_FXP_EXTENDED-Aufrufe nutzbar — siehe
[[#OpenSSH-SFTP-Erweiterungen]] weiter unten.
* '''Serialisierung pro Host.''' Zwei gleichzeitige Operationen
am selben Host stehen am Host-Mutex an. Siehe [[#Ausblick]].
* '''<code>#renameTo:</code>-Fallback hat ein TOCTOU-Fenster.'''
Bei Servern, die <code>posix-rename@openssh.com</code> ankündigen
(jedes moderne OpenSSH tut das), ist das Überschreiben atomar.
Beim seltenen Server, der das nicht tut, wird auf
Delete-dann-Rename ausgewichen und ein anderer Prozess kann sich
dazwischenschieben.
* '''<code>#isNonEmptyDirectory</code> ist eine Heuristik.'''
Liefert immer <code>#isDirectory</code> (die genaue Antwort
würde drei Roundtrips pro Verzeichnis-Symbol kosten, was das
ursprüngliche Baum-Ausklappen unerträglich gebremst hatte).

== Implementierungsdetails ==

Für Leser, die die Architektur verstehen wollen. Fünf Klassen,
von oben nach unten:

{| class="wikitable"
! Klasse !! Aufgabe
|-
| <code>SSH::SftpFilename</code> || Filename-Unterklasse, die
öffentliche API. Bildet <code>sftp://...</code>-URLs auf
entfernte Dateien ab und stellt <code>directoryContents</code>,
<code>readingFileDo:</code>, <code>renameTo:</code> usw. bereit.
|-
| <code>SSH::SftpClient</code> || SFTP-v3-Protokoll
(Request/Response-Codec, listDir, stat, open, read, write, mkdir).
Wird von SftpFilename angesteuert.
|-
| <code>SSH::Channel</code> || SSH-Kanal-Multiplexer (CHANNEL_OPEN,
DATA, EOF, CLOSE, WINDOW_ADJUST). Eine logische Sitzung pro
Channel-Instanz.
|-
| <code>SSH::Client</code> || High-Level-SSH-Client: öffnet den
Transport, führt KEX, Hostschlüssel-Prüfung und userauth durch und
verteilt anschließend Kanäle.
|-
| <code>SSH::Transport</code> || Drahtschicht. Banner- und
KEXINIT-Austausch, ChaCha20-Poly1305-Paket-Framing, sendSeq /
recvSeq, Heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH-SFTP-Erweiterungen ===

SFTP v3 (Entwurf draft-ietf-secsh-filexfer-02) ist bewusst
minimal gehalten. OpenSSH bringt einen offenen
Erweiterungsmechanismus mit: der Server listet im
<code>SSH_FXP_VERSION</code>-Reply die Erweiterungsnamen auf, die
er versteht, und der Client ruft sie über
<code>SSH_FXP_EXTENDED(200)</code>-Pakete mit dem
Erweiterungsnamen als erstem String auf. Jede Erweiterung wird
über <code>SSH::SftpClient>>supportsExtension:</code>
feature-detektiert; Aufrufer fallen zurück, wenn der Server sie
nicht ankündigt.

Der Stack nutzt heute vier OpenSSH-Erweiterungen:

* <code>posix-rename@openssh.com</code> — atomares
rename-mit-Überschreiben. Wird automatisch von
<code>SftpFilename>>renameTo:</code> aufgegriffen; die
Delete-dann-Rename-Fallback-Variante kommt nur bei Servern zum
Einsatz, die die Erweiterung nicht haben.
* <code>hardlink@openssh.com</code> — Erzeugt einen POSIX-Hardlink.
Verfügbar als <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX-
<code>statvfs(3)</code>-typische Dateisystem-Statistik.
Verfügbar als <code>SftpFilename>>fileSystemInfo</code>;
das Ergebnis ist form-kompatibel zu
<code>OperatingSystem getDiskInfoOf:</code>, sodass Aufrufer
lokale und entfernte Pfade einheitlich behandeln können.
Treibt den Menü-Eintrag '''Tools → Filesystem Info...''' an,
der am Anfang dieser Seite beschrieben ist.
* <code>fsync@openssh.com</code> — schreibt den
serverseitigen Schreibpuffer eines geöffneten Handles auf
Platte. Liegt als
<code>SftpClient>>fsyncHandle:</code> bereit; noch nicht
in eine "Durable-Write"-API auf Filename-Ebene eingebunden.

Die verbleibenden OpenSSH-Erweiterungen
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
werden in der angekündigten Liste erkannt, aber nicht auf
Filename-Ebene gekapselt — es gibt dafür noch keinen
Filename-seitigen Aufrufer.

=== Verbindungs-Pooling ===

Alle <code>SftpFilename</code>-Instanzen, die auf dasselbe Tripel
<code>user@host:port</code> zeigen, teilen sich einen
<code>SSH::Client</code> samt einem <code>SSH::SftpClient</code>.
Der Pool ist klassenseitig und wird von einem einzigen
<code>ConnectionPoolMutex</code> bewacht:

* '''Lazy-Aufbau''' — TCP + KEX + userauth + SFTP-INIT laufen
erst beim ersten SFTP-Aufruf, nicht in <code>forUrl:</code>.
* '''Serialisierung pro Host''' — SFTP-Anfragen an einen
bestimmten Host werden durch einen <code>RecursionLock</code>
mit dem Namen <code>SFTP/<user@host:port></code>
serialisiert (sichtbar im SemaphoreMonitor).
* '''Idle-Verdrängung''' — ein Pool-Eintrag, der länger als
<code>idleEvictionSeconds</code> ungenutzt liegt, wird beim
nächsten Zugriff proaktiv geschlossen und neu geöffnet.
* '''Automatischer Reconnect''' — ein Fehler auf Transportebene
(Broken Pipe, EOF, MNU auf nil-Socket) verdrängt den
Pool-Eintrag, öffnet einen frischen Client und wiederholt die
Anfrage '''einmal'''. Anwendungsfehler aus
SFTP-STATUS-Antworten werden sofort durchgereicht.

== Ausblick ==

Geplant, aber noch nicht umgesetzt:

* '''Multi-Channel-Parallelität pro Host''' — aktuell bedeutet
eine TCP- plus eine SFTP-Verbindung pro Host, dass N
gleichzeitige Anfragen serialisieren. Pipelining über mehrere
SshClients im Pool (bevorzugt) oder ein transport-seitiger
Reader-Prozess, der eingehende Pakete in
Pro-Kanal-Postfächer demultiplext, würde es dem Baum-Panel
erlauben, weiter aufzulisten, während das Inhalts-Panel eine
große Datei liest.
* '''Genaues <code>#isNonEmptyDirectory</code>''' via OPEN_DIR
+ READ_DIR (nur erstes Batch) + CLOSE — drei Roundtrips pro
Sondierung; lohnt erst, wenn der SftpClient Anfragen pipelinen
kann.
* '''SFTP-v5/v6-Aushandlung''' für erweiterte Attribute und
FTP-artige Kanonisierung. (Atomares Überschreibungs-rename
ist bereits über die OpenSSH-Erweiterung
<code>posix-rename@openssh.com</code> abgedeckt; siehe
[[#OpenSSH-SFTP-Erweiterungen]].)

= Kommando-Shell =

Lokale Kommando-Shell auf dieser expecco-Maschine. Typische
Anwendungen: lokale Kommandozeile, lokales Hilfsprogramm,
Brücke zwischen entferntem Workflow und lokalem Tool.

Das RemoteAccess-Plugin stellt bereit:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

Keine Zugangsdaten, kein Netzwerk — läuft als der Benutzer des
expecco-Prozesses. Ausgaben gehen in das expecco-Log.

= Telnet =

[[File:Warning.svg|24px|Warnung]] '''Telnet ist ein veraltetes
Protokoll ohne Verschlüsselung.''' Passwörter werden im Klartext
über die Leitung übertragen; jeder im Netzpfad kann sie lesen.
Telnet NUR einsetzen, wenn die Gegenstelle keine Alternative
bietet (typisch: alte Industriesteuerungen, Laborgeräte,
eingebettete Messgeräte ohne SSH-Stack). Für alles andere
[[#SSH und SFTP]] verwenden.

Das expecco-Plugin stellt bereit:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (interne Demo)

Das Telnet-Protokoll (RFC 854) ist ein bidirektionaler
8-Bit-Byte-Strom über TCP, mit In-Band-Steuersequenzen für
Terminal-Optionen. Verbindungsaufbau zum Ziel-Host:Port; nach
optionalem In-Band-Login können beide Seiten Daten senden.

= Siehe auch =

* [[SSH Client|SSH::Client]] — die SSH-Schicht (exec, TTY,
Agent-Weiterleitung, ProxyJump).
* [[FileBrowserV2]] — die Haupt-UI dieses Stacks.
* [[ClaudeCode plugin|Claude Code]] — nutzt denselben SSH-Stack
als HTTPS-Transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Netz]]
[[Category:SSH]]

Vorlage:Languages

2026-05-26T10:19:27Z

Sv: Make bold-link label parameterizable (default English) — see Talk for rationale

{{nmbox
| header = '''[[Project:Language policy|{{Languages/Title|{{SUBPAGENAME}}}}]]'''
| text =
'''[[{{{1|:{{NAMESPACE}}:{{BASEPAGENAME}}}}}|{{{label|English}}}]]''' {{Languages/Lang|af|{{{1|}}}|
}}{{Languages/Lang|ar|{{{1|}}}|
}}{{Languages/Lang|ast|{{{1|}}}|
}}{{Languages/Lang|az|{{{1|}}}|
}}{{Languages/Lang|bcc|{{{1|}}}|
}}{{Languages/Lang|bg|{{{1|}}}|
}}{{Languages/Lang|br|{{{1|}}}|
}}{{Languages/Lang|bn|{{{1|}}}|
}}{{Languages/Lang|bs|{{{1|}}}|
}}{{Languages/Lang|ca|{{{1|}}}|
}}{{Languages/Lang|cs|{{{1|}}}|
}}{{Languages/Lang|da|{{{1|}}}|
}}{{Languages/Lang|de|{{{1|}}}|
}}{{Languages/Lang|diq|{{{1|}}}|
}}{{Languages/Lang|el|{{{1|}}}|
}}{{Languages/Lang|eo|{{{1|}}}|
}}{{Languages/Lang|es|{{{1|}}}|
}}{{Languages/Lang|fa|{{{1|}}}|
}}{{Languages/Lang|fi|{{{1|}}}|
}}{{Languages/Lang|fr|{{{1|}}}|
}}{{Languages/Lang|gl|{{{1|}}}|
}}{{Languages/Lang|gu|{{{1|}}}|
}}{{Languages/Lang|he|{{{1|}}}|
}}{{Languages/Lang|hi|{{{1|}}}|
}}{{Languages/Lang|hu|{{{1|}}}|
}}{{Languages/Lang|hy|{{{1|}}}|
}}{{Languages/Lang|id|{{{1|}}}|
}}{{Languages/Lang|io|{{{1|}}}|
}}{{Languages/Lang|it|{{{1|}}}|
}}{{Languages/Lang|ja|{{{1|}}}|
}}{{Languages/Lang|ka|{{{1|}}}|
}}{{Languages/Lang|kk|{{{1|}}}|
}}{{Languages/Lang|km|{{{1|}}}|
}}{{Languages/Lang|ko|{{{1|}}}|
}}{{Languages/Lang|ksh|{{{1|}}}|
}}{{Languages/Lang|kw|{{{1|}}}|
}}{{Languages/Lang|la|{{{1|}}}|
}}{{Languages/Lang|min|{{{1|}}}|
}}{{Languages/Lang|mk|{{{1|}}}|
}}{{Languages/Lang|ml|{{{1|}}}|
}}{{Languages/Lang|mr|{{{1|}}}|
}}{{Languages/Lang|ms|{{{1|}}}|
}}{{Languages/Lang|nl|{{{1|}}}|
}}{{Languages/Lang|no|{{{1|}}}|
}}{{Languages/Lang|oc|{{{1|}}}|
}}{{Languages/Lang|or|{{{1|}}}|
}}{{Languages/Lang|pl|{{{1|}}}|
}}{{Languages/Lang|pt|{{{1|}}}|
}}{{Languages/Lang|pt-br|{{{1|}}}|
}}{{Languages/Lang|ro|{{{1|}}}|
}}{{Languages/Lang|ru|{{{1|}}}|
}}{{Languages/Lang|si|{{{1|}}}|
}}{{Languages/Lang|sk|{{{1|}}}|
}}{{Languages/Lang|sl|{{{1|}}}|
}}{{Languages/Lang|sq|{{{1|}}}|
}}{{Languages/Lang|sr|{{{1|}}}|
}}{{Languages/Lang|sv|{{{1|}}}|
}}{{Languages/Lang|ta|{{{1|}}}|
}}{{Languages/Lang|th|{{{1|}}}|
}}{{Languages/Lang|tr|{{{1|}}}|
}}{{Languages/Lang|uk|{{{1|}}}|
}}{{Languages/Lang|vi|{{{1|}}}|
}}{{Languages/Lang|yi|{{{1|}}}|
}}{{Languages/Lang|yue|{{{1|}}}|
}}{{Languages/Lang|zh|{{{1|}}}|
}}{{Languages/Lang|zh-hans|{{{1|}}}|
}}{{Languages/Lang|zh-hant|{{{1|}}}|
}}{{Languages/Lang|zh-tw|{{{1|}}}}}|
}}<includeonly>{{#if:{{Languages/Lang|af|{{{1|}}}|
}}{{Languages/Lang|ar|{{{1|}}}|
}}{{Languages/Lang|ast|{{{1|}}}|
}}{{Languages/Lang|az|{{{1|}}}|
}}{{Languages/Lang|bcc|{{{1|}}}|
}}{{Languages/Lang|bg|{{{1|}}}|
}}{{Languages/Lang|br|{{{1|}}}|
}}{{Languages/Lang|bn|{{{1|}}}|
}}{{Languages/Lang|bs|{{{1|}}}|
}}{{Languages/Lang|ca|{{{1|}}}|
}}{{Languages/Lang|cs|{{{1|}}}|
}}{{Languages/Lang|da|{{{1|}}}|
}}{{Languages/Lang|de|{{{1|}}}|
}}{{Languages/Lang|diq|{{{1|}}}|
}}{{Languages/Lang|el|{{{1|}}}|
}}{{Languages/Lang|eo|{{{1|}}}|
}}{{Languages/Lang|es|{{{1|}}}|
}}{{Languages/Lang|fa|{{{1|}}}|
}}{{Languages/Lang|fi|{{{1|}}}|
}}{{Languages/Lang|fr|{{{1|}}}|
}}{{Languages/Lang|gl|{{{1|}}}|
}}{{Languages/Lang|gu|{{{1|}}}|
}}{{Languages/Lang|he|{{{1|}}}|
}}{{Languages/Lang|hi|{{{1|}}}|
}}{{Languages/Lang|hu|{{{1|}}}|
}}{{Languages/Lang|hy|{{{1|}}}|
}}{{Languages/Lang|id|{{{1|}}}|
}}{{Languages/Lang|io|{{{1|}}}|
}}{{Languages/Lang|it|{{{1|}}}|
}}{{Languages/Lang|ja|{{{1|}}}|
}}{{Languages/Lang|ka|{{{1|}}}|
}}{{Languages/Lang|kk|{{{1|}}}|
}}{{Languages/Lang|km|{{{1|}}}|
}}{{Languages/Lang|ko|{{{1|}}}|
}}{{Languages/Lang|ksh|{{{1|}}}|
}}{{Languages/Lang|kw|{{{1|}}}|
}}{{Languages/Lang|la|{{{1|}}}|
}}{{Languages/Lang|min|{{{1|}}}|
}}{{Languages/Lang|mk|{{{1|}}}|
}}{{Languages/Lang|ml|{{{1|}}}|
}}{{Languages/Lang|mr|{{{1|}}}|
}}{{Languages/Lang|ms|{{{1|}}}|
}}{{Languages/Lang|nl|{{{1|}}}|
}}{{Languages/Lang|no|{{{1|}}}|
}}{{Languages/Lang|oc|{{{1|}}}|
}}{{Languages/Lang|or|{{{1|}}}|
}}{{Languages/Lang|pl|{{{1|}}}|
}}{{Languages/Lang|pt|{{{1|}}}|
}}{{Languages/Lang|pt-br|{{{1|}}}|
}}{{Languages/Lang|ro|{{{1|}}}|
}}{{Languages/Lang|ru|{{{1|}}}|
}}{{Languages/Lang|si|{{{1|}}}|
}}{{Languages/Lang|sk|{{{1|}}}|
}}{{Languages/Lang|sl|{{{1|}}}|
}}{{Languages/Lang|sq|{{{1|}}}|
}}{{Languages/Lang|sr|{{{1|}}}|
}}{{Languages/Lang|sv|{{{1|}}}|
}}{{Languages/Lang|ta|{{{1|}}}|
}}{{Languages/Lang|th|{{{1|}}}|
}}{{Languages/Lang|tr|{{{1|}}}|
}}{{Languages/Lang|uk|{{{1|}}}|
}}{{Languages/Lang|vi|{{{1|}}}|
}}{{Languages/Lang|yi|{{{1|}}}|
}}{{Languages/Lang|yue|{{{1|}}}|
}}{{Languages/Lang|zh|{{{1|}}}|
}}{{Languages/Lang|zh-hans|{{{1|}}}|
}}{{Languages/Lang|zh-hant|{{{1|}}}|
}}{{Languages/Lang|zh-tw|{{{1|}}}}}
||[[Category:Languages pages without translations]]}}</includeonly><noinclude>
{{documentation}}
[[Category:Exclude in print]]
</noinclude>

Remote Access/en

2026-05-26T09:53:07Z

Sv: Add Filesystem Info feature; document OpenSSH SFTP extensions (posix-rename, hardlink, statvfs, fsync); correct stale limitations/future-work entries.

{{Languages|Remote Access|Remote Access/en}}

'''Remote access''' is the ability to drive a remote computer or
network from this expecco image — opening shells, running commands,
moving files, or driving a test target. Three protocol families are
supported, listed in current-recommended order:

* '''SSH and SFTP''' (recommended) — encrypted shell + secure
file transfer over an SSH-2 tunnel. Pure-Smalltalk implementation
in <code>exept:libcrypt/ssh</code>; no external dependency on
OpenSSL or libssh. Use this for anything that touches credentials
or sensitive payloads.
* '''Local Command Shell''' — fork + exec on the local machine.
Used for local-tool integration and for the local end of a remote
workflow that bridges via another protocol.
* '''Telnet''' (legacy) — plain-text terminal session. No
encryption, passwords on the wire in clear. Use only when the
target hardware has no other option.

= SSH and SFTP =

The SSH stack covers the full SSH-2 protocol (RFC 4251–4254,
RFC 5656, RFC 8709, RFC 8731) plus OpenSSH's chacha20-poly1305
transport cipher and the SFTP v3 file-transfer subsystem
(draft-ietf-secsh-filexfer-02). Two layers:

* '''<code>SSH::Client</code>''' — programmatic SSH access (remote
<code>exec</code>, TTY shell, agent forwarding, ProxyJump bastion).
* '''<code>SSH::SftpFilename</code>''' — a <code>Filename</code>
subclass that lets the rest of ST/X treat a remote SFTP path the
same way it treats a local file.

The rest of this section is organised user-task-first: what the user
sees and does, the expecco-library hooks below that, then the
implementation detail at the end for the curious.

== From the FileBrowserV2 ==

Open the location dropdown and paste an <code>sftp://</code> URL.
The browser tab populates as if it were a local path. Tree
expansion, column sort (name / size / mtime), preview, and
double-click-to-open-in-editor all behave normally. The first
click on a host takes ~200–500 ms (TCP + KEX + auth); subsequent
clicks reuse the pooled connection.

URL syntax:

<pre>
sftp://[user@]host[:port]/remote/path
</pre>

User defaults to the local login name, port to 22, path to
<code>/</code>.

The Tools menu offers four browser actions, three of them gated on
the SSH library being loaded:

* '''Generate SSH Key Pair...''' — opens the same key-generation
dialog described under [[#Generating an SSH key pair]] below.
* '''SSH Connect...''' — opens an interactive VT100 terminal to a
remote host.
* '''SFTP Connect...''' — points this browser tab at a remote
filesystem via SFTP.
* '''Filesystem Info...''' — shows size, free space and usage of
the filesystem holding the currently displayed directory. Works
uniformly for local paths and SFTP paths; for SFTP it requires
the server to advertise the <code>statvfs@openssh.com</code>
extension (every modern OpenSSH does). Sizes are reported in
IEC binary units (MiB, GiB, TiB) — the largest unit yielding a
value ≥ 1 is chosen, so a TB-scale volume reads as ''X TiB''
rather than ''10240 GiB''.

== From expecco actions ==

The Expecco RemoteAccess plugin
([[Expecco::RemoteAccessImportPlugin]]) exposes the following test
actions to the expecco action palette:

* '''CmdShell - Open SSH Remote Connection''' — opens an SSH session
via the platform's <code>ssh</code> binary (PuTTY's
<code>plink</code> on Windows).
* '''CmdShell - Open SSH Remote Connection and PublicKey''' — same
but with explicit public-key authentication.

To run these you need a configured keypair (private key on this
machine, public key in the remote host's
<code>~/.ssh/authorized_keys</code>). Generate one via the dialog
below or via <code>ssh-keygen</code>.

The plugin also adds a settings page at '''Extras → Settings →
Plugins → Remote Access — SSH Keys''' carrying a single
'''Generate SSH Key Pair...''' button that opens the same dialog.

== Generating an SSH key pair ==

=== The dialog (FileBrowserV2 / settings page) ===

The dialog asks for all parameters in one form:

* '''Comment''' — embedded in the generated key (defaults to
<code>stx@<hostname></code>).
* '''Storage''':
** ''Save to disk file only'' — writes <code>~/.ssh/id_ed25519_stx</code>
(or wherever) plus a matching <code>.pub</code> companion.
** ''Save to disk AND load into ssh-agent'' — writes the file and
also hands the key to the running ssh-agent.
** ''Load into ssh-agent only'' — key lives in agent memory only;
gone on agent restart.
* '''Private key file''' — full path; disabled in agent-only mode.
* '''Passphrase / Confirm''' — empty leaves the on-disk file
unencrypted (agent-only mode ignores the passphrase, since the
OpenSSH agent wire protocol carries only the decrypted key).

On '''Generate''', the public-key line (the same
<code>ssh-ed25519 AAAA... comment</code> string ssh-keygen
emits) is copied to the system clipboard for pasting into the
remote host's <code>~/.ssh/authorized_keys</code>.

=== From a workspace ===

For headless deployments, sandboxed builds, or scripts,
<code>SSH::Client</code> exposes a pure-Smalltalk key generator
that produces output bit-compatible with
<code>ssh-keygen -t ed25519</code>:

<pre>
| seed comment priv |
seed := SSH::Client generateEd25519Seed.
comment := 'stx@', OperatingSystem getHostName.

"/ Save passphrase-encrypted to disk"
priv := (Filename homeDirectory / '.ssh' / 'id_ed25519_stx') pathName.
SSH::Client
saveOpenSshEd25519Seed:seed
toFile:priv
comment:comment
passphrase:'choose-something-long'.

"/ AND load into the running agent"
SSH::Client addEd25519SeedToAgent:seed comment:comment.

"/ Print the public-key line to paste into authorized_keys"
Transcript showCR:
(SSH::Client authorizedKeysLineForEd25519Seed:seed comment:comment).
</pre>

Keys generated this way are interoperable with OpenSSH's own
tooling (<code>ssh-keygen -y -f ...</code> re-derives the public
key, <code>ssh-keygen -p -f ...</code> changes the passphrase,
etc.).

=== Using the shell tools instead ===

The traditional path also works:

<pre>
ssh-keygen -t ed25519 -C "stx@your.host"
ssh-copy-id user@remotehost
ssh-add ~/.ssh/id_ed25519
</pre>

== Preparing ssh-agent ==

The agent path is strongly preferred over reading raw keyfiles: it
keeps encrypted private keys unlocked once per session, and handles
identities (hardware-token-backed keys, KeePassXC entries) that
ST/X should never see directly.

ST/X picks the agent path automatically when
<code>$SSH_AUTH_SOCK</code> is set in the process environment
'''at the time stx is launched'''. Setting it later from a
workspace does not help.

=== Linux / macOS ===

Most desktop distributions launch an agent automatically as part of
the session (gnome-keyring on GNOME, ssh-agent.service on systemd,
KWallet on KDE). Verify in a terminal:

<pre>
echo $SSH_AUTH_SOCK # /run/user/1000/keyring/ssh or similar
ssh-add -l # lists loaded identities
ssh-add ~/.ssh/id_ed25519 # load yours if not loaded
</pre>

If no agent runs at all, add this snippet to your shell rc:

<pre>
# ~/.bashrc or ~/.zshrc
if [ -z "$SSH_AUTH_SOCK" ]; then
eval "$(ssh-agent -s)" > /dev/null
fi
</pre>

ST/X must be launched from a shell that has seen this rc — a
desktop launcher started from the file manager does NOT inherit
the variable. Wrap the stx start command in a small script under
<code>~/.local/bin/</code> that sources the rc first.

The Remote Access settings page ('''Extras → Settings → Plugins
→ Remote Access — SSH Keys''') shows whether the running image
sees an agent.

==== Permanent setup via systemd ====

For a truly cross-session agent (survives desktop logouts, comes
up automatically at next login), enable the per-user systemd
unit shipped with most distros' <code>openssh-clients</code>
package:

<pre>
systemctl --user enable --now ssh-agent.service
</pre>

Then point <code>SSH_AUTH_SOCK</code> at the user-service socket
in your shell rc (this replaces the <code>eval $(ssh-agent -s)</code>
snippet above):

<pre>
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</pre>

==== Auto-loading keys on first use ====

To skip the manual <code>ssh-add</code> step, let OpenSSH load
keys into the agent automatically the first time they are needed.
Add to <code>~/.ssh/config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

The first SSH connection then prompts for the key passphrase
once and hands the unlocked key to the agent; subsequent
connections use the cached identity without prompting.

=== Windows ===

Windows 10+ ships native OpenSSH including an agent service.
One-time setup:

# Open '''Services''' (<code>services.msc</code>) as Administrator.
# Find '''OpenSSH Authentication Agent''', set Startup Type to
'''Automatic''', click '''Start'''.
# In PowerShell: <code>ssh-add $HOME\.ssh\id_ed25519</code>.
# Verify: <code>ssh-add -l</code>.

The Windows OpenSSH agent listens on a named pipe
(<code>\\.\pipe\openssh-ssh-agent</code>), not a Unix socket. ST/X
supports both transports, but Windows ssh-add does '''not''' set
<code>SSH_AUTH_SOCK</code> for you. Add it manually:

# Press {{Key|Win}} → type "environment" → "Edit the system environment variables".
# '''Environment Variables''' → under '''User variables''', '''New'''.
# Name: <code>SSH_AUTH_SOCK</code>
# Value: <code>\\.\pipe\openssh-ssh-agent</code>
# Log out and back in (or restart stx) so the new env propagates.

==== PowerShell quick-setup ====

The same setup from an '''elevated''' PowerShell prompt, for
scripts or unattended provisioning:

<pre>
# Start the agent now AND on every reboot (permanent).
Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

# Persist SSH_AUTH_SOCK for the user (survives reboots).
[Environment]::SetEnvironmentVariable(
'SSH_AUTH_SOCK',
'\\.\pipe\openssh-ssh-agent',
'User')

# Load a key (prompts for the passphrase if the file is encrypted).
ssh-add $HOME\.ssh\id_ed25519
</pre>

For a one-shot agent start without making it persistent (e.g.
single-session test), drop the <code>Set-Service</code> line and
just run <code>Start-Service ssh-agent</code>. The env-var line
can also be omitted if <code>SSH_AUTH_SOCK</code> is only needed
in the current shell — use <code>$env:SSH_AUTH_SOCK = '...'</code>
instead for that session-local form.

On stripped-down Windows installs the ssh-agent service may not
be present. Add it once via '''Settings → Apps → Optional
features → OpenSSH Client'''.

Alternative agents:

* '''PuTTY pageant''' — uses its own protocol; NOT supported by
ST/X's SSH::Agent. Migrate the keys to OpenSSH.
* '''Git for Windows ssh-agent''' — works; point
<code>SSH_AUTH_SOCK</code> at the socket it publishes.
* '''WSL 2''' — a ST/X inside WSL sees WSL's Linux agent normally;
a ST/X on the Windows side does not. Bridging needs a helper
like <code>npiperelay</code> + <code>socat</code>.

Verify in the Remote Access settings page
('''Extras → Settings → Plugins → Remote Access — SSH Keys''') —
the agent indicator there reports whether the running image sees
the agent.

==== Auto-loading keys on first use ====

Windows OpenSSH does '''not''' persist agent-loaded keys across
agent restarts. To avoid running <code>ssh-add</code> manually
after each reboot, add the same lazy-load configuration to
<code>%USERPROFILE%\.ssh\config</code>:

<pre>
Host *
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
</pre>

OpenSSH then loads the key into the agent on first use (prompts
for the passphrase once) and reuses it for the rest of the
session.

== Configuration ==

All tunables are class-side on <code>SSH::SftpFilename</code>:

{| class="wikitable"
! Accessor !! Default !! What it controls
|-
| <code>#idleEvictionSeconds:</code> || 240 (4 min) || How long a pooled
connection sits idle before the next access proactively closes +
reopens it. Just under typical sshd
<code>ClientAliveInterval × ClientAliveCountMax</code> so we recycle
before the server TCP-RESETs us. Pass <code>nil</code> to restore
the default.
|-
| <code>#attrsCacheTtlSeconds:</code> || 5 || Max age (s) of a
cached STAT before <code>#ensureAttrs</code> refetches. Parent
listDir always re-stamps fresh attrs onto children, so navigating
an open directory does not pay the TTL. Set to <code>0</code> to
disable caching.
|-
| <code>#closeAllConnections</code> || (action) || Tears down every
pooled connection. Useful after a known-bad network event, before
a deliberate identity swap, or as part of a clean image shutdown.
|}

== Diagnostics ==

=== SemaphoreMonitor ===

Open <code>SemaphoreMonitor</code> from the Launcher's "Status"
sub-menu. Per-host SFTP mutex appears as
<code>SFTP/<user@host:port></code>; the pool-wide mutex as
<code>SFTP/pool</code>. Right-click a row:

* '''Copy Waiters Stack to Clipboard''' — dumps the last-owner's
walkback plus each waiter's, formatted as plain text. Use when
a process is wedged in <code>readWait</code> inside
<code>withSftpClientDo:</code> and you need to see which SFTP
request it is on.
* '''Copy List to Clipboard''' — the whole table, for an
email-this-to-someone diagnosis.
* '''Detect Deadlocks''' — DFS over the wait-for graph, reports
cycles.

=== Logger ===

The SSH stack logs interesting events:

* <code>warning:</code> on auto-reconnect after a dead connection.
* <code>warning:</code> when a pool entry is idle-evicted.
* <code>warning:</code> when an SSH key file cannot be parsed
(e.g. legacy PEM, encrypted-without-agent) — the file is skipped,
others tried.

== Limitations ==

* '''SFTP v3 only.''' No SETSTAT (no remote chmod / chown / utime),
no SSH_FXP_READLINK exposed (<code>#isSymbolicLink</code> always
<code>false</code>, <code>#linkInfo</code> returns the regular
stat info). Several SFTPv5+ niceties are nevertheless picked up
via OpenSSH SSH_FXP_EXTENDED requests — see
[[#OpenSSH SFTP extensions]] below.
* '''Per-host serialisation.''' Two concurrent operations on the
same host queue through the host mutex. See [[#Future work]].
* '''<code>#renameTo:</code> fallback has a TOCTOU window.''' On
servers that advertise <code>posix-rename@openssh.com</code> (every
modern OpenSSH does), overwrite is atomic; on the rare server
that does not, the receiver is emulated as delete-then-rename
and another process can race in between.
* '''<code>#isNonEmptyDirectory</code> is heuristic.''' Always
returns <code>#isDirectory</code> (the accurate answer would cost
three round-trips per directory icon, which made the original tree
expansion unbearably slow).

== Implementation details ==

For readers wanting the architecture. Five classes, top-down:

{| class="wikitable"
! Class !! Role
|-
| <code>SSH::SftpFilename</code> || Filename subclass; the public
API. Maps <code>sftp://...</code> URLs to remote files; exposes
<code>directoryContents</code>, <code>readingFileDo:</code>,
<code>renameTo:</code> etc.
|-
| <code>SSH::SftpClient</code> || SFTP-v3 protocol
(request/response codec, listDir, stat, open, read, write, mkdir).
Driven by SftpFilename.
|-
| <code>SSH::Channel</code> || SSH channel multiplexer
(CHANNEL_OPEN, DATA, EOF, CLOSE, WINDOW_ADJUST). One logical
session per Channel instance.
|-
| <code>SSH::Client</code> || High-level SSH client: opens the
transport, runs KEX, host-key check, userauth, then dispenses
Channels.
|-
| <code>SSH::Transport</code> || Wire layer. Banner + KEXINIT
exchange, ChaCha20-Poly1305 packet framing, sendSeq / recvSeq,
heartbeat, SSH_MSG_DISCONNECT.
|}

=== OpenSSH SFTP extensions ===

SFTP v3 (RFC draft-ietf-secsh-filexfer-02) is intentionally minimal.
OpenSSH ships an open-ended extension mechanism: the server lists
extension names it understands in its <code>SSH_FXP_VERSION</code>
reply, and the client invokes them via
<code>SSH_FXP_EXTENDED(200)</code> packets carrying the extension
name as the first string. Each extension is feature-detected via
<code>SSH::SftpClient>>supportsExtension:</code>; callers fall
back when the server doesn't advertise it.

The stack uses four of the OpenSSH extensions today:

* <code>posix-rename@openssh.com</code> — atomic
rename-with-overwrite. Picked up automatically by
<code>SftpFilename>>renameTo:</code>; the delete-then-rename
fallback only fires on servers that lack it.
* <code>hardlink@openssh.com</code> — create a POSIX hard link.
Exposed as <code>SftpFilename>>createHardLinkAs:</code>.
* <code>statvfs@openssh.com</code> — POSIX
<code>statvfs(3)</code>-shape filesystem stats. Exposed as
<code>SftpFilename>>fileSystemInfo</code>; the result is
shape-compatible with <code>OperatingSystem getDiskInfoOf:</code>
so callers can treat local and remote uniformly. Drives the
'''Tools → Filesystem Info...''' menu entry described at the
top of this page.
* <code>fsync@openssh.com</code> — flush server-side write buffer
to disk on an open handle. Available on the low-level
<code>SftpClient>>fsyncHandle:</code>; not yet plumbed
into a Filename-level "durable write" API.

The remaining OpenSSH extensions
(<code>lsetstat@openssh.com</code>, <code>fstatvfs@openssh.com</code>)
are recognised in the advertised-extensions list but not wrapped at
Filename level — there's no Filename-side caller for them yet.

=== Connection pooling ===

Every <code>SftpFilename</code> instance pointing at the same
<code>user@host:port</code> triple shares one
<code>SSH::Client</code> plus one <code>SSH::SftpClient</code>.
Pool is class-side, guarded by a single
<code>ConnectionPoolMutex</code>:

* '''Lazy bring-up''' — TCP + KEX + userauth + SFTP INIT happens
on the first SFTP operation, not on <code>forUrl:</code>.
* '''Per-host serialisation''' — SFTP requests on a given host
are serialised through a <code>RecursionLock</code> named
<code>SFTP/<user@host:port></code> (visible in
SemaphoreMonitor).
* '''Idle eviction''' — unused for longer than
<code>idleEvictionSeconds</code>, the entry is proactively
closed + reopened on the next access.
* '''Auto-reconnect''' — a transport-level failure (broken pipe,
EOF, MNU on nil socket) evicts the dead pool entry, opens a
fresh client, retries the request '''once'''. Application-level
SFTP STATUS errors propagate immediately.

== Future work ==

Tracked but not yet implemented:

* '''Multi-channel parallelism per host''' — today one TCP +
one SFTP channel per host means N concurrent requests
serialise. Pipelining over multiple SshClients in the pool
(preferred), or a transport-level reader process demultiplexing
to per-channel inboxes, would let the tree pane keep listing
while the content pane reads a large file.
* '''Accurate <code>#isNonEmptyDirectory</code>''' via OPEN_DIR
+ READ_DIR (first batch only) + CLOSE — three RTTs per probe;
needs SftpClient to pipeline requests before this pays off.
* '''SFTP v5/v6 negotiation''' for extended attrs and FTP-style
canonicalisation. (Atomic-overwrite rename is already handled
via the OpenSSH <code>posix-rename@openssh.com</code> extension;
see [[#OpenSSH SFTP extensions]].)

= Command Shell =

Local command shell on this expecco machine. Typical applications:
local command-line, running a local helper tool, bridging a
remote workflow to a local utility.

The Expecco RemoteAccess plugin exposes:

* '''CmdShell - Open'''
* '''CmdShell - Close'''

No credentials, no network — runs as the expecco process's own
user. Output streams to expecco's log.

= Telnet =

[[File:Warning.svg|24px|Warning]] '''Telnet is a legacy protocol
with no encryption.''' Passwords are transmitted in plain text on
the wire; anyone on the network path can read them. Use Telnet
ONLY when the target device has no other option (typically: old
industrial controllers, lab instruments, embedded measurement
equipment without an SSH stack). For everything else use
[[#SSH and SFTP]].

The expecco plugin exposes:

* '''Telnet - Open Remote Connection With Login'''
* '''Telnet - Execute Remote Command'''
* '''Example - Remote Device Control via Telnet''' (internal demo)

The Telnet protocol (RFC 854) is a bidirectional 8-bit byte stream
over TCP, with in-band control sequences for terminal options.
A connection is established to a target host:port; after optional
in-band login, both sides can send data.

= See also =

* [[SSH Client/en|SSH::Client]] — the SSH layer (exec, TTY, agent
forwarding, ProxyJump).
* [[FileBrowserV2/en|FileBrowserV2]] — the main UI client of
this stack.
* [[ClaudeCode plugin/en|Claude Code]] — uses the same SSH stack
for its HTTPS transport.
* [[Wikipedia:Secure Shell|RFC 4251 (SSH-2 Architecture)]]
* [[Wikipedia:Telnet|RFC 854 (Telnet Protocol)]]

[[Category:Plugins]]
[[Category:Network]]
[[Category:SSH]]