CLI & Headless

Überblick

Theron läuft auch ohne Fenster – mit denselben Agents und Prozessen wie in der App. Drei Wege:

Alle Builds enthalten Theron als kompilierten Maschinencode. Die Agents arbeiten mit Claude Code auf dem jeweiligen Rechner – mit deinem Claude-Abo – oder mit lokalen Modellen über OpenCode.

Installieren

Befehle

BefehlWirkung
theron execute PROZESS [ORDNER] ["AUFTRAG"] [-q] [--no-server]Einen Prozess ausführen (Alias: run). Details unten.
theron execute-package PAKET [ORDNER] [--task "…"] [--interactive]Das Paket einer Prozess-Executable ausführen – das macht die Executable selbst (siehe Prozess als Executable).
theron processesVorhandene Prozesse auflisten.
theron export PROZESS DATEI.theronEinen Prozess samt Agents und Wissen exportieren.
theron config [show]Einstellungen anzeigen.
theron config server ADRESSE TOKEN · … server offMit dem Theron-Server verbinden (prüft die Verbindung) bzw. trennen.
theron config sync on|off [--knowledge on|off] [--memory on|off] [--databases on|off]Prozesse und Agents über den Server abgleichen – auf Wunsch mit Wissen, Memorys und Datenbanken.
theron config language de|enSprache von Theron.
theron syncJetzt mit dem Server abgleichen.
theron status · theron versionVersion, Datenordner, Server, Sync, Claude-CLI.
theron --listen HOST:PORT [--token TOKEN] [--no-plugins]Als Slave starten (siehe unten).
theron plugin list|install|remove|enable|disable|new|pack|keygen|trust …Plugins verwalten und bauen – siehe Plugins.

Prozesse ausführen

Cronjobs & CI

# jede Nacht um 3 Uhr: Abhängigkeiten aktualisieren, Theron entscheidet selbst
0 3 * * * cd /srv/shop && theron execute "Dependency-Update" . -q >> /var/log/theron.log 2>&1

# in einer CI-Pipeline: Review eines Merge-Requests aus einer exportierten Prozessdatei
theron execute review.theron . "Prüfe die Änderungen dieses Merge-Requests" -q || exit 1

Im Cronjob fehlt oft der PATH – dann den vollen Pfad zu theron angeben. Mit eingerichtetem Server siehst du nächtliche Läufe im Web-UI.

Slave-Betrieb: theron --listen

Ein Slave ist Theron ohne Fenster, den deine App steuert. Starte ihn auf dem Rechner, auf dem gearbeitet werden soll:

theron config server https://theron.example.com TOKEN   # optional: Rückfragen im Web-UI
theron --listen 0.0.0.0:7531 --token GEHEIM

Er zeigt Adresse, Token und den Fingerprint seines Zertifikats (Zertifikat und Token liegen im Datenordner unter slave/ und bleiben gleich). Ohne --token erzeugt er einen und merkt ihn sich.

Headless-Worker (Docker)

Das Image enthält Claude Code und Theron als Slave. Es enthält keine Zugangsdaten – dein Claude-Login kommt beim Start dazu.

docker run -d --name theron-worker --restart unless-stopped -p 7531:7531 -v theron:/data \
  -e THERON_SLAVE_TOKEN=geheim -e CLAUDE_CODE_OAUTH_TOKEN=… -e THERON_NAME=worker-1 \
  mibexx1985/theron-headless
docker logs theron-worker | grep Fingerprint

Offline: das Archiv von der Startseite mit docker load -i theron-headless-image-amd64.tar.gz laden.

VariableBedeutung
CLAUDE_CODE_OAUTH_TOKENDein Claude-Abo (einmal lokal: claude setup-token) – nutzt die Limits deines Abos, keine API-Kosten.
THERON_SLAVE_TOKENToken für deine App; leer = einmal erzeugt und in /data gespeichert.
THERON_NAMEName in der App und auf dem Server (Standard: Hostname des Containers).
THERON_SERVER_URL, THERON_SERVER_TOKENOptional: Verbindung zum Theron-Server (Rückfragen im Web).
THERON_SYNCon: Prozesse und Agents mit dem Server abgleichen.
THERON_LANGUAGEde oder en.
THERON_PLUGIN_PACKAGESOrdner mit .theronplugin-Dateien, die bei jedem Start installiert werden (Standard /data/plugin-packages).
THERON_LISTENAdresse (Standard 0.0.0.0:7531).
THERON_ALLOW_API_KEY1: auch ANTHROPIC_API_KEY nutzen (kostenpflichtige API). Ohne wird ein API-Key ignoriert.

