Skip to main content

Reference Manual

Reference Manual

Applies to Terminux 0.1.1. Commands and features may differ in other versions.

Contents

  1. About this manual
  2. System overview
  3. Command reference
  4. Terminux terminal (GUI) reference
  5. DQE Viewer reference
  6. @@ reference
  7. Configuration reference
  8. Files and data reference
  9. Quality checks (DQE) reference
  10. Messages and codes
  11. Limits, timeouts and defaults
  12. Glossary

1. About this manual

1.1 Notation

Notation Meaning
<value> Required; replace with an actual value
[option] Optional
a|b One of the alternatives
… Repeatable, or the rest omitted
~ Your home directory
<nodename> The host name (overridable with TERMINUX_NODENAME)

1.2 Where the commands are

  • Source installation: in the bin/ of the Python environment (for example $VIRTUAL_ENV/bin/).
  • Portable bundle: ~/.local/bin contains only terminux (= terminux-launch) and terminux-qt-check; the other commands are in ~/.local/opt/terminux/current/venv/bin/.
  • Scripts in the source tree: terminux-chat, terminux-dream, terminux-lineage-graph, terminux-build-rag-index and terminux-llm-env.sh/.csh are in the scripts/ directory of the source tree.

2. System overview

Component Description
Daemon The background service, one per Linux account. All data, AI and execution management live here. Uniqueness is guaranteed by the owner lock (~/.terminux/run/owner.lock)
Core socket ~/.terminux/run/<nodename>/terminux.sock: the connection on which the GUI and CLIs open a session
Lineage socket ~/.terminux/run/<nodename>/lineage.sock: lineage checks, @@, the DQE Viewer, tasks and other requests
GUI (terminux) The terminal window; it never starts the daemon itself, terminux-launch does
DQE Viewer (dqe_viewer) Started locally by the GUI; reads data through the lineage socket
Shell hooks and wrappers Installed into ~/.terminux when the daemon starts; they notify the daemon when commands start and end
Relay (terminux-relay) Local relay on hosts that are not the owner, when several hosts share HOME (not verified)

The daemon accepts connections only from the same Linux account; the identity of a connection is checked by the operating system.


3. Command reference

3.1 terminux-launch

Synopsis: terminux-launch [--no-gui] [--reset] [--version]

Starts or reuses the daemon, then starts the GUI. In the portable bundle, ~/.local/bin/terminux is this command.

Option Description
(none) Make sure the daemon is running, then open the GUI
--no-gui Only make sure the daemon (or relay) is running; do not open the GUI
--reset Print owner.json, ask you to type yes, then remove only ~/.terminux/run/owner.lock. No daemon is stopped
--version Print the version and exit

Behavior:

Owner state Action
No owner Start the daemon in the background (output to daemon.stdout.log) and wait up to 30 seconds for it to become ready; on timeout only warn and open the GUI anyway
Owner starting Wait up to 30 seconds
Owner on this host, process alive Reuse it
Owner on this host, process gone Start the daemon again (the daemon reclaims the stale lock itself)
Owner on another host Check that the owner's TCP port can be reached within 3 seconds, then start a local relay (not verified)
Owner state not ready, unreadable, or unix-only on another host Fail (TERM_DAEMON_OWNER_UNAVAILABLE)
You are in Profile mode but the owner was not started in Profile mode Fail (TERM_DAEMON_OWNER_UNCONTAINED); the owner is neither reused nor stopped

The GUI is searched in this order: TERMINUX_GUI_BIN → <Python environment>/bin/terminux → <Python environment>/../bin/terminux → an ELF executable on PATH (the launcher itself is skipped). If none is found: TERM_LAUNCH_GUI_NOT_FOUND. When the daemon failed to deploy the hooks, or the deployment is disabled, TERM_LAUNCH_WRAPPER_SETUP is printed.

Exit codes: 0 success; 1 failure (messages start with TERM_, see chapter 10).

3.2 terminux (GUI)

Synopsis: terminux [--version] [--self-check] (source installation; for the bundle's terminux see 3.1)

Option Description
(none) Open the Terminux terminal window
--version Print the version and license, then exit
--self-check Start in offscreen mode, check Qt and its plugins, then exit; no window, no daemon connection

After start-up the GUI connects to the Core socket and retries every 3 seconds while it cannot connect.

3.3 terminux-daemon

Synopsis: terminux-daemon [--version] [-h|--help]; equivalent to python -m terminux_engine

Normally started by terminux-launch. All settings come from the environment variables at start-up (7.2).

Exit codes: 0 normal stop (SIGINT/SIGTERM received); 2 the socket paths cannot be resolved (TERM_AGENT_SOCKET_UNAVAILABLE); 3 start-up failed (TERM_SERVICE_START_FAILED); 4 an owner already exists or a legacy daemon was detected (TERM_DAEMON_OWNER_EXISTS, TERM_LEGACY_DAEMON_RUNNING).

python -m terminux_engine.main does not start the daemon; it exits immediately.

3.4 python -m terminux_engine purge

Synopsis: python -m terminux_engine purge --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--force]

Removes the events of a date range from the event records (~/.terminux/ecc/event_store.db). Run it while the daemon is stopped.

Option Description
--from, --to First and last date (inclusive)
--force Really delete. The events of the range are first written as JSONL to ~/.terminux/ecc/archive/ and fsynced; only then are they deleted. Allowed only for the account in TERMINUX_PURGE_ALLOW_USER (default: the current account)
(without --force) Only preview the number of affected events; the database is not changed

Exit codes: 0 success; 1 --force refused; 2 invalid arguments; 5 the daemon runs on another host (TERM_DATABASE_REMOTE_OWNER).

3.5 terminux-relay (not verified)

Synopsis: terminux-relay (no options; normally started by terminux-launch)

Provides the local Core and lineage sockets on a host that is not the owner, reads owner.json for every connection and connects to the owner's TCP ports with a token. A single instance is guaranteed by ~/.terminux/run/<nodename>/relay.pid; the log is relay.log in the same directory.

3.6 terminux-doctor

Synopsis: terminux-doctor [--agent-socket <path>] [--lineage-socket <path>] [--version]

Local diagnostics; calls no provider, runs no EDA tool, and never reads the content of the credentials file. Output is JSON:

Field Content
package_version Package version
agent_socket, lineage_socket Paths of the two sockets
daemon running, state, host, pid
llm_config Whether the legacy Layer 2 configuration exists and is readable, and its source (package template or user)
bundled_knowledge Whether the five bundled knowledge files are readable
plugin_dir Whether the plugin directory exists (0.1.x ships no plugins, so its absence is normal)
eap3_bindings State of the Engineering Work bindings file (when configured)
credentials Source of the credentials file and whether it is safe (owned by you, 0600, regular file); the content is not read
background Whether background RAG rebuilding is disabled; the embedding backend
status ready or attention

Exit codes: 0 ready; 1 attention.

3.7 terminux-qt-check

Synopsis: terminux-qt-check --qt-dir <Qt directory> [--prefix <installation prefix>]

Reads an external Qt installation and checks its version, libraries, QML imports and the xcb and offscreen plugins. With --prefix, it also runs the self-checks of terminux and dqe_viewer in offscreen mode (no window, no daemon connection). When xcb is missing system libraries, it lists the SONAMEs and the known EL9/Ubuntu 24.04 package names, but never installs anything. On multiple hosts, the Qt directory must have the same absolute path on every host.

Exit codes: 0 passed; 1 failed.

3.8 terminux-orfs-run

Synopsis:

terminux-orfs-run --orfs-repo-root <dir> --work-home <dir> --design <name> --platform <name>
                  --variant <name> --design-config <path> --ledger-db <file> --receipt-out <file>
                  [--env-script <file>] [--make-executable <file>] [--openroad-exe <file>] [--yosys-exe <file>]
                  [--timeout-seconds <seconds>] [--receipt-store <file> | --no-receipt] [--version]

Runs one ORFS flow on the host under your account (host-native) and leaves a receipt, an artifact manifest and a quality verdict. Running it as root is refused.

Option Required Default Description
--orfs-repo-root Yes — The ORFS installation root (containing flow/); may be read-only
--work-home Yes — Output directory (ORFS WORK_HOME); must be owned by you; the last level is created if its parent exists
--design Yes — Must equal the name ORFS uses for its output directories (DESIGN_NICKNAME, or DESIGN_NAME when not set)
--platform Yes — For example nangate45
--variant Yes — ORFS FLOW_VARIANT; must not be base; becomes part of the step id orfs-<design>-<variant>
--design-config Yes — Path of config.mk relative to ORFS flow/; must be under flow/
--ledger-db Yes — A ledger file dedicated to this run; must not point to the daemon's ~/.terminux/orchestration/ledger.sqlite (aliases included)
--receipt-out Yes — Where to write the receipt JSON
--env-script No <orfs-repo-root>/env.sh Environment script that makes the EDA tools available; apart from HOME, LANG and PATH, the shell environment is not inherited
--make-executable No make on PATH The make that runs the flow
--openroad-exe, --yosys-exe No ORFS's own rules Explicit ORFS OPENROAD_EXE, YOSYS_EXE
--timeout-seconds No 900 Time limit in seconds
--receipt-store No TERMINUX_EVENT_STORE_PATH or ~/.terminux/ecc/event_store.db Write the receipt into the given event-record file instead
--no-receipt No — Do not write into any event records (--receipt-out is still written); mutually exclusive with --receipt-store

Output: at the end, stdout shows the quality summary and the run id; --work-home contains ORFS's results/, reports/, logs/ and objects/; the receipt is written to --receipt-out. The tool identity (paths and SHA-256 of the env script, make, the design configuration and any explicit tools) is recorded in the receipt.

Exit codes:

Code Meaning
0 The run succeeded and the receipt was written (with --no-receipt, only the run result counts)
1 The run failed (the quality verdict itself does not affect the exit code)
2 Invalid options or environment: running as root, a --work-home you do not own, a --ledger-db that points to the daemon's ledger, a missing env script or make, or the removed --docker-image
3 The run succeeded but the receipt was not written
5 The daemon runs on another host
130/143 Ctrl-C/SIGTERM received (not verified)

The codes that may appear on stderr are listed in 10.3.

3.9 terminux-orfs-report

Synopsis: terminux-orfs-report --receipt <file> --run-id <run_id> --attempt <n> [--role <role>] [--stage <N> [--expect-line <L>] [--view]]

Prints a report only after its hash matches the receipt and the artifact manifest, so what you see is the report of that exact run.

Option Description
--receipt, --run-id, --attempt Required
--role orfs.finish_report (default) or orfs.route_drc_report
--stage N Locate stage N (1-based) of the timing path in the finish report instead
--expect-line L With --stage: require that stage to be on line L
--view With --stage: open the verified report at that line with less -N (needs a terminal)

Exit codes: 0 success; 2 error (message on stderr).

3.10 dqe_viewer

Normally started by the GUI on @@open DQE Viewer with --db, --temporary-db-path and --ipc-endpoint. To run it by hand:

Synopsis: dqe_viewer [options]

Option Description
--version (As the last argument, without a value) print the version and exit
--smoke-exit Build and validate the QML interface, then exit immediately (installation check)
--ipc-endpoint <socket> The daemon's lineage socket; must be combined with a Temporary or Archived data source
--temporary-db-path <file> Temporary data source (the quality database)
--db <file> Compatibility alias for --temporary-db-path
--archived-version-dir <dir> Archived data source
--temporary-retention-days <days> Display context of the Temporary retention period (1–3650)
--workspace archived|temporary|compare Initial workspace (--select-tab is a compatibility alias)
--job-key <job_key> Focus this job in the Temporary workspace (needs a Temporary data source)
--window-size <W>x<H> Window size, for example 1440x900
--screenshot <png> Take a screenshot when the interface is ready, then exit (needs a data source or a built-in sample scenario)
--ui-scenario <name> Scenario of the built-in sample data (for screenshots and visual comparison)

Without --ipc-endpoint and a data source, the Viewer shows the built-in sample data (marked MOCK on screen).

3.11 dqe-scheduled-clean

Synopsis: dqe-scheduled-clean [--db <file>] [--policy <file>] [--dry-run] [--no-vacuum] [--log <file>]

Removes expired jobs according to the Temporary retention policy.

Option Default Description
--db ~/.terminux/dqe/dqe.sqlite The quality database
--policy ~/.terminux/dqe/retention_policy.json The retention policy
--dry-run — Only compute; delete nothing
--no-vacuum — Do not run SQLite VACUUM after deleting
--log ~/.terminux/dqe/scheduled_clean.log The log file

Output is JSON. Exit codes: 0 success; 1 failure; 2 invalid arguments; 3 completed, but the retention policy file was invalid or had a warning and the default policy was used; 5 the daemon runs on another host.

3.12 terminux-cold-backup

Synopsis:

terminux-cold-backup [--agent-socket <path>] [--lineage-socket <path>] create <destination> --source <LABEL>=<abs path> …
terminux-cold-backup verify <backup>
terminux-cold-backup restore <backup> --target <LABEL>=<abs path> …
Subcommand Rules
create The daemon must be stopped (no owner lock); the destination must be an absolute path that does not exist; sources are LABEL=/absolute/path (LABEL: letters, digits, _, - only), must not overlap, must not contain symlinks or special files, and must not contain the destination
verify Recomputes the SHA-256 of every file and compares it with the backup record
restore The daemon must be stopped; the set of target LABELs must equal the backup's, each path must equal the original path at backup time and must not exist now; files are first written to a staging directory and checked against their hashes, then moved into place

Output is JSON. Exit codes: 0 success; 2 a precondition is not met ({"status": "error", "reason": …}). --help only.

3.13 terminux-rollback-check

Synopsis: terminux-rollback-check --event-store <file> --agent-socket <path> --lineage-socket <path>

Checks, in a read-only transaction, whether the data formats in the event records are within the range this version supports: Engineering Work engineering_work.v1, and FlowTask and AnalysisTask schema 1 and 2. It neither switches programs nor restores data. Output is JSON.

Exit codes: 0 compatible (DATA_COMPATIBLE_ONLY); 2 incompatible or unreadable (REJECTED); 5 the daemon runs on another host. --help only.

3.14 terminux-work (not verified)

Synopsis: terminux-work [--agent-socket <path>] [--lineage-socket <path>] [--project <id>] [--profile-path <file>] <subcommand> …

Subcommand Arguments Description
create <profile_id> <package_id> <objective>; [--block] [--method] [--source-root] [--criterion …] [--constraint …] [--expert …] [--review proposal_review|result_review …] Create a work item
create-from-saved-proposal <profile_id> <source_work_id> <source_proposal_id> <expected_proposal_digest> <objective>; [--source-root] [--criterion …] [--constraint …] [--request-id] Create a work item from a previously saved proposal
authorize <work_id>; [--mode PLAN_ONLY|PER_PROPOSAL|BOUNDED_EXPLORATION] (default BOUNDED_EXPLORATION) [--attempts 2] [--provider-dispatches 12] [--tool-launches 5] [--candidate-materializations 2] [--formal-proof-launches N] [--baseline-tool-launches N] [--allowed-method …] [--allowed-change-json …] [--writable-root …] [--stop-condition …] Authorization preview (scope and limits)
approve, continue, get, pause, resume, cancel, takeover <work_id> Approve, advance, show, pause, resume, cancel, take over again
config <work_id> Show the settings actually in effect for this work item
export <work_id> Print a support summary (JSON) with sensitive content masked by default, for reporting problems
list — List work items
answer <work_id> <message>; [--objective] [--method] Answer a question or add information

Needs TERMINUX_EAP3_BINDINGS_FILE; without it, or in Profile mode, the feature is not enabled. --profile-path first selects a Profile for this session. Exit codes: 0 success; 2 error.