Kubernetes

Ein vollständiges Beispiel: Secret mit Slave-Token, Claude-Token und optional Server-Token, ein Volume für /data, ein Deployment mit genau einem Pod (Strategie Recreate) und ein Service.

apiVersion: v1
kind: Secret
metadata: { name: theron-headless, namespace: theron }
stringData:
  slave-token: "LANGER-ZUFALLS-TOKEN"            # openssl rand -base64 24
  claude-oauth-token: "…"                        # claude setup-token
  server-token: "…"                              # optional: Theron-Server
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: theron-headless-data, namespace: theron }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 20Gi } }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: theron-headless, namespace: theron }
spec:
  replicas: 1
  strategy: { type: Recreate }                   # one pod per /data volume
  selector: { matchLabels: { app: theron-headless } }
  template:
    metadata: { labels: { app: theron-headless } }
    spec:
      securityContext: { fsGroup: 10001 }
      containers:
        - name: theron-headless
          image: mibexx1985/theron-headless:latest
          ports: [{ name: slave, containerPort: 7531 }]
          env:
            - { name: THERON_NAME, value: "k8s-worker" }
            - name: THERON_SLAVE_TOKEN
              valueFrom: { secretKeyRef: { name: theron-headless, key: slave-token } }
            - name: CLAUDE_CODE_OAUTH_TOKEN
              valueFrom: { secretKeyRef: { name: theron-headless, key: claude-oauth-token } }
            - { name: THERON_SERVER_URL, value: "https://theron.example.com" }   # optional
            - name: THERON_SERVER_TOKEN
              valueFrom: { secretKeyRef: { name: theron-headless, key: server-token, optional: true } }
          volumeMounts: [{ name: data, mountPath: /data }]
          readinessProbe: { tcpSocket: { port: slave }, periodSeconds: 10 }
          resources: { requests: { cpu: 500m, memory: 1Gi }, limits: { memory: 6Gi } }
      volumes: [{ name: data, persistentVolumeClaim: { claimName: theron-headless-data } }]
---
apiVersion: v1
kind: Service
metadata: { name: theron-headless, namespace: theron }
spec:
  type: LoadBalancer                             # or NodePort – not an HTTP ingress
  selector: { app: theron-headless }
  ports: [{ name: slave, port: 7531, targetPort: slave }]

Mit kubectl apply -f theron-headless.yaml anlegen.

CLI & headless

Overview

Theron also runs without a window – with the same agents and processes as in the app. Three ways:

Every build contains Theron as compiled machine code. The agents work with Claude Code on that machine – with your Claude subscription – or with local models via OpenCode.

Install

Commands

CommandEffect
theron execute PROCESS [FOLDER] ["TASK"] [-q] [--no-server]Run a process (alias: run). Details below.
theron execute-package PACKAGE [FOLDER] [--task "…"] [--interactive]Runs the package of a process executable – the executable does this itself (see Process as executable).
theron processesList the processes.
theron export PROCESS FILE.theronExport a process with its agents and knowledge.
theron config [show]Show the settings.
theron config server ADDRESS TOKEN · … server offConnect to the Theron server (checks the connection) or disconnect.
theron config sync on|off [--knowledge on|off] [--memory on|off] [--databases on|off]Synchronise processes and agents via the server – optionally with knowledge, memories and databases.
theron config language de|enTheron's language.
theron syncSynchronise with the server now.
theron status · theron versionVersion, data folder, server, sync, Claude CLI.
theron --listen HOST:PORT [--token TOKEN] [--no-plugins]Start as a slave (see below).
theron plugin list|install|remove|enable|disable|new|pack|keygen|trust …Manage and build plugins – see Plugins.

Running processes

Cron jobs & CI

# every night at 3 am: update dependencies, Theron decides by itself
0 3 * * * cd /srv/shop && theron execute "Dependency update" . -q >> /var/log/theron.log 2>&1