3.15 terminux-tool (not verified)

Synopsis: terminux-tool [--format text|json] register <tool_id> [--executable <name> …], … unregister <tool_id>, … list

Registers your own EDA executables (no administrator rights needed) in ~/.terminux/tools/user_tool_catalog.yaml. --executable can be repeated and defaults to the tool id. list shows built-in and user tools. Exit codes: 0 success; any other value is a failure.

3.16 terminux-package-install / -uninstall / -status (not verified)

Synopsis Description
terminux-package-install <source_dir> [--replace] [--format text|json] Copies a directory containing package.yaml into ~/.terminux/packages; --replace replaces an installed package with the same id
terminux-package-uninstall <package_id> [--format text|json] Removes a user package
terminux-package-status [<package_id>] [--activate] [--format text|json] Shows the installed packages and what the running daemon has loaded; --activate asks the daemon to reload them (no restart)

TERMINUX_DISABLE_USER_PACKAGES disables user packages entirely. Exit codes: 0 success; any other value is a failure.

3.17 Package development tools (--help only)

Synopsis Description Exit codes
terminux-package-new <package_id> --root <dir> [--tool <name> …] [--package-version <v>] [--dry-run] [--format text|json] Generates the skeleton of an after-phase package 0 success; 2 error
terminux-package-validate [--root <dir>] [--format text|json] Validates packages offline (without --root, the built-in packages); a handler must be a top-level function of its module 0 valid; 1 invalid; 2 error
terminux-package-test --root <dir> --package <id> [--case <name> …] [--timeout 10] [--format text|json] Runs the package's test cases in an isolated child process 0 all passed; 1 a case failed; 2 error
terminux-package-doctor --root <dir> [--run-cases] [--require-cases] [--junitxml <file>] [--timeout 10] [--format text|json] Combined diagnostics, optionally with JUnit XML output 0 passed; 1 errors or failures; 2 invalid arguments

3.18 terminux-corpus-replay

A replay tool for simulated qualification data, not a real ORFS run; do not use it for actual work. --help only.

3.19 Scripts in the source tree (not verified)

Synopsis Description
terminux-chat <question…> Sends one @@ question from outside the Terminux terminal; every call is a new session; 120-second timeout. When the answer is to open the DQE Viewer, the Viewer is started locally
terminux-lineage-graph [jobs] [--ledger <file>] [--session <S1,S2>] [--output <file>] [--no-open] Produces an artifact lineage graph HTML page and opens it in a browser; --session filters and colors by session
terminux-lineage-graph trace --session <SESS> [--event-store <file>] [--output <file>] [--no-open] Produces the execution trace graph of one session
terminux-dream --user-id <account> --date <yesterday|today|YYYY-MM-DD> Produces the work summary of a given date
terminux-dream --user-id <account> --backfill [--days <N>] Catches up on the summaries of the last N days (default 1)
terminux-build-rag-index [--source-dir <dir>] [--index-dir <dir>] [--chunk-size 512] [--chunk-overlap 64] Builds the RAG index from ~/.terminux/rag_knowledge (default) into ~/.terminux/rag_index (default); needs the rag extra and an embedding setup
source terminux-llm-env.sh / source terminux-llm-env.csh LLM configuration templates; uncomment one backend and source the file; do not put credentials in it

3.20 The portable bundle's install.sh and uninstall.sh

install.sh: ./install.sh [--qt-dir <dir>] [--prefix <dir>] [--no-bin-link] [--yes] [--reinstall] [--force]

Option Default Description
--qt-dir The existing current/qt The Qt SDK directory
--prefix ~/.local/opt/terminux Installation location; one subdirectory per version, current points to the version in use
--no-bin-link — Do not create terminux and terminux-qt-check in ~/.local/bin
--yes — Do not ask for confirmation
--reinstall — Reinstall the same version
--force — Skip only the "unsupported OS" block

The installer checks SHA256SUMS first and refuses to install while a daemon is running. current is switched only after the Qt check passes; on failure the newly created .partial is removed.

uninstall.sh: ~/.local/opt/terminux/current/uninstall.sh (--version <v> | --all) [--purge-data] [--yes]

By default ~/.terminux is kept; --purge-data deletes the data, and even with --yes you must type the full data path to confirm. No rc file is modified; files in ~/.local/bin that were not created by this installation are never removed.


4. Terminux terminal (GUI) reference

4.1 Main window

Area Content
Title bar The shell's title; when the daemon cannot be reached it shows "⚠ Terminux Core not connected (daemon not running)" and the reason
Status bar At start-up "Connecting to Terminux Core…" and "Initialising session…", then "Terminux service ready" (in the interface language)
Menu bar View ▸ Work Panel: show or hide the Engineering Work panel (hidden by default; not verified). Help ▸ About Terminux: version and license; Help ▸ About Qt
Terminal Your shell (PTY); bash loads the hooks automatically
Notification Bar At the top of the window, see 4.4

4.2 Terminal and shell

  • The built-in bash starts with --rcfile ~/.terminux/hooks/bash_rcfile: it first loads your ~/.bashrc and then ~/.terminux/bash_hooks.sh; hooks already loaded by .bashrc are not registered twice.
  • The GUI injects TERMINUX_ACTIVE=1 into the terminal environment, so that the tcsh rc line loads the hooks only inside Terminux.
  • If no hook marker (OSC 133) arrives within 10 seconds after csh or tcsh starts, a setup hint is shown once; no rc file is modified.
  • Input that starts with @@ is not passed to the shell (chapter 6).

4.3 Context menu

Item Shortcut Effect
Copy Ctrl+Shift+C Copy the selected text
Paste Ctrl+Shift+V Paste
Select All — Select everything
Clear Terminal — Clear the screen
Notification Bar ▸ Show — Expand the Notification Bar
Notification Bar ▸ Remove Oldest 10 Messages — Delete the 10 oldest notifications
Notification Bar ▸ Remove All Messages — Delete all notifications
Language ▸ 繁體中文 / English / 简体中文 — Language of the interface and of AI answers; stored in ~/.terminux/preferences.json
Open URL — Appears when the selected text is a URL; opens it in a browser
Font Size + Ctrl+= Larger font
Font Size - Ctrl+- Smaller font
Reset Font Size Ctrl+0 Default font size
Ask AI about this — Ask about the selected text; unavailable without a selection

4.4 Notification Bar

Item Description
Notification types Warn (warnings, for example lineage concerns), AI (AI answers and background analysis results), Gate (quality-gate results), Hint (hints)
Auto-collapse Collapses to a title bar about 5 seconds after the pointer leaves; click the title bar to expand it again
Height The height of the Notification Bar can be adjusted by dragging
Background notifications The GUI fetches new notifications from the daemon about every 1.2 seconds; the daemon buffers at most 500

4.5 Work panel (not verified)

Its title is "工程工作" (Engineering Work); open it with View ▸ Work Panel. The panel's labels are in Chinese; the English column below explains each one.

Field Range / default Description
Profile 檔 — Path of the Profile file; "選 Profile" (Select Profile) selects it for this session
Profile ID, Package — The Profile and package used to create the work item
來源目錄 — Source directory (optional; limited by the Profile)
工程目標 — Objective of the work item
Work ID — The work item to operate on
授權模式 PLAN_ONLY, PER_PROPOSAL, BOUNDED_EXPLORATION Authorization mode for the preview
嘗試上限 0–100, default 1 Attempt limit
Provider 上限 0–1000, default 5 Provider dispatch limit
Tool launch 上限 0–100, default 2 Tool launch limit
候選寫入上限 0–100, default 1 Candidate write limit
補充資料 — Answer to a question raised by the work item

Buttons: 選 Profile (select Profile), 建立 (create), 授權預覽 (authorization preview), 核准 (approve; asks for confirmation), 查詢 (show), 重新接管 (take over again), 暫停 (pause), 恢復 (resume), 取消 (cancel; asks for confirmation), 送出補充 (send answer). Below them the panel shows a status summary of the work item and the daemon's raw reply; "查詢" (show) never advances the work.


5. DQE Viewer reference

5.1 Common elements

Element Description
Workspace tabs Temporary, Archived, Compare
Language menu The header switches between English / 繁體中文 / 简体中文; the initial language follows the terminal's setting
Data source The status bar shows the data source (Terminux daemon for real data; sample data is marked MOCK)
Refresh Refresh reloads the data
Status values Pass, Warn, Fail, Unknown

5.2 Temporary workspace

Section Content and operations
Temporary jobs Quality records of each run, grouped by job; "Search job_key / block / flow"
DQE items The checks of the selected job: DQE_ID, Title, Value, Unit, Status, Date/time, Description, Reference, Source path, attachment count, executable count; filters by status and block; the header shows the total and the count per status
Selected item inspector The full information of the selected item
Evidence / attachment preview Preview of attachments
Check-in (not verified) Check-in dry-run, Check in whole job, Confirm check-in; fields: existing target version (relative path) and workspace root. Runs through the external isvn tool
Temporary retention policy A global policy for all temporary jobs: Edit policy, Save policy; retention N days
Temporary purge Preview selected job purge, Preview expired jobs purge; the purge runs only after you confirm the preview

5.3 Archived workspace (not verified)

Lists the checked-in versions; filter by phase, block and version ("Filter phase / block / version"); select a version to see its DQE items.

5.4 Compare workspace

Section Content
Compare sources Choose the jobs or versions to compare (checkbox comparison not verified in 0.1.1)
Normalized trend The first source is the baseline (100%); the trend of each metric is drawn and data points can be selected
Raw value comparison The raw value of each source
Baseline delta The difference from the baseline
Block filter Filter the series by block
Export Export HTML: save the comparison as HTML

6. @@ reference

6.1 Input rules

  • At the prompt of the Terminux terminal, type @@ followed by a question or a command and press Enter; the line is not passed to the shell.
  • Shell variables are not expanded in the text after @@; write paths as absolute paths.
  • Select text, right-click and choose Ask AI about this to ask about the selected text; such input is always treated as data and never as a / command.
  • Answers appear in the Notification Bar. An LLM backend is required; the Agent is available with openai_compatible and gemini only.

6.2 Keywords that do not go to the AI

Condition Effect
Contains "dqe viewer" (or dqe_viewer, dqeviewer; case-insensitive) together with one of these verbs: open, launch, start, show, 開啟, 打開, 打开, 啟動, 启动, 顯示, 显示 Opens the DQE Viewer (Temporary workspace)
Contains lineage graph, lineage dag, blood line, show lineage, 血緣圖 or 祖譜圖 Produces ~/.terminux/lineage_graph.html and opens it

6.3 Local commands

Known commands that start with / are handled locally by Terminux and never sent to the LLM. Which commands are available depends on the mode:

Mode Available local commands
Normal mode All commands below except run binding. /bind-run and /unbind-run are not local commands in normal mode and are treated as ordinary questions
Profile mode Only /bind-run and /unbind-run. Every other control command returns LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE; nothing is run or sent

So "bind a run, then ask" and "run an explanation or comparison with explicit commands" cannot be used with the same daemon configuration.

Run binding (Profile mode, with run_binding in the Profile)

Command Effect
/bind-run <absolute path of the receipt> Binds one run to this session. The receipt must be your own formal record in the event records, with a matching content hash, and must satisfy the Profile's run_binding rules
/unbind-run Removes all bindings of this session

Plans, proposals and results

Command Effect
/plan-only <goal> Produces a plan; runs nothing and creates no proposal
/plan-propose <plan_id> <step_id> Creates a proposal for one step of the plan; runs nothing
/plans, /plan <plan_id> List and show plans
/use-plan <plan_id> Makes this plan the continuation context for later questions
/cancel-plan <plan_id> <plan_digest> Cancels a plan
/proposals Lists proposals
/approve <proposal_id> <proposal_digest> Approves (a proposal awaiting approval expires after 10 minutes)
/reject <proposal_id> <proposal_digest> Rejects
/execute <proposal_id> <proposal_digest> Runs once; the arguments must equal the proposal's; cannot be repeated
/results Lists execution results
/use-result <result_id> <result_digest> Includes this result in later questions
/clear-result Stops including a result
/approve-plan, /execute-plan, /approve-all Always refused: there is no way to approve or run a whole plan at once

Tasks (not verified)

Command Effect
/profile <absolute path of the Profile> Selects a Profile for this session
/profiles Lists the selected Profiles
/task-create <profile_id> <question…> Creates a flow task draft
/task-start <task_id> <task_digest> Approves and starts
/task <task_id> Shows a task
/task-cancel <task_id> <task_digest> Requests a stop
/tasks Lists all your tasks in this daemon

Engineering Work (not verified)

Command Effect
/work-create <profile_id> <package_id> <objective> Creates a work item
/work-authorize <work_id> <plan|proposal|bounded> Authorization preview
/work-approve <work_id>, /work-continue <work_id> Approve, advance
/work <work_id>, /works Show, list
/work-answer <work_id> <answer or additional information> Answer
/work-pause, /work-resume, /work-cancel, /work-takeover <work_id> Pause, resume, cancel, take over again

6.4 Tools available to the AI

Situation Available tools
Cloud backend (openai_compatible, gemini) Only the two execution-evidence query tools: evidence of one run, and a comparison of the evidence of 2–3 runs. Other tools are not offered to the model and return CLOUD_AGENT_CAPABILITY_DENIED when called
Profile mode The Profile's tools (currently only query_orchestration_evidence)

The AI cannot read files, run shell commands, or create actions awaiting approval by itself. Actions with side effects run only through the explicit commands in 6.3 (normal mode only).


7. Configuration reference

7.1 When settings are read, and precedence

The daemon reads its settings only at start-up; restart it after a change.

Item Precedence (high → low)
LLM router ~/.terminux/llm_router.yaml (used whenever it exists) → environment variables
Credentials The credentials file (TERMINUX_CREDENTIALS_FILE or ~/.terminux/credentials.json) → environment variables with the same names
Legacy Layer 2 settings TERMINUX_LLM_CONFIG_PATH → ~/.terminux/config/llm_config.yaml → package template
STA playbook TERMINUX_PLAYBOOK_PATH → ~/.terminux/ecc/sta_signoff_playbook.yaml
Quality database TERMINUX_DQE_DB_PATH → ~/.terminux/dqe/dqe.sqlite
Interface language ~/.terminux/preferences.json → TERMINUX_PREFERRED_LANGUAGE → zh-Hant

7.2 Environment variables

"Truthy" = 1, true or yes (case-insensitive).

LLM and AI

Variable Default Description
TERMINUX_LLM_BACKEND Unset (AI off) openai_compatible, gemini, llama_cpp
TERMINUX_OPENAI_MODEL deepseek-chat Model of the OpenAI-compatible service
TERMINUX_OPENAI_TIMEOUT_SEC 120 Timeout of each request (seconds)
TERMINUX_GEMINI_MODEL gemini-3.6-flash Gemini model
TERMINUX_LLM_MODEL_PATH — GGUF file for llama_cpp
TERMINUX_LLM_DISABLE_THINKING Unset 1: turn off the thinking mode (for example Qwen3)
TERMINUX_EMBEDDING_BACKEND Depends on the LLM backend noop/none, local, gemini
TERMINUX_EMBEDDING_MODEL_PATH — Model for local embeddings
GEMINI_API_KEY, GEMINI_EMBEDDING_MODEL — Also accepted only with TERMINUX_EMBEDDING_BACKEND=gemini; the model defaults to gemini-embedding-001
TERMINUX_CREDENTIALS_FILE ~/.terminux/credentials.json Location of the credentials file
TERMINUX_DISABLE_CREDENTIAL_FILE Unset 1: never read the credentials file
TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME Off 1: ask the LLM to explain when a lineage check raises a concern
TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME Off 1: ask the LLM to parse a runfile that the fixed-format parser cannot read (sends the complete runfile)
TERMINUX_DISABLE_RAG_BACKGROUND_REBUILD Unset Truthy: do not rebuild the RAG index in the background
TERMINUX_PREFERRED_LANGUAGE — Default before a language is chosen: zh-Hant, en, zh-Hans