# in a CI pipeline: review a merge request with an exported process file
theron execute review.theron . "Review the changes of this merge request" -q || exit 1

Cron often lacks the PATH – then give the full path to theron. With a server set up, you see nightly runs in the web UI.

Slave mode: theron --listen

A slave is Theron without a window, controlled by your app. Start it on the machine that should do the work:

theron config server https://theron.example.com TOKEN   # optional: questions in the web UI
theron --listen 0.0.0.0:7531 --token SECRET

It shows its address, token and the fingerprint of its certificate (certificate and token live in the data folder under slave/ and stay the same). Without --token it creates one and keeps it.

Headless worker (Docker)

The image contains Claude Code and Theron as a slave. It contains no credentials – your Claude login is added when you start it.

docker run -d --name theron-worker --restart unless-stopped -p 7531:7531 -v theron:/data \
  -e THERON_SLAVE_TOKEN=secret -e CLAUDE_CODE_OAUTH_TOKEN=… -e THERON_NAME=worker-1 \
  mibexx1985/theron-headless
docker logs theron-worker | grep Fingerprint

Offline: load the archive from the home page with docker load -i theron-headless-image-amd64.tar.gz.

VariableMeaning
CLAUDE_CODE_OAUTH_TOKENYour Claude subscription (once locally: claude setup-token) – uses your plan's limits, no API costs.
THERON_SLAVE_TOKENToken for your app; empty = created once and kept in /data.
THERON_NAMEName in the app and on the server (default: the container's host name).
THERON_SERVER_URL, THERON_SERVER_TOKENOptional: connection to the Theron server (questions on the web).
THERON_SYNCon: synchronise processes and agents with the server.
THERON_LANGUAGEde or en.
THERON_PLUGIN_PACKAGESFolder with .theronplugin files installed at every start (default /data/plugin-packages).
THERON_LISTENAddress (default 0.0.0.0:7531).
THERON_ALLOW_API_KEY1: also use ANTHROPIC_API_KEY (paid API). Without it an API key is ignored.

Kubernetes

A complete example: a secret with slave token, Claude token and optionally server token, a volume for /data, a deployment with exactly one pod (strategy Recreate) and a service.

apiVersion: v1
kind: Secret
metadata: { name: theron-headless, namespace: theron }
stringData:
  slave-token: "LANGER-ZUFALLS-TOKEN"            # openssl rand -base64 24
  claude-oauth-token: "…"                        # claude setup-token
  server-token: "…"                              # optional: Theron-Server
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: theron-headless-data, namespace: theron }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 20Gi } }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: theron-headless, namespace: theron }
spec:
  replicas: 1
  strategy: { type: Recreate }                   # one pod per /data volume
  selector: { matchLabels: { app: theron-headless } }
  template:
    metadata: { labels: { app: theron-headless } }
    spec:
      securityContext: { fsGroup: 10001 }
      containers:
        - name: theron-headless
          image: mibexx1985/theron-headless:latest
          ports: [{ name: slave, containerPort: 7531 }]
          env:
            - { name: THERON_NAME, value: "k8s-worker" }
            - name: THERON_SLAVE_TOKEN
              valueFrom: { secretKeyRef: { name: theron-headless, key: slave-token } }
            - name: CLAUDE_CODE_OAUTH_TOKEN
              valueFrom: { secretKeyRef: { name: theron-headless, key: claude-oauth-token } }
            - { name: THERON_SERVER_URL, value: "https://theron.example.com" }   # optional
            - name: THERON_SERVER_TOKEN
              valueFrom: { secretKeyRef: { name: theron-headless, key: server-token, optional: true } }
          volumeMounts: [{ name: data, mountPath: /data }]
          readinessProbe: { tcpSocket: { port: slave }, periodSeconds: 10 }
          resources: { requests: { cpu: 500m, memory: 1Gi }, limits: { memory: 6Gi } }
      volumes: [{ name: data, persistentVolumeClaim: { claimName: theron-headless-data } }]
---
apiVersion: v1
kind: Service
metadata: { name: theron-headless, namespace: theron }
spec:
  type: LoadBalancer                             # or NodePort – not an HTTP ingress
  selector: { app: theron-headless }
  ports: [{ name: slave, port: 7531, targetPort: slave }]

Create it with kubectl apply -f theron-headless.yaml.