Profile mode

Variable Description
TERMINUX_AGENT_TASK_PROFILE_FILE The Profile file (7.5)
TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE The outbound policy file (7.6)
TERMINUX_EGRESS_AUDIT_DIGEST Hash mode of the outbound records (7.7)
TERMINUX_EGRESS_AUDIT_KEYRING_FILE Keyring file for the keyed_persisted mode
TERMINUX_CHAT_QUERY_REQUIRE_ORIGIN Off by default; when on, input from legacy clients that do not label its origin is always treated as data and / commands are not parsed (Profile mode always behaves this way)

Paths, identity and connections

Variable Default Description
TERMINUX_HOME_DIR The home directory in the account database Private base directory for sockets, the owner lock and logs; must be an absolute path that exists, is owned by you and has no group/other permissions
TERMINUX_NODENAME Host name Directory name of run/<nodename>/; ASCII letters, digits and ._- only
TERMINUX_CORE_SOCK, TERMINUX_SOCK — Isolated-deployment overrides of the Core/lineage socket (absolute paths; the parent directory must be owned by you, with no group/other permissions)
TERMINUX_ADVERTISE_HOST The host's FQDN Host name advertised in owner.json
TERMINUX_UNIX_ONLY_IPC 0 1: do not open the TCP relay ports; only 0 and 1 are accepted
TERMINUX_GUI_BIN — GUI executable
TERMINUX_DQE_VIEWER_BIN dqe_viewer next to the GUI DQE Viewer executable
TERMINUX_PROJECT_ID (old name TERMINUX_PROJECT) Unset Declares a project

Data locations

Variable Default
TERMINUX_EVENT_STORE_PATH ~/.terminux/ecc/event_store.db
TERMINUX_ECC_STORE_PATH ~/.terminux/ecc/ecc_store.jsonl
TERMINUX_PLAYBOOK_PATH ~/.terminux/ecc/sta_signoff_playbook.yaml
TERMINUX_DQE_DB_PATH ~/.terminux/dqe/dqe.sqlite
TERMINUX_DQE_DEFAULT_DB_POLICY Unset = the default quality database may be used; deny: refuse to write to the default location unless a path is given explicitly
TERMINUX_ORCHESTRATION_LEDGER_PATH ~/.terminux/orchestration/ledger.sqlite
TERMINUX_LLM_CONFIG_PATH, TERMINUX_PLUGIN_DIR Legacy Layer 2 configuration file; plugin directory (~/.terminux/plugins). Both must be absolute paths
TERMINUX_AGENT_AUDIT_LOG_PATH ~/.terminux/agent_tool_audit.jsonl
TERMINUX_LOG_PATH, TERMINUX_PROJECT_ROOT Pre-exec observation log: TERMINUX_LOG_PATH → <TERMINUX_PROJECT_ROOT>/artifacts/lineage_preexec.log → ~/.terminux/lineage_preexec.log

Switches and limits

Variable Default Description
TERMINUX_LOG_LEVEL ERROR Daemon log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
TERMINUX_AUTO_SETUP_WRAPPERS 1 0: the daemon does not install hooks and wrappers at start-up
TERMINUX_DISABLE_PACKAGES Unset Truthy: stop package dispatch
TERMINUX_DISABLE_USER_PACKAGES Unset Disable user packages
TERMINUX_DISABLE_PLUGINS Unset Truthy: do not subscribe the legacy plugin pipeline
TERMINUX_FLOW_MAX_ACTIVE_TASKS, TERMINUX_FLOW_MAX_PARALLEL_EDA, TERMINUX_FLOW_MAX_PARALLEL_PROVIDER 1 each Concurrency limits of tasks
TERMINUX_EAP3_BINDINGS_FILE Unset Provider bindings for Engineering Work (not verified)
TERMINUX_FORMAL_YOSYS_EXE Unset Yosys used for formal checking (not verified)
TERMINUX_PURGE_ALLOW_USER The current account Account allowed to run purge --force

Variables set by Terminux itself, which you should not set by hand: TERMINUX_ACTIVE, TERMINUX_HOOKS_LOADED, TERMINUX_TRACE_ROOT, TERMINUX_TRACE_SELF, TERMINUX_TRACE_PARENT, TERMINUX_TRACE_JOB, TERMINUX_TRACE_QUEUE, TERMINUX_VENV_PYTHON.

7.3 credentials.json

{
  "TERMINUX_OPENAI_API_KEY": "<key>",
  "TERMINUX_OPENAI_BASE_URL": "https://api.deepseek.com",
  "TERMINUX_GEMINI_API_KEY": "<key>"
}
  • A JSON object; only TERMINUX_OPENAI_API_KEY, TERMINUX_OPENAI_BASE_URL and TERMINUX_GEMINI_API_KEY are recognized, other names are ignored.
  • Must be a regular file (not a symlink) owned by you with permissions exactly 0600; otherwise the whole file is ignored.
  • TERMINUX_OPENAI_BASE_URL defaults to https://api.deepseek.com; a local service is for example http://127.0.0.1:8080/v1.

7.4 llm_router.yaml (not verified)

When ~/.terminux/llm_router.yaml exists, the daemon uses it as the LLM router configuration and no longer builds one from environment variables. Format:

realtime:   {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
background: {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
analysis:   {backend: openai_compatible, model_name: deepseek-chat, api_key: "${MY_KEY}", base_url: "https://api.deepseek.com"}
embedding:  {backend: noop}
Key Fields
realtime, background, analysis (all three required) backend (openai_compatible, gemini, llama_cpp, none), model_name, model_path (llama_cpp), api_key, base_url (openai_compatible)
embedding (required) backend (gemini, local, noop), model_name, model_path, api_key
  • ${VARIABLE} in a string is expanded from the environment; unset variables are left as they are.
  • With this file, the router takes its keys from the api_key fields in the file and does not read the credentials file; avoid writing keys directly into the file.
  • As long as this file exists, data may be sent to the providers configured in it (see User Guide 13.2).

7.5 Profile file

Given by TERMINUX_AGENT_TASK_PROFILE_FILE. Must be a UTF-8 JSON file owned by you, with permissions 0600, no larger than 64 KiB. Anything invalid makes the whole file invalid, and every AI request that would leave the machine is refused.

Key Required Type and rules
profile_id Yes Non-empty string
tools Yes Array of unique strings; may contain only query_orchestration_evidence
context_sections Yes Array of unique strings; may contain only conversation_history
allowed_runs Yes Object: keys are run ids (starting with run_, otherwise letters, digits or _), values are positive integer attempts. May be {}
run_binding No Object with four required keys (below); without it /bind-run cannot be used

No other key is allowed.

run_binding key Rule
max_runs_per_session Integer 1–8
require_runner Non-empty string without leading or trailing spaces; receipts of terminux-orfs-run have host_native
allowed_designs Non-empty array of unique strings, each <platform>/<design> (each part: letters, digits, _, - only)
max_age_sec Integer 1–31536000 (maximum age of the receipt's completion time, in seconds)

In Profile mode the instructions given to the AI are fixed by Terminux and cannot be changed through the Profile file.

7.6 Outbound policy file

Given by TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE. Must be a regular file owned by you, with permissions 0600, no larger than 64 KiB.

v2 (recommended):

Key Rule
policy_version terminux.egress_policy.v2
approval_mode structural_c2 (allowed by data class and limits) or exact_digest (only the listed request-content hashes are allowed)
endpoint Must equal <TERMINUX_OPENAI_BASE_URL>/v1/chat/completions
model Must equal TERMINUX_OPENAI_MODEL
allowed_payload_sha256 Array of hashes; must be empty with structural_c2
approved_data_classes Data classes that may be sent, from: system_instructions, learner_text, conversation_history, tool_schema, tool_call, evidence_bundle, model_output, budget_summary, timing_path_evidence
limits All five keys required (below)
non_agent_egress Must be deny
limits key Valid range
learner_text_max_chars 1–65536
history_max_turns 0–200
history_max_chars 0–262144
model_output_max_chars 1–262144
requests_per_turn 1–8
  • timing_path_evidence (per-stage timing-path data) is never sent unless listed in approved_data_classes; evidence_bundle does not cover it.
  • The old v1 shape (only the four keys endpoint, model, allowed_payload_sha256, approved_data_classes) works only with a digest allow-list; use v2 for new configurations.

7.7 Hash modes of the outbound records

TERMINUX_EGRESS_AUDIT_DIGEST decides how each outbound record captures the integrity of the request content (the record itself never contains the content):

Value Description
metadata_only No content hash; not suitable when outbound records are required
plain_sha Records the SHA-256 of the request content
keyed_ephemeral HMAC with a key generated at daemon start-up and never written to disk; comparable within one daemon run, not across restarts
keyed_persisted HMAC with the administrator's keyring from TERMINUX_EGRESS_AUDIT_KEYRING_FILE, plus a MAC over each whole record; verifiable after a daemon restart. If the keyring content changes, sending is refused; rotating the key requires a daemon restart

With a structural_c2 policy, one of the last three is required. Records are kept in ~/.terminux/run/<nodename>/egress_audit/<date>.jsonl for 90 days.

7.8 STA playbook

  • Template: terminux_engine/ecc/templates/sta_signoff_playbook.yaml in the package; deploy it to ~/.terminux/ecc/ (see User Guide 4.5).
  • The top-level key is playbook:, containing id, name, description, playbook_type, version, milestone_model and stage_specs.
  • Without a playbook, stage tracking, quality gates and hints are off and nothing else is affected; the daemon log contains TERM_ECC_PLAYBOOK_UNAVAILABLE.

7.9 preferences.json

~/.terminux/preferences.json: {"preferred_language": "zh-Hant"}, with the value zh-Hant, en or zh-Hans. Written by the context menu's Language; read or write failures fall back to zh-Hant.

7.10 package.yaml (user packages, not verified)

package:
  id: my_package             # globally unique
  version: 0.1.0
  api: terminux.package.v1
schema: 1
when:
  tools: [orfs]              # dispatched after these tools finish
phases:
  after: after.run           # <module>.<function>; the function must be a top-level def of the module
permissions:
  services: {file: read, store: write, notify: emit}

Actions can also be defined under actions: (handler, timeout_sec, description, parameters). Validate offline with terminux-package-validate.

7.11 Hooks and wrappers installed by the daemon

Location Content
~/.terminux/bin/ Wrappers for EDA tools (symlinks to _terminux_wrapper), terminux-notify, terminux-tcsh-postcmd
~/.terminux/hooks/bash_env, bash_rcfile bash integration
~/.terminux/bash_hooks.sh, ~/.terminux/tcsh_hooks.csh Hooks to source from an rc file

Installation is idempotent: files with the same name that you put into ~/.terminux/bin, or symlinks pointing elsewhere, are not overwritten, and no rc file is modified.


8. Files and data reference

8.1 ~/.terminux

~/.terminux/
├── credentials.json            credentials (0600)
├── preferences.json            interface language
├── llm_router.yaml             optional router configuration
├── terminux.db                 legacy command records
├── agent_tool_audit.jsonl      record of AI tool use
├── lineage_graph.html          most recent lineage graph
├── lineage.<nodename>.jsonl    execution records of the wrappers (lineage.jsonl in older versions)
├── lineage_preexec.log         pre-exec observation log
├── ecc/                        event records event_store.db, ECC snapshots, playbook, archive/
├── dqe/                        quality database dqe.sqlite, retention_policy.json, scheduled_clean.log
├── lineage/                    ledger.jsonl, artifact_manifests/, branch_tree.jsonl
├── orchestration/              the daemon's execution state ledger.sqlite
├── memory/                     search index search_index.db
├── rag_knowledge/, rag_index/  your RAG knowledge and index
├── tools/                      user_tool_catalog.yaml
├── packages/                   user packages
├── plugins/                    plugin directory (empty in 0.1.x)
├── bin/, hooks/, bash_hooks.sh, tcsh_hooks.csh   hooks and wrappers
└── run/
    ├── owner.lock/owner.json   the daemon's host and state
    └── <nodename>/             terminux.sock, lineage.sock, daemon.log, daemon.stdout.log,
                                relay.pid, relay.log, egress_audit/ (Profile mode)

~/.terminux must be a directory owned by you, not writable by group or other, and not a symlink.

8.2 Execution receipt (receipt JSON)

Main fields of the JSON written by terminux-orfs-run --receipt-out:

Field Content
schema_version Format version
run_id, step_id, attempt Execution identity; run_id is run_ followed by 32 hexadecimal characters; step_id is orfs-<design>-<variant>
tool_id, adapter_id, adapter_version Tool and adapter identity
tool_version_evidence Evidence of the tool version and identity
started_at, finished_at Start and end time (epoch seconds)
process_exit_code, timed_out, termination_reason How the run ended
stdout_tail, stderr_tail Last lines of the output
execution_lifecycle_status, dispatch_status, evidence_status State of the execution, the package dispatch and evidence readiness
output_roots Output root directories
artifact_manifest_reference, artifact_manifest_id, artifact_capture_status Reference to the artifact manifest and the capture status
adapter_metadata Includes runner (host_native), platform, design and more

/bind-run needs this file; the same receipt must also exist in the event records with a matching content hash.

8.3 owner.json

~/.terminux/run/owner.lock/owner.json (0600): state (starting/ready), host, nodename, pid, instance_id, version, started_at, the TCP relay's core_port, lineage_port and token (or unix_only_ipc), the result of the hook deployment, and a start-up identity consisting only of enumerated values and hashes. token authenticates the TCP relay; do not share it.

8.4 Logs

File Content Rotation
run/<nodename>/daemon.log The daemon's structured messages after it acquired ownership 10 MiB, 3 backups
run/<nodename>/daemon.stdout.log Daemon output collected by terminux-launch (before ownership) —
run/<nodename>/relay.log, relay.stdout.log Relay 10 MiB, 3 backups
run/<nodename>/egress_audit/<date>.jsonl Outbound records in Profile mode (metadata and hashes only) Kept 90 days
agent_tool_audit.jsonl Record of AI tool use —
dqe/scheduled_clean.log Scheduled DQE purge —

By default the daemon logs ERROR messages only, so daemon.log is empty during normal operation.


9. Quality checks (DQE) reference

9.1 ORFS checks

Check Description Source Mandatory
orfs_manifest_integrity Identity and hash of the artifact manifest Artifact manifest Yes
orfs_artifact_completeness The required artifacts are present and stable Artifact manifest Yes
orfs_final_deliverables The final layout, DEF, database and netlist were produced Artifact manifest Yes
orfs_process_exit_code Exit code of the tool process is 0 Run result Yes
orfs_setup_wns Setup WNS ≥ 0 (ns) 6_finish.rpt Yes
orfs_setup_tns Setup TNS ≥ 0 6_finish.rpt No
orfs_setup_violation_count Setup-violating paths = 0 6_finish.rpt Yes
orfs_hold_violation_count Hold-violating paths = 0 6_finish.rpt Yes
orfs_max_slew_violation_count Max-transition violations = 0 6_finish.rpt No
orfs_max_fanout_violation_count Max-fanout violations = 0 6_finish.rpt No
orfs_max_cap_violation_count Max-capacitance violations = 0 6_finish.rpt No
orfs_route_drc_violation_count Detailed-route DRC violations = 0 5_route_drc.rpt Yes
orfs_log_error_markers Error markers in the log = 0 ORFS log (6_report.log) Yes
orfs_log_warning_markers Warning markers in the log = 0 ORFS log (6_report.log) No

The thresholds have their signoff meaning (for example, WNS below 0 is a violation); they are not ORFS's per-design regression bounds.

9.2 Rules

  • Each check results in pass, warn, fail or unknown (unreadable or undecidable).
  • Overall result: any mandatory fail → fail; otherwise any warn → warn; otherwise any mandatory unknown → unknown; otherwise pass. An unknown in a non-mandatory check never turns the overall result into pass.
  • A notification is sent when the overall result is warn, fail or unknown.
  • The checks follow fixed rules only: no LLM, no root-cause analysis, no rerun, no design change.

9.3 Fields of a quality record

Each row in the DQE Viewer corresponds to a record in the quality database. Main fields: ProjectCode, Phase, Block, Stage, Flow, Version, DQE_ID, VALUE, UNIT, STATUS, DATE_TIME, Reporter, PATH, attachment and executable (5 MiB each), job_key (format YYYYMMDD_HHMMSS_NNN), and the execution identity (run id, step id, attempt). A dispatch that is sent again is not written twice.


10. Messages and codes

10.1 Exit codes

Command Exit codes
terminux-launch 0 success; 1 failure
terminux-daemon 0 normal stop; 2 socket paths cannot be resolved; 3 start-up failed; 4 an owner or a legacy daemon exists
terminux-doctor 0 ready; 1 attention
terminux-qt-check 0 passed; 1 failed
terminux-orfs-run 0, 1, 2, 3, 5, 130, 143 (3.8)
terminux-orfs-report 0 success; 2 error
python -m terminux_engine purge 0 success; 1 --force refused; 2 invalid arguments; 5 owner on another host
dqe-scheduled-clean 0 success; 1 failure; 2 invalid arguments; 3 completed with a degraded policy; 5 owner on another host
terminux-cold-backup 0 success; 2 a precondition is not met
terminux-rollback-check 0 compatible; 2 incompatible or unreadable; 5 owner on another host
terminux-work, terminux-package-new 0 success; 2 error
terminux-package-validate 0 valid; 1 invalid; 2 error
terminux-package-test 0 all passed; 1 a case failed; 2 error
terminux-package-doctor 0 passed; 1 errors or failures; 2 invalid arguments

10.2 Daemon and launcher codes

Code Where Meaning and what to do
TERM_DAEMON_OWNER_EXISTS Daemon stderr (exit 4) Another daemon holds the owner lock (possibly on another host). Use or stop it on its host; use terminux-launch --reset only after confirming that it no longer exists
TERM_LEGACY_DAEMON_RUNNING Daemon stderr (exit 4) A legacy daemon still runs on the old path ~/.terminux/terminux.sock; stop it first
TERM_AGENT_SOCKET_UNAVAILABLE Daemon (exit 2) The socket path cannot be used; the message includes one of the detailed codes below, the UID and the expected path
TERM_RUNTIME_DIR_MISSING, _NOT_A_DIRECTORY, _IS_SYMLINK, _WRONG_OWNER, _TOO_PERMISSIVE, _UNAVAILABLE Same ~/.terminux does not exist, is not a directory, is a symlink, is not owned by you, is writable by group/other, or cannot be used. Fix the permissions or the path; Terminux never deletes existing files on its own
TERM_HOME_DIR_UNRESOLVED, TERM_HOME_DIR_UNAVAILABLE Same The home directory cannot be found in the account database, or cannot be used
TERM_AGENT_SOCKET_PATH_OCCUPIED Same A regular file, directory or symlink occupies the socket path
TERM_SOCKET_PATH_TOO_LONG Same The socket path is too long (the Unix socket limit is about 107 bytes); shorten TERMINUX_HOME_DIR or the override path
TERM_AGENT_SOCKET_OVERRIDE_INVALID Same The value of TERMINUX_CORE_SOCK, TERMINUX_SOCK or TERMINUX_HOME_DIR is invalid
TERM_AGENT_SOCKET_LEGACY_PATH_REJECTED Same The override value is the retired /tmp/terminux.sock or /run/user/<uid>/terminux/terminux.sock
TERM_LEGACY_SOCKET_OVERRIDE_IGNORED daemon.log (WARNING) The override value equals the old default path; it was ignored and the current rules were used
TERM_NODENAME_INVALID Daemon, CLIs TERMINUX_NODENAME contains characters that are not allowed
TERM_UNIX_ONLY_IPC_INVALID Daemon TERMINUX_UNIX_ONLY_IPC is neither 0 nor 1
TERM_SERVICE_START_FAILED Daemon (exit 3) Start-up failed; restart with TERMINUX_LOG_LEVEL=INFO and read daemon.log
TERM_SOCKET_BIND_FAILED, TERM_LINEAGE_LISTENER_NOT_STARTED, TERM_SOCKET_CONFLICT_HINT daemon.log The lineage socket could not be created; the AI and background analysis do not start. If you can connect to it, someone is using it, so do not delete it; remove it by hand only after confirming that it is a leftover
TERM_DAEMON_OWNER_LOCK_RETAINED daemon.log At shutdown the daemon could not confirm that the data was closed cleanly, and keeps the owner lock on purpose
TERM_EVENT_STORE_UNAVAILABLE daemon.log The event records cannot be opened or written; package dispatch and event recording stop. Fix ~/.terminux/ecc and restart
TERM_ECC_PLAYBOOK_UNAVAILABLE daemon.log No STA playbook (an optional feature); nothing else is affected
TERM_EGRESS_AUDIT_UNAVAILABLE daemon.log The outbound-record directory of Profile mode cannot be used; sending is refused
TERM_DATABASE_REMOTE_OWNER Commands that open the database directly (exit 5) The daemon runs on another host; run the command there
TERM_DAEMON_OWNER_UNAVAILABLE terminux-launch, relay The owner state is not ready, cannot be read, or cannot be reached over TCP
TERM_DAEMON_OWNER_UNCONTAINED terminux-launch You are in Profile mode but the existing daemon was not started in Profile mode; stop it and restart with the Profile settings
TERM_DAEMON_OWNER_IDENTITY_MISMATCH terminux-launch The Profile/policy loaded by the existing daemon differs from yours (Learner build)
TERM_LAUNCH_DAEMON_NOT_READY terminux-launch Still not ready after 30 seconds; the hooks may not be deployed yet
TERM_LAUNCH_WRAPPER_SETUP terminux-launch The hook deployment failed or is disabled; read daemon.log as the message says
TERM_LAUNCH_GUI_NOT_FOUND terminux-launch The GUI executable cannot be found
TERM_LAUNCH_RELAY_START_FAILED, TERM_LAUNCH_RELAY_START_TIMEOUT, TERM_LAUNCH_RELAY_STOP_TIMEOUT terminux-launch The relay failed to start, timed out, or stopping the old relay timed out
TERM_LAUNCH_OWNER_DIRECTORY_UNSAFE terminux-launch --reset The owner lock is not a directory owned by you; deletion is refused
TERM_LAUNCH_FAILED terminux-launch Other failures; the reason follows

10.3 terminux-orfs-run codes

Code Meaning
NATIVE_RUN_AS_ROOT_REFUSED Running as root (exit 2)
NATIVE_SETUP_INVALID The env script or make cannot be found, or another execution setting is invalid (exit 2)
DOCKER_EXECUTION_REMOVED The removed --docker-image was used (exit 2)
LEDGER_SHARED_WITH_DAEMON --ledger-db points to the daemon's ledger (exit 2)
EXECUTION_RECEIPT_NOT_DURABLE The run succeeded but the receipt was not written into the event records (exit 3)
PACKAGE_RECORD_STORE_UNAVAILABLE The event records cannot be opened or written, so the package records (including the timing-path evidence) cannot be stored; the meaning of the exit code is unchanged
EXECUTION_INTERRUPTED, EXECUTION_INTERRUPTED_BEFORE_START A signal arrived during the run or before it started
EXECUTION_CLEANUP_UNCONFIRMED It could not be confirmed that the flow's process group ended, so no receipt is written
EXECUTION_FINALIZATION_INTERRUPTED, SIGNAL_DURING_FINALIZATION, SIGNAL_AFTER_PERSISTENCE A signal arrived during finalization or after the receipt was written; a signal that arrives after the receipt is complete does not change the exit code
TERMINUX_DESIGN_NICKNAME_MISMATCH --design differs from the design name resolved by ORFS; the flow stops before it starts
TERMINUX_FORBIDDEN_ENV The environment or the env script sets a variable that is not allowed: MAKEFLAGS, GNUMAKEFLAGS, MAKEOVERRIDES, MAKEFILES, DESIGN_CONFIG, FLOW_VARIANT, WORK_HOME, IN_NIX_SHELL, and OPENROAD_EXE/YOSYS_EXE unless given with --openroad-exe/--yosys-exe. These values may come only from the arguments assembled by Terminux
TERMINUX_NATIVE_TOOL_MISSING, TERMINUX_NATIVE_TOOL_DIGEST_MISMATCH, TERMINUX_NATIVE_TOOL_REALPATH_CHANGED A declared tool does not exist, or the content or real path of a tool file changed during the run

10.4 Codes in @@ answers

Code Meaning
RUN_BOUND Bound (or already bound)
RUN_UNBOUND Bindings removed
RUN_NOT_BOUND No run is bound to this session
RUN_BIND_DISABLED No valid session, or the Profile has no run_binding
RUN_BIND_USAGE Wrong syntax (/bind-run needs one absolute path; /unbind-run takes no arguments)
RUN_BIND_UNSUPPORTED Unsupported argument (for example last); give the absolute path of the receipt
RUN_BIND_RECEIPT_UNREADABLE The receipt path is not absolute, cannot be read, or is not a regular file
RUN_BIND_RECEIPT_INVALID The receipt is not valid JSON, or lacks run_id, attempt or adapter_metadata
RUN_BIND_NOT_PROJECTED The event records contain no formal receipt for this run
RUN_BIND_FOREIGN_OR_UNTRUSTED The same run has records not written by you, or a record's content hash does not match
RUN_BIND_ATTEMPT_MISMATCH The event records have no such attempt
RUN_BIND_AMBIGUOUS The same run/attempt matches several records
RUN_BIND_OUTSIDE_POLICY The runner, <platform>/<design> or receipt time does not satisfy the Profile's run_binding
RUN_BIND_LIMIT max_runs_per_session reached
RUN_BIND_AUTHORITY_UNAVAILABLE The event records cannot be used
RUN_BIND_POLICY_UNAVAILABLE The outbound policy cannot be read; binding is refused
TASK_POLICY_INVALID The Profile file is invalid (format, permissions, size); every AI request that would leave the machine is refused
PROFILE_PROVIDER_UNSUPPORTED Profile mode supports the openai_compatible backend only; no request was sent
LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE In Profile mode only /bind-run and /unbind-run are available; nothing was run or sent
CLOUD_AGENT_CAPABILITY_DENIED With a cloud backend, the AI tried to use a tool that is not allowed
PLAN_BATCH_CONTROL_NOT_SUPPORTED /approve-plan, /execute-plan or /approve-all was used
PROPOSAL_PENDING_LIMIT_EXCEEDED This session already has the maximum number of proposals awaiting approval (16)

10.5 Task codes (not verified)

Code Meaning
TASK_NOT_FOUND_OR_OUT_OF_SCOPE The task does not exist or is outside your scope (deliberately not distinguished)
TASK_DIGEST_MISMATCH task_digest does not match the draft
TASK_ORIGIN_SESSION_REQUIRED Only the session that created the task can start it
TASK_INSTANCE_EXPIRED Not a task of the current daemon (history from before a restart); read-only
TASK_BUSY The slots are taken by other tasks; no authorization was consumed
TASK_WORKER_UNCONFIRMED The previous action has not been confirmed as finished, so its slot cannot be reused
TASK_ALREADY_STARTED The same task cannot be started twice
TASK_REVALIDATION_FAILED Revalidation at start did not match
TASK_RUN_ACCESS_UNVERIFIABLE It cannot be proven that you may access the given run
TASK_PROPOSAL_CONTROL_DENIED Proposals inside a task cannot be operated with the single-proposal commands
TASK_BUDGET_EXHAUSTED, TASK_DEADLINE_EXCEEDED Budget or deadline used up; no more work is dispatched
TASK_EVIDENCE_INVALID Records, scope or hashes are inconsistent or missing
TASK_OUTCOME_UNCONFIRMED It is unknown whether an action completed; it is never resent automatically
TASK_INPUT_INVALID Invalid input at creation
TASK_PROVIDER_UNAVAILABLE The LLM provider needed for analysis is unavailable (showing and cancelling still work)
LEGACY_DOCKER_EXECUTION_DISABLED, LEGACY_HOST_RUNNER_EXECUTION_DISABLED Old execution modes are disabled; historical tasks can still be read

11. Limits, timeouts and defaults

Item Value
terminux-launch waiting for the daemon 30 seconds
GUI reconnecting to the daemon Every 3 seconds
GUI fetching background notifications About every 1.2 seconds; 1.5-second timeout each
Daemon notification buffer 500 notifications
Notification Bar auto-collapse About 5 seconds after the pointer leaves
Lineage check (GUI wait) 30 seconds
Hook notifying the daemon (terminux-notify) 2 seconds; silently skipped when the daemon is not running
csh/tcsh hook setup hint When no marker arrives within 10 seconds after start-up
terminux-chat 120 seconds; 5 seconds to open the session
OpenAI-compatible request 120 seconds (TERMINUX_OPENAI_TIMEOUT_SEC)
terminux-orfs-run 900 seconds (--timeout-seconds)
Explaining one run (explain_run) 300 seconds
Proposals awaiting approval Expire after 10 minutes; at most 16 per session
Execution results Kept 30 minutes (in memory only)
Run bindings 1–8 per session (Profile setting); cleared when the daemon restarts
Concurrent tasks Each limit defaults to 1
Profile and outbound policy file size 64 KiB
Daemon/relay log Rotated at 10 MiB, 3 backups
Wrapper execution records gzip backup above 10 MiB, 3 backups; checked every 300 seconds
Outbound records Kept 90 days
Attachment and executable in a quality record 5 MiB each
DQE Viewer retention setting 1–3650 days
Single message on the Core socket 1 MiB
Default timeout of package tests 10 seconds
terminux-work authorize defaults attempts 2, provider dispatches 12, tool launches 5, candidate materializations 2

12. Glossary

Term Description
Attempt The number of an attempt within one run
Artifact manifest A mechanical record of a run's output files (path, size, SHA-256); immutable once written
Baseline The run used as the reference in a comparison
Cloud backend openai_compatible or gemini; with it the AI can only query evidence
Daemon The background service, one per Linux account
DQE Design Quality Evidence: quality verdicts produced by fixed rules
Engineering Work Multi-round engineering work under an overall budget (not verified)
Event records ~/.terminux/ecc/event_store.db; every formal record is only ever appended
Flow task A bounded task with fixed steps: baseline → explanation → one change → candidate → comparison (not verified)
Host-native Tools run directly on the host under the user's account
Job / job_key A group of quality records of one run in DQE; job_key has the format YYYYMMDD_HHMMSS_NNN
Lineage Data lineage: which inputs a step actually read and which outputs it wrote
Normal mode Operation without a Profile; all local commands except run binding are available
Owner The daemon that holds the owner lock and is serving
Package An extension unit: package.yaml plus Python code
Profile mode A mode in which the administrator restricts the AI's scope and the data sent out; any invalid setting means refusal
Proposal An action with side effects awaiting approval; run once after approval
Receipt The formal result record of one tool execution
Relay Local relay on a host that is not the owner
Session The identity a GUI or CLI gets when it connects to the daemon; it ends when the connection closes
Temporary / Archived DQE records not yet checked in / versions checked in through isvn