Skip to main content

User Guide

User Guide

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

Contents

  1. Before you start
  2. Quick start
  3. Installation
  4. Configuration
  5. Starting, stopping and status
  6. Using the Terminux terminal
  7. Lineage checks
  8. Running ORFS
  9. Quality checks (DQE) and the DQE Viewer
  10. Using the AI
  11. Bounded tasks and Engineering Work (not verified)
  12. Other tools
  13. Data, privacy and security
  14. Maintenance
  15. Troubleshooting
  16. FAQ
  17. Appendix

1. Before you start

1.1 What Terminux is

Terminux is a terminal and personal background service for IC design engineers. You keep using bash or tcsh in the Terminux terminal; the background service (the daemon) checks data lineage when you run EDA commands, leaves verifiable evidence and a quality verdict after every run, and lets an AI answer your questions using only that evidence.

Each Linux account has one daemon, and data is kept in your own ~/.terminux. As long as no LLM provider is configured, Terminux sends no data to any provider.

1.2 Components you will use

Component Command Purpose
Terminux terminal (GUI) terminux Terminal window, Notification Bar, AI questions
Launcher terminux-launch Starts or reuses the daemon, then opens the GUI
DQE Viewer Opened with @@open DQE Viewer Reviews and compares quality records
ORFS runs terminux-orfs-run Runs one ORFS flow on the host under your account
Verified report terminux-orfs-report Prints a report verified against the receipt and the artifact manifest
Diagnostics terminux-doctor Checks the installation and the daemon

The full list of commands is in Appendix A.

1.3 Terms

Term Meaning
Daemon The Terminux service that runs in the background, one per Linux account
Receipt The formal result record of one tool execution: run id, attempt, tool identity, exit code and a reference to the artifact manifest
Artifact manifest An objective record of a run's output files (path, size, SHA-256); immutable once written
DQE Design Quality Evidence: quality verdicts on a run's results, produced by fixed rules
@@ Typing @@your question at the terminal prompt hands the question to Terminux's AI instead of the shell
Profile mode An administrator-configured mode that restricts the AI's scope and the data sent out
Host-native EDA tools run directly on the host under your own account, without a container

2. Quick start

STOP: do not extract or install until the archive and its checksum have been verified against an independently trusted source.

Using the portable bundle, DeepSeek (an OpenAI-compatible service) and nangate45/gcd as an example:

  1. Make sure the host is Linux x86_64 and Qt 6.7 or later (default Desktop gcc 64-bit components) is installed.

  2. Download terminux-<version>-linux-x86_64.tar.gz and SHA256SUMS, verify them and install:

    Follow the Installation tutorial for the independent checksum, STOP and subsequent installation sequence.

  3. Create the credentials file (its permissions must be 0600):

    mkdir -p ~/.terminux
    cat > ~/.terminux/credentials.json <<'JSON'
    {"TERMINUX_OPENAI_API_KEY": "<your API key>", "TERMINUX_OPENAI_BASE_URL": "https://api.deepseek.com"}
    JSON
    chmod 600 ~/.terminux/credentials.json
    
  4. Choose the backend and start:

    export TERMINUX_LLM_BACKEND=openai_compatible
    terminux
    
  5. Run ORFS in the Terminux terminal (replace the paths with your ORFS installation):

    terminux-orfs-run --orfs-repo-root /path/to/OpenROAD-flow-scripts \
      --work-home ~/orfs-runs/run1 --design gcd --platform nangate45 --variant run1 \
      --design-config ./designs/nangate45/gcd/config.mk \
      --ledger-db ~/orfs-runs/run1-ledger.sqlite --receipt-out ~/orfs-runs/run1-receipt.json
    

    With the portable bundle, terminux-orfs-run is in ~/.local/opt/terminux/current/venv/bin/; use the full path or add that directory to PATH.

  6. Type @@open DQE Viewer to see the quality results. When you ask, include the run id printed at the end of step 5, for example @@Which checks of run_… are WARN or FAIL, and where is the evidence? (replace run_… with the full run id, which is run_ followed by 32 hexadecimal characters). Without a run id in the question and without a bound run, the AI answers that it has no evidence to query (binding a run requires Profile mode, see 10.3).

The following chapters explain each step in detail.


3. Installation

STOP: do not extract or install until the archive and its checksum have been verified against an independently trusted source.

3.1 System requirements

Item Requirement
Operating system Linux x86_64. The bundle's install guide lists Ubuntu 24.04, RHEL/Rocky/AlmaLinux 9 and CentOS Stream 9; 0.1.1 was verified on Ubuntu 24.04 only
C library The bundle needs glibc 2.34 or later and a libstdc++ that provides GLIBCXX_3.4.29
Qt Qt 6.7 or later, Qt 6 series, default Desktop gcc 64-bit components; not bundled. It must include the libraries, QML imports, and the xcb and offscreen platform plugins
Graphics A working X11 session, plus the xcb system libraries (see 3.2)
Python Building from source needs Python 3.12 or later and uv; the bundle includes Python 3.12
Build tools Building the GUI from source needs CMake 3.16 or later and a C++17 compiler
Privileges No root, sudo or Docker required

3.2 Option 1: portable bundle

Download and verify

Use the independently authenticated checksum and STOP procedure in the Installation tutorial. A check that ignores missing entries does not prove the intended archive was checked.

System libraries: ask your system administrator for the X11/xcb packages. The installer runs terminux-qt-check, which lists the libraries that are actually missing, but it never installs anything.

Purpose EL9 Ubuntu 24.04
xcb cursor xcb-util-cursor libxcb-cursor0
xcb utility, image, keysyms, renderutil, wm xcb-util, xcb-util-image, xcb-util-keysyms, xcb-util-renderutil, xcb-util-wm libxcb-util1, libxcb-image0, libxcb-keysyms1, libxcb-render-util0, libxcb-icccm4
XKB libxkbcommon, libxkbcommon-x11 libxkbcommon0, libxkbcommon-x11-0
X11/xcb libX11, libX11-xcb, libxcb libx11-6, libx11-xcb1, libxcb1

Install: first stop the daemon this account is running (the installer does not stop it; with a shared HOME and the daemon on another host, stop it on that host).

After the identity check passes, use the installer sequence in the Installation tutorial.

Option Effect
--qt-dir <Qt directory> The Qt SDK (for example …/6.7.3/gcc_64). Can be omitted when current/qt already exists
--yes Do not ask for confirmation
--prefix <path> Installation location, default ~/.local/opt/terminux
--no-bin-link Do not create the entries in ~/.local/bin
--reinstall Reinstall the same version (by default the installer stops when the version is already installed)
--force Skips only the "unsupported OS" block; it never skips the architecture, ABI, Qt or running-daemon checks

After installation:

  • Each version is installed in ~/.local/opt/terminux/<version>, and current points to the version in use. current is switched only after the Qt check passes; on failure it is left unchanged.
  • Upgrades keep the old versions.
  • ~/.local/bin receives only two entries: terminux (runs terminux-launch, which starts the daemon and opens the GUI) and terminux-qt-check. The other commands are in ~/.local/opt/terminux/current/venv/bin/; use their full path or add that directory to your PATH.
  • The bundle contains only the basic dependencies and does not include the Gemini, local-llm (llama.cpp), RAG or Anthropic extras. To use the Gemini backend or build a RAG knowledge base, install the corresponding packages into the bundle's Python environment yourself. The openai_compatible backend needs no extra package.
  • No rc file is modified.

Add the entries to PATH

export PATH="$HOME/.local/bin:$PATH"          # bash
setenv PATH "$HOME/.local/bin:$PATH"          # tcsh

Check Qt again

~/.local/bin/terminux-qt-check --qt-dir ~/.local/opt/terminux/current/qt --prefix ~/.local/opt/terminux/current

3.3 Option 2: from source

Python package (at the root of the source tree):

uv venv --python 3.12 .venv
source .venv/bin/activate              # tcsh: source .venv/bin/activate.csh
uv pip install './engine[gemini]'
Extra When you need it
gemini The Gemini backend, or Gemini embeddings
local-llm The llama_cpp backend
rag Building a RAG knowledge base with terminux-build-rag-index
anthropic Only the retained legacy notification path; normally not needed

The openai_compatible backend needs no extra package.

GUI and DQE Viewer: install them into the same prefix as the Python environment.

cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.7.3/gcc_64 -DTERMINUX_BUILD_TESTS=OFF
cmake --build build
cmake --install build --prefix "$VIRTUAL_ENV"

This installs $VIRTUAL_ENV/bin/terminux (GUI) and $VIRTUAL_ENV/bin/dqe_viewer (DQE Viewer), together with the Qt runtime and QML modules they need.

Using an external Qt (the Qt on the system is used instead of being deployed into the prefix) (not verified):

cmake -S . -B build-external -DCMAKE_PREFIX_PATH=/absolute/path/to/Qt/gcc_64 \
  -DTERMINUX_EXTERNAL_QT=ON -DTERMINUX_BUILD_TESTS=OFF -DTERMINUX_BUILD_INTERNAL_TARGETS=OFF
cmake --build build-external --target terminux dqe_viewer
cmake --install build-external --prefix "$VIRTUAL_ENV"
ln -s /absolute/path/to/Qt/gcc_64 "$VIRTUAL_ENV/qt"
terminux-qt-check --qt-dir "$VIRTUAL_ENV/qt" --prefix "$VIRTUAL_ENV"

In this mode the executables find Qt through $ORIGIN/../qt/lib, so LD_LIBRARY_PATH, QT_PLUGIN_PATH and QML2_IMPORT_PATH are not needed. On multiple hosts, the Qt directory must have the same absolute path on every host.

Note: in a source installation, terminux is the GUI itself; start Terminux with terminux-launch, which makes sure the daemon is running first. In the portable bundle, ~/.local/bin/terminux already is terminux-launch.

3.4 Checking the installation

terminux --version                                   # source install: GUI version; bundle entry: launcher version
QT_QPA_PLATFORM=offscreen dqe_viewer --smoke-exit && echo ok
terminux-doctor                                      # after the daemon has started: exit 0 when ready

terminux-doctor prints JSON: the socket paths, the daemon state, whether the configuration and the bundled knowledge files are readable, and whether the credentials file is safe (its content is never read).


4. Configuration

The daemon reads its configuration when it starts. After changing environment variables or configuration files, restart the daemon for the change to take effect (5.3).

4.1 LLM provider and credentials

Credentials file ~/.terminux/credentials.json:

mkdir -p ~/.terminux
cat > ~/.terminux/credentials.json <<'JSON'
{
  "TERMINUX_OPENAI_API_KEY": "<your API key>",
  "TERMINUX_OPENAI_BASE_URL": "https://api.deepseek.com"
}
JSON
chmod 600 ~/.terminux/credentials.json
  • The permissions must be exactly 0600, it must be a regular file (not a symlink) and it must belong to you; if any of these does not hold, the whole file is ignored.
  • Supported names: TERMINUX_GEMINI_API_KEY, TERMINUX_OPENAI_API_KEY, TERMINUX_OPENAI_BASE_URL.
  • TERMINUX_CREDENTIALS_FILE selects another location.
  • Environment variables with the same names still work, but only as a compatible alternative; the credentials file takes precedence.

Choosing a backend: TERMINUX_LLM_BACKEND has no default; without it the AI features are off.

Backend Settings Capabilities
openai_compatible TERMINUX_OPENAI_MODEL (default deepseek-chat); TERMINUX_OPENAI_API_KEY and TERMINUX_OPENAI_BASE_URL (default https://api.deepseek.com) in the credentials file; optional TERMINUX_OPENAI_TIMEOUT_SEC (default 120 seconds) Q&A and the Agent; Profile mode
gemini TERMINUX_GEMINI_MODEL (default gemini-3.6-flash); TERMINUX_GEMINI_API_KEY in the credentials file; needs the gemini extra Q&A and the Agent
llama_cpp TERMINUX_LLM_MODEL_PATH (a local GGUF file); for models with a thinking mode (for example Qwen3) also set TERMINUX_LLM_DISABLE_THINKING=1; needs the local-llm extra Basic Q&A only, without Agent capabilities

A local OpenAI-compatible service: connect with openai_compatible, put {"TERMINUX_OPENAI_BASE_URL": "http://127.0.0.1:8080/v1", "TERMINUX_OPENAI_API_KEY": "local"} in the credentials file, and set the model name with TERMINUX_OPENAI_MODEL. Whether a local service can complete the Agent flow depends on the model and the service, and is not verified yet.

Configuration templates: scripts/terminux-llm-env.sh (bash) and scripts/terminux-llm-env.csh (tcsh) in the source tree list every option; uncomment one backend and source the file. Do not put credentials in the template.

4.2 Embeddings (search index)

Past questions and records are indexed for search. The embedding destination is chosen separately from the provider above:

Setting Result
TERMINUX_LLM_BACKEND=gemini, or openai_compatible with TERMINUX_GEMINI_API_KEY in the credentials file Sent to the Gemini embedding API (gemini-embedding-001)
TERMINUX_EMBEDDING_BACKEND=noop Embeddings off; full-text search only
TERMINUX_EMBEDDING_BACKEND=local with TERMINUX_EMBEDDING_MODEL_PATH A local model

4.3 Declaring a project (optional)

TERMINUX_PROJECT_ID=<name> declares your project when the session is opened (the old name TERMINUX_PROJECT is also accepted). Terminux works normally without it; in Profile mode, a session that has not declared a project uses the Profile's project.

4.4 Interface language

Right-click in the terminal, choose Language, then 繁體中文, English or 简体中文. The choice is stored in ~/.terminux/preferences.json and applies to the daemon's messages, the language of AI answers and the initial language of the DQE Viewer; the DQE Viewer can also switch language from its own header. The default is Traditional Chinese; TERMINUX_PREFERRED_LANGUAGE is used only before a language has been chosen.

4.5 STA playbook (optional)

To enable STA stage tracking, quality gates and hints, deploy the template installed with the package to ~/.terminux/ecc:

mkdir -p ~/.terminux/ecc
python3 -c "from importlib.resources import files; import shutil, pathlib; shutil.copy(files('terminux_engine.ecc') / 'templates' / 'sta_signoff_playbook.yaml', pathlib.Path.home() / '.terminux' / 'ecc')"

Use the Python environment where Terminux is installed. A running daemon loads the playbook only after a restart; TERMINUX_PLAYBOOK_PATH selects another location. Without a playbook the daemon log contains a line TERM_ECC_PLAYBOOK_UNAVAILABLE; this is expected and nothing else is affected.

4.6 Shell integration

When the daemon starts, it installs and updates the hooks and wrappers automatically (~/.terminux/bin, ~/.terminux/hooks, ~/.terminux/bash_hooks.sh, ~/.terminux/tcsh_hooks.csh) and never modifies an rc file. With TERMINUX_AUTO_SETUP_WRAPPERS=0 nothing is installed, so the hooks send no notifications.

Shell How to enable
bash inside the GUI Automatic. The GUI starts bash with --rcfile, which first loads your ~/.bashrc and then the Terminux hooks
tcsh inside the GUI Add one line to ~/.tcshrc (or ~/.cshrc if there is no .tcshrc): if ( $?TERMINUX_ACTIVE ) source ~/.terminux/tcsh_hooks.csh (not verified)
An external bash terminal Not integrated automatically; to use it, add to ~/.bashrc: [ -f ~/.terminux/bash_hooks.sh ] && source ~/.terminux/bash_hooks.sh
  • TERMINUX_ACTIVE=1 is injected by the GUI, so the tcsh line takes effect only inside the Terminux terminal.
  • If the GUI receives no hook marker within 10 seconds after csh or tcsh starts, it shows a setup hint once.
  • Classic csh does not have tcsh's automatic postcmd/precmd mechanism.
  • Before each prompt, the wrapper directory is moved to the front of PATH, so EDA commands go through the wrappers.

4.7 Profile mode (for administrators)

Profile mode restricts the AI conversation to a scope defined by the administrator and enables @@/bind-run. It supports the openai_compatible backend only. The daemon reads the following environment variables at start-up; both files must be regular files owned by the user, with permissions 0600, given as absolute paths. If anything in them is invalid, the whole file is treated as invalid and every AI request is refused; it never falls back to an unrestricted mode.

Environment variable Content
TERMINUX_AGENT_TASK_PROFILE_FILE The Profile (JSON): the tools the AI may use, the conversation it may include, the allowed runs, and the rules for /bind-run
TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE The outbound policy (JSON): the allowed endpoint and model, the data classes that may be sent and their limits
TERMINUX_EGRESS_AUDIT_DIGEST How outbound records are hashed: plain_sha, keyed_ephemeral or keyed_persisted (the latter also needs TERMINUX_EGRESS_AUDIT_KEYRING_FILE). Required when the policy uses structural_c2

Profile example (evidence queries only; binding of host-native nangate45/gcd runs is allowed):

{
  "profile_id": "gcd-evidence",
  "tools": ["query_orchestration_evidence"],
  "context_sections": ["conversation_history"],
  "allowed_runs": {},
  "run_binding": {
    "max_runs_per_session": 2,
    "require_runner": "host_native",
    "allowed_designs": ["nangate45/gcd"],
    "max_age_sec": 604800
  }
}
  • tools can currently only be query_orchestration_evidence; context_sections can only be conversation_history.
  • allowed_runs lists pre-approved run ids and attempts; normally leave it empty and let users bind runs through run_binding.
  • All four keys of run_binding are required: how many runs one session may bind (1–8), the receipt's runner (terminux-orfs-run is host_native), the allowed <platform>/<design>, and the maximum age of the receipt in seconds.

Outbound policy example (v2, structural_c2; DeepSeek deepseek-chat):

{
  "policy_version": "terminux.egress_policy.v2",
  "approval_mode": "structural_c2",
  "endpoint": "https://api.deepseek.com/v1/chat/completions",
  "model": "deepseek-chat",
  "allowed_payload_sha256": [],
  "approved_data_classes": ["system_instructions", "learner_text", "conversation_history",
                            "tool_schema", "tool_call", "evidence_bundle", "model_output",
                            "budget_summary"],
  "limits": {"learner_text_max_chars": 4000, "history_max_turns": 20, "history_max_chars": 60000,
             "model_output_max_chars": 60000, "requests_per_turn": 4},
  "non_agent_egress": "deny"
}
  • endpoint must equal <TERMINUX_OPENAI_BASE_URL>/v1/chat/completions and model must equal TERMINUX_OPENAI_MODEL; otherwise every request is refused.
  • approved_data_classes lists the data classes that may be sent; timing_path_evidence (per-stage timing-path data) is never sent unless listed. All five keys of limits are required.
  • allowed_payload_sha256 must be empty in structural_c2 mode; in exact_digest mode only the listed request contents are allowed.
  • Every outbound decision is recorded in ~/.terminux/run/<nodename>/egress_audit/<date>.jsonl (metadata and hashes only, no content) and kept for 90 days.
  • In Profile mode the Engineering Work provider bindings are not enabled (11.2).

5. Starting, stopping and status

5.1 Starting

terminux-launch            # start or reuse the daemon, then open the GUI (the bundle's ~/.local/bin/terminux runs this)
terminux-launch --no-gui   # only make sure the background service is running
terminux-launch --reset    # show the owner information; after you type yes, only the owner lock is removed (no daemon is stopped)
  • Each account has exactly one daemon. terminux-launch reads ~/.terminux/run/owner.lock/owner.json: if there is no daemon it starts one and waits up to 30 seconds for it to become ready; if the daemon runs on this host it is reused; if the daemon runs on another host that shares HOME, a local relay is started instead (5.5).
  • If the daemon is not ready after 30 seconds, the launcher only warns and opens the GUI anyway; the hooks may not be deployed yet at that point.
  • The GUI is searched in this order: TERMINUX_GUI_BIN → <Python environment>/bin/terminux → <Python environment>/../bin/terminux → PATH.
  • The daemon uses the environment variables of the shell that ran terminux-launch. To change the backend or the Profile, restart the daemon with the new settings.

5.2 Checking the status

How What to look for
terminux-doctor "status": "ready" and exit 0
The GUI title bar and status bar A warning appears in the title bar when the daemon cannot be reached; the GUI reconnects automatically every 3 seconds
cat ~/.terminux/run/owner.lock/owner.json state is ready; host and pid are the daemon's host and process. This file contains the token of the TCP relay; do not share it

5.3 Stopping and restarting

Terminux has no stop command. On the host where the daemon runs:

cat ~/.terminux/run/owner.lock/owner.json      # find the pid
kill -TERM <pid>
while [ -e ~/.terminux/run/owner.lock ]; do sleep 1; done   # the owner lock is gone = clean shutdown
terminux-launch --no-gui                       # start again with the settings you want
  • An open GUI reconnects automatically and does not need to be restarted, but it gets a new session. Bound runs, proposals awaiting approval, plans and execution results exist only in the daemon's memory and are cleared by a restart. The history of tasks and Engineering Work is kept in the event records; unfinished tasks left by the previous daemon appear as read-only INTERRUPTED.
  • After an abnormal exit of the daemon (for example SIGKILL) or a reboot, the next start on the same host detects and reclaims the stale owner lock automatically.
  • If the owner lock does not disappear after stopping, daemon.log contains TERM_DAEMON_OWNER_LOCK_RETAINED: the daemon could not confirm that the data was closed cleanly and keeps the lock on purpose. Make sure no daemon process is left before deciding whether to use terminux-launch --reset.

5.4 Log locations

Content Location
The daemon's structured messages ~/.terminux/run/<nodename>/daemon.log (rotated at 10 MiB, 3 backups kept)
The daemon's output before it acquired ownership ~/.terminux/run/<nodename>/daemon.stdout.log
The relay relay.log and relay.stdout.log in the same directory

By default the daemon logs ERROR messages only, so an empty log during normal operation does not mean that something is wrong. To troubleshoot, restart the daemon with TERMINUX_LOG_LEVEL=INFO (or DEBUG, WARNING). <nodename> is the host name; TERMINUX_NODENAME overrides it.

5.5 Multiple login servers (not verified)

When the same account logs in from several login servers and HOME is shared (for example over NFS):

  • Each account has a single daemon (the owner). Running terminux-launch on another host starts terminux-relay, which offers the same sockets locally and connects to the owner's TCP ports with a token.
  • The TCP relay is not encrypted; use it only on trusted networks. On a single host, set TERMINUX_UNIX_ONLY_IPC=1 to keep the TCP ports closed.
  • The Python environment and the GUI executable must be at the same path on every host.
  • Commands that open the database directly (for example terminux-orfs-run) refuse with exit code 5 when the owner is on another host; run them on the owner host.
  • Known limitations: after the owner moves to another host, the GUI on the original host reconnects only after terminux-launch --no-gui is run there again; several GUIs show the action of the same notification, and clicking it repeatedly runs it repeatedly; notifications beyond the 500-entry buffer are lost when a GUI is disconnected for too long.
  • Verification: verified only in a simulated setup (two VMs, NFSv4.2); production sites, NFSv3, clock skew and mixed operating systems are not verified.

6. Using the Terminux terminal

6.1 The window

  • Terminal: your shell.
  • Notification Bar: at the top of the window; shows lineage checks, AI answers and other notifications. A few seconds after an answer appears it collapses to a title bar; click the title bar, or right-click and choose Notification Bar ▸ Show, to read it again.
  • Menu bar: View ▸ Work Panel shows or hides the Engineering Work panel (hidden by default; not verified); Help ▸ About Terminux and About Qt.

6.2 The context menu

Item Effect
Copy (Ctrl+Shift+C), Paste (Ctrl+Shift+V), Select All, Clear Terminal Usual terminal operations
Notification Bar ▸ Show / Remove Oldest 10 Messages / Remove All Messages Re-read or tidy up the Notification Bar
Language ▸ 繁體中文 / English / 简体中文 The language of the interface and of AI answers (4.4)
Open URL Appears when the selected text is a URL; opens it in a browser
Font Size + (Ctrl+=), Font Size - (Ctrl+-), Reset Font Size (Ctrl+0) Font size
Ask AI about this Ask about the selected text (10.1)

6.3 Known behavior

In the GUI's built-in bash, an extra line [1]+ Done … terminux-notify post_exec … appears after every command. It is the shell hook's background job report and does not affect the command.


7. Lineage checks

A lineage check answers the question "did this step read the right version of its inputs?".

  • When it runs: after you submit a command in the Terminux terminal, the GUI asks the daemon for a check. The command has already started, so the result is only a notice after the fact; it never blocks the command.

  • How it decides: for EDA tools it recognizes, the daemon reads the inputs declared by the command's runfile (-f <runfile>) and compares them with the recorded history:

    Result Notification Bar
    Consistent (CONSISTENT) No notice
    Mixed sources (MIXED_LINEAGE) Warning
    Insufficient evidence (INSUFFICIENT_EVIDENCE) Warning
    Unsupported tool (UNSUPPORTED_TOOL) No notice
  • Records: for EDA commands that finish successfully and carry -f <runfile>, the daemon records the inputs and outputs declared by the runfile in ~/.terminux/lineage/ledger.jsonl. The daemon only reads these files; it never creates or modifies them. The wrappers also write each host's execution records to ~/.terminux/lineage.<nodename>.jsonl.

  • Optional LLM assistance (off by default; when enabled, data is sent out, see chapter 13):

    • TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME=1: ask the LLM to explain when a check raises a concern.
    • TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME=1: ask the LLM to parse a runfile that the fixed-format parser cannot read (the complete runfile contents are sent).
  • Graphs: an @@ question that contains "lineage graph" (or one of the other keywords in 10.5) produces a lineage graph HTML page.


8. Running ORFS

terminux-orfs-run runs one ORFS flow directly on the host under your account and leaves a receipt, an artifact manifest and a quality verdict. It needs no Docker, container, sudo or root, and no write access to the ORFS installation; running it as root is refused.

8.1 Prerequisites

  • Your CAD/IT administrator has installed ORFS and the EDA tools (OpenROAD, Yosys, KLayout).
  • The last step of ORFS needs KLayout: klayout must be on PATH when you run the command, or be added to PATH by --env-script. Without it the flow stops at check-klayout with exit code 1; the outputs and quality records of the earlier stages are kept.
  • An output directory that you own.

8.2 Running a flow

terminux-orfs-run --orfs-repo-root /path/to/OpenROAD-flow-scripts \
  --work-home ~/orfs-runs/my-run --design gcd --platform nangate45 --variant my-run \
  --design-config ./designs/nangate45/gcd/config.mk \
  --ledger-db ~/orfs-runs/my-run-ledger.sqlite --receipt-out ~/orfs-runs/my-run-receipt.json

At the end, stdout shows the quality summary and the run id. The receipt is written to --receipt-out and, by default, into your event records, so the daemon and @@ can find this run.

8.3 Options

Option Required Description
--orfs-repo-root Yes The ORFS installation root (containing flow/); may be read-only
--work-home Yes This run's output directory (ORFS WORK_HOME); must be owned by you; the last level is created if its parent exists. results/, reports/, logs/ and objects/ are written here
--design Yes The design name; must equal the name used by ORFS for its output directories (DESIGN_NICKNAME, or DESIGN_NAME when not set), otherwise the flow stops before it starts
--platform Yes For example nangate45
--variant Yes ORFS FLOW_VARIANT; must not be base. It also becomes part of the step id and may be sent to the LLM provider with the evidence, so do not use a confidential name
--design-config Yes The path of config.mk relative to ORFS flow/; the file must be under flow/
--ledger-db Yes A ledger file dedicated to this run. It must not point to the daemon's ~/.terminux/orchestration/ledger.sqlite (aliases such as symlinks and hard links included)
--receipt-out Yes Where to write the receipt JSON
--env-script No The environment script that makes the EDA tools available, default <orfs-repo-root>/env.sh. Apart from HOME, LANG and PATH, Terminux does not inherit your shell's environment
--make-executable No The make that runs the flow, default make on PATH
--openroad-exe, --yosys-exe No Explicit tools (ORFS OPENROAD_EXE, YOSYS_EXE)
--timeout-seconds No Time limit, default 900 seconds
--receipt-store No Write the receipt into the given event-record file instead of the default one (mutually exclusive with --no-receipt)
--no-receipt No Do not write into any event records (--receipt-out is still written)

If you have no write access to the ORFS installation and need to change settings: write your own --env-script that first sources the original env.sh and then exports the variables that the configuration defines with ?= (for example CORE_UTILIZATION). The hash of the env script is recorded in the receipt.

8.4 Exit codes

Exit code Meaning
0 The run succeeded and the receipt was written (with --no-receipt, only the run result counts)
1 The run failed
2 Invalid options or environment (including running as root, a --work-home you do not own, a --ledger-db that points to the daemon's ledger, and a missing env script or make)
3 The run succeeded but the receipt was not written
5 The daemon runs on another host; opening the database directly is refused
130/143 Ctrl-C/SIGTERM received

The quality verdict (for example a timing failure) does not affect the exit code.

8.5 Interruption (not verified)

On Ctrl-C or SIGTERM, Terminux first terminates the whole process group of the flow and confirms that it has ended, then writes a cancelled receipt and exits with the original signal (the shell sees 130/143). If this cannot be confirmed, no receipt is written and stderr shows EXECUTION_CLEANUP_UNCONFIRMED.

8.6 Viewing the verified report

terminux-orfs-report --receipt ~/orfs-runs/my-run-receipt.json --run-id <run_id> --attempt <attempt>
Option Description
--receipt, --run-id, --attempt Required. The run id and the attempt are in the receipt and are printed at the end of terminux-orfs-run
--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 of printing the whole report
--expect-line L With --stage: require that stage to be on line L of the report
--view With --stage: open the verified report at that line with less (needs a terminal)

The command shows the report only after its hash matches the receipt and the artifact manifest, so what you see is the report of that exact run. It exits with 0 on success and 2 on error.


9. Quality checks (DQE) and the DQE Viewer

9.1 What is checked

After an ORFS run, orfs_dqe parses 6_finish.rpt, 5_route_drc.rpt, 6_report.log and the artifact manifest with fixed rules (no LLM) and judges the following 14 checks:

Check Description Mandatory
orfs_manifest_integrity Identity and hash of the artifact manifest Yes
orfs_artifact_completeness The required artifacts are present and stable Yes
orfs_final_deliverables The final layout, DEF, database and netlist were produced Yes
orfs_process_exit_code Exit code of the tool process Yes
orfs_setup_wns Setup worst negative slack (WNS); below 0 is a violation Yes
orfs_setup_tns Setup total negative slack (TNS) No
orfs_setup_violation_count Number of setup-violating paths Yes
orfs_hold_violation_count Number of hold-violating paths Yes
orfs_max_slew_violation_count Number of max-transition (slew) violations No
orfs_max_fanout_violation_count Number of max-fanout violations No
orfs_max_cap_violation_count Number of max-capacitance violations No
orfs_route_drc_violation_count Number of detailed-route DRC violations Yes
orfs_log_error_markers Error markers in the ORFS logs Yes
orfs_log_warning_markers Warning markers in the ORFS logs No

Each check results in pass, warn, fail or unknown. The 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 result is warn, fail or unknown. The quality check only gives results: it does no root-cause analysis, and it never reruns the flow or changes the design.

9.2 Opening the DQE Viewer

In the Terminux terminal, type:

@@open DQE Viewer

This command is handled locally by Terminux and sends no AI request. The GUI starts the Viewer on your host, using the dqe_viewer in the GUI's own directory by default; set TERMINUX_DQE_VIEWER_BIN to use another executable. Outside the Terminux terminal, terminux-chat "open DQE Viewer" does the same (not verified).

9.3 The Temporary workspace

The quality records written by each run are grouped by job and appear in the Temporary workspace:

  • The workspace lists the jobs, and "Search job_key / block / flow" finds them; selecting a job lists its DQE items, which can be filtered by status (Pass / Warn / Fail / Unknown, for example choose "Fail" to see only failed items).
  • Selecting an item shows its value, unit, description, source path and an attachment preview.
  • The header shows the total and the count per status (for example total 14, pass 10, warn 2, fail 2).

9.4 The Archived workspace and check-in (not verified)

  • Check in whole job turns a temporary job into an archived package and checks it in to the version path you specify through the external isvn tool; run Check-in dry-run first to confirm. isvn is an independently released product and must be installed separately.
  • The Archived workspace lists the checked-in versions and can be filtered by phase, block and version.

9.5 The Compare workspace

  • Compare takes the first source as the baseline (100%) and draws a normalized trend of each DQE metric; you can also see the raw values and the delta from the baseline.
  • Export HTML exports the comparison result as HTML.
  • Comparing several jobs selected with checkboxes is not verified in 0.1.1.

9.6 Retention and purge

  • Retention: the retention period of the Temporary workspace is a global policy for all temporary jobs. Change it in the Viewer's Temporary retention policy with Edit policy and Save policy (stored in ~/.terminux/dqe/retention_policy.json).
  • Manual purge: first run Preview selected job purge or Preview expired jobs purge; the purge runs only after you confirm the previewed list.
  • Scheduled purge: dqe-scheduled-clean (add --dry-run to see the result first; also --no-vacuum, --db <path>, --policy <path>, --log <path>). The default log is ~/.terminux/dqe/scheduled_clean.log.

The quality database is ~/.terminux/dqe/dqe.sqlite by default; TERMINUX_DQE_DB_PATH selects another location.


10. Using the AI

You ask with @@. An LLM backend must be configured first (4.1). The Agent is available with openai_compatible and gemini only.

10.1 Asking a question

  • At the prompt of the Terminux terminal, type @@ followed by your question and press Enter. The line is not passed to the shell; the answer appears in the Notification Bar.
  • Alternatively, select text in the terminal with the mouse, right-click and choose Ask AI about this; the selected text is the question. Follow-up questions with @@ continue the same conversation.
  • The text after @@ goes to Terminux, so shell variables are not expanded; write paths as full absolute paths.

10.2 What the AI can and cannot do

  • The AI can only query recorded execution evidence (receipts, artifact manifests, quality results). It cannot read your files or run shell commands, and it never approves or performs any action on your behalf.
  • When there is no evidence to query, the AI says so and gives only general information.
  • The AI sees the quality summary, not the report itself; check timing numbers yourself with the DQE Viewer and terminux-orfs-report.

10.3 Asking about one ORFS run

  1. Run the flow with terminux-orfs-run. The receipt written to --receipt-out contains the run's run_id and attempt; the quality summary at the end of stdout also shows the run id.

  2. Bind the run (requires Profile mode, 4.7):

    @@/bind-run /absolute/path/to/receipt.json
    

    On success the Notification Bar shows RUN_BOUND: run_… attempt 1 is now bound to this session (host_native nangate45/gcd).. The binding exists only in this window's session and is gone after a daemon restart; @@/unbind-run removes it.

  3. Ask directly, for example:

    @@For the Run I just bound, which DQE checks are WARN or FAIL? Show the run evidence and where I can verify it.
    @@Based on the evidence from this run, what should I inspect next, and why?
    

    Without Profile mode, writing the run id in the question also lets the AI query the same evidence.

  4. Check for yourself: @@open DQE Viewer and look at the checks under the "Fail" filter; terminux-orfs-report prints the verified finish report.

10.4 Explanation and comparison: explicit commands

With a cloud backend, the AI never creates actions awaiting approval from a natural-language request by itself. To have Terminux explain one run or compare two runs, use these four steps. These commands work in normal mode only: in Profile mode the only local commands are /bind-run and /unbind-run, and every other command returns LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE.

Step Command Effect
1 @@/plan-only <goal> Produces a plan; runs no step and creates no proposal. Example: @@/plan-only Plan how to analyse why this run failed its quality checks; only produce a plan, do not run anything.
2 @@/plan-propose <plan_id> <step_id> Creates a proposal for one step of the plan; still runs nothing
3 @@/approve <proposal_id> <proposal_digest> Approves the proposal (/reject rejects it). A proposal that is not approved within 10 minutes expires
4 @@/execute <proposal_id> <proposal_digest> Runs it once. The arguments must be exactly those of the proposal; it cannot be run again
  • @@/proposals lists the proposals; @@/plans and @@/plan <plan_id> show plans, and @@/cancel-plan <plan_id> <plan_digest> cancels a plan.
  • @@/results lists execution results; @@/use-result <result_id> <result_digest> includes that result in later questions, and @@/clear-result stops doing so. Execution results exist only in the daemon's memory and are kept for 30 minutes.
  • There is no way to approve or run a whole plan at once: /approve-plan, /execute-plan and /approve-all are always refused; every step must be approved with /approve and run with /execute on its own.
  • Keep one step per plan. Steps that depend on other steps cannot be proposed yet, so plan one step at a time.
  • Running without approval, a wrong digest and running twice are all refused.
  • Known limitation: a comparison of two runs is at most "conditionally comparable" (conditionally_comparable). It does not use the configuration-file and env-script hashes in the execution records, so it cannot prove that the only difference between the two runs is the one you declared; metric differences are reported as they are.

10.5 Commands that do not go to the AI

Input Effect
Contains "DQE Viewer" together with a verb such as open, launch, start or show (or 開啟, 打開, 啟動, 顯示), for example @@open DQE Viewer Opens the DQE Viewer
Contains "lineage graph", "lineage dag", "show lineage", "血緣圖" and similar Produces and opens a lineage graph HTML page (the browser loads a pinned version of Mermaid from jsDelivr)
A known command starting with / Handled locally by Terminux (sections 10.3 and 10.4, and chapter 11)

10.6 Differences in Profile mode

  • The system prompt contains only the Profile's instructions, this window's conversation and the bound runs; other session state, work summaries and the state of other terminals are not sent.
  • The only local commands are /bind-run and /unbind-run; /plan-only, /approve, /execute, /task…, /work… and the others return LOCAL_COMMAND_DISABLED_IN_PROFILE_MODE. Conversely, /bind-run is not a local command in normal mode. So "bind a run, then ask" and "run an explanation or comparison with explicit commands" cannot be used with the same daemon configuration.
  • Profile mode supports the openai_compatible backend only; with another backend Terminux returns PROFILE_PROVIDER_UNSUPPORTED and sends no request.
  • Without a bound run and without text attached to the question, the AI gives only general information or asks you to bind a run first. For example, selecting a line of config.mk and choosing Ask AI about this yields "bind a run first or ask an explicit question", not an explanation of that line.

11. Bounded tasks and Engineering Work (not verified)

The features in this chapter were not verified with the public artifacts of 0.1.1. The @@ commands in this chapter work in normal mode only (they are disabled in Profile mode).

11.1 Tasks

A task is created as a draft first; after you approve it, the daemon runs it through fixed steps. The number of tasks that run at the same time is limited, and further tasks wait in a queue.

Command Effect
@@/profile <absolute path of the Profile> Selects a Profile for this session
@@/profiles Lists the Profiles selected in this session
@@/task-create <profile_id> <question…> Creates a flow task draft with a selected Profile (no EDA has run yet)
@@/task-start <task_id> <task_digest> Approves and starts (one approval is enough)
@@/task <task_id> Shows one task
@@/task-cancel <task_id> <task_digest> Requests a stop
@@/tasks Lists all your tasks in this daemon

A flow task always runs: baseline run → explanation → a candidate with the one approved change → candidate run → comparison.

11.2 Engineering Work

Engineering Work is multi-round engineering work under an overall budget: you state an objective and criteria; after you authorize it, the system proposes approaches collaboratively, runs them after approval, and decides from the actual engineering evidence whether the criteria are met.

  • Prerequisite: the administrator provides a provider bindings file with TERMINUX_EAP3_BINDINGS_FILE. Without it the feature is not enabled and terminux-work list reports an error. It is not enabled in Profile mode.

  • Command line:

    terminux-work [--profile-path <Profile>] create <profile_id> <package_id> "<objective>" [--criterion …] [--constraint …]
    terminux-work authorize <work_id> --mode PLAN_ONLY|PER_PROPOSAL|BOUNDED_EXPLORATION
    terminux-work approve <work_id>
    terminux-work continue <work_id>
    terminux-work get <work_id>
    terminux-work list
    terminux-work answer <work_id> "<answer or additional information>"
    terminux-work pause|resume|cancel|takeover <work_id>
    

    authorize can also limit counts and scope: --attempts (default 2), --provider-dispatches (default 12), --tool-launches (default 5), --candidate-materializations (default 2), --formal-proof-launches, --baseline-tool-launches, --allowed-method, --allowed-change-json, --writable-root, --stop-condition.

  • In the terminal: @@/works, @@/work <work_id>, @@/work-create, @@/work-authorize <work_id> <plan|proposal|bounded>, @@/work-approve, @@/work-continue, @@/work-answer, @@/work-pause, @@/work-resume, @@/work-cancel, @@/work-takeover; or use View ▸ Work Panel.


12. Other tools

Tool Purpose Status
terminux-chat "<question>" Ask an @@ question outside the Terminux terminal; every call is a new session Not verified
terminux-lineage-graph [--ledger PATH] [--session S1,S2] [--output PATH] [--no-open] Produces a lineage graph HTML page; trace --session SESS produces an execution trace graph Not verified
terminux-dream --user-id <account> --date <yesterday|today|YYYY-MM-DD>; --backfill --days N Produces work summaries manually (normally the daemon does this automatically) Not verified
terminux-build-rag-index [--source-dir DIR] [--index-dir DIR] Builds the index of your own RAG knowledge base from ~/.terminux/rag_knowledge into ~/.terminux/rag_index; needs the rag extra and an embedding setup Not verified
terminux-tool register <tool_id> [--executable NAME], unregister, list Registers your own EDA executables, without administrator rights Not verified
terminux-package-install <directory> [--replace], terminux-package-uninstall <id>, terminux-package-status [<id>] [--activate] Installs, removes and shows your own packages (installed into ~/.terminux/packages); --activate asks the running daemon to reload them without a restart Not verified
terminux-package-new <id> --root DIR, terminux-package-validate, terminux-package-test --root DIR --package ID, terminux-package-doctor --root DIR Package development: scaffold, offline validation, local tests, diagnostics --help only

terminux-chat, terminux-dream, terminux-lineage-graph and terminux-build-rag-index are provided in the scripts/ directory of the source tree.


13. Data, privacy and security

13.1 Where data is kept

All records are kept in ~/.terminux under your own account: event records, the quality database, execution receipts, artifact manifests, lineage records, the search index and logs. The full list is in Appendix C.

13.2 When data is sent to the LLM provider

When TERMINUX_LLM_BACKEND and TERMINUX_EMBEDDING_BACKEND are both unset and ~/.terminux/llm_router.yaml does not exist, Terminux sends nothing to any LLM provider. Once configured, the features below send data to the selected provider. gemini and openai_compatible (for example DeepSeek) are cloud services; llama_cpp and a local OpenAI-compatible service stay on your machine.

Feature When it sends What it sends
AI Q&A and the @@ Agent When you ask The question and the conversation history; the current session state (stage, corner, block, gate results, WNS, and the most recent lineage checks with command and working directory); the work summary and related past Q&A; the state of other terminals. In addition the Agent sends only the execution evidence it looked up: the status and terminal outcome of the queried run, step and tool identifiers, receipt and artifact-manifest identifiers and hashes, DQE results, and the index of reports and lineage (hashes and sizes only, no file contents). Per-stage timing-path data is not sent by default
Explanation, comparison and situation assessment of ORFS runs When you request it through @@; situation assessment also runs automatically after a new ORFS run's quality results are written (not verified) Run identity (design, platform, variant), DQE results and metrics, excerpts of ORFS reports/logs, and the comparison with the baseline
Work summary When the terminal is used again after being idle for a while, and when the daemon starts and catches up on earlier summaries EDA tools used in the period, corners, gate results, WNS changes, number of questions and conversation highlights
Conversation condensation When the conversation history grows too long The conversation
Block-name inference After an STA playbook is loaded, when the block cannot be determined before a command runs (tcsh hooks do this for every command) Command and working directory
Embedding (search index) In the background; when building the RAG knowledge index Questions, AI replies, prompt messages, lineage-check messages, conversation highlights and work summaries; the query when searching; knowledge-document contents
Lineage explainer (off by default) When TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME=1 is set and a lineage check raises a concern Command, working directory, runfile path, check results and messages about the related files
Runfile parsing fallback (off by default) When TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME=1 is set and the fixed-format parser cannot read the runfile The complete runfile contents, command, working directory and runfile path
  • Automatic situation assessment, work summaries and conversation condensation have no individual switches; without a configured backend nothing is sent.
  • If /projusers/<project>/<account>/.terminux/event_store.sqlite exists and is readable (<project> is the name of the directory above HOME), AI Q&A also includes the accounts, blocks, corners and WNS summaries of other members of the same project.
  • In Profile mode only the Profile's instructions, this window's conversation, the bound runs and the evidence looked up are sent, within the limits of the outbound policy (4.7).
  • If design scripts, paths, design names and timing results are confidential, check the provider's data-processing terms first, or use a local provider only. --design and --variant may also be sent with the evidence, so do not use confidential names.

13.3 Other connections

  • When a lineage graph HTML page is opened in a browser, it downloads a pinned version of Mermaid from jsDelivr and verifies it with Subresource Integrity; that download carries no Terminux data.
  • The TCP relay across login servers has token authentication but no encryption (5.5).
  • The portable bundle needs no network access during installation.

13.4 Credentials and access

  • Keys are read only from a credentials file with permissions 0600 (or from the compatible environment variables); terminux-doctor only checks whether the file is safe and never reads its content.
  • The daemon accepts connections only from the same Linux account; the identity of a connection is checked by the operating system, not taken from what the client claims.
  • The Profile, the outbound policy and the keyring must all be regular files owned by the user, with permissions 0600.

14. Maintenance

14.1 Diagnostics

terminux-doctor

It calls no provider and runs no EDA tool. "status": "ready" (exit 0) means that the daemon is ready and the configuration and bundled knowledge files are readable; for "attention" (exit 1), look at the individual fields of the JSON.

14.2 Backup and restore (--help only)

terminux-cold-backup works only while the daemon is stopped (no ~/.terminux/run/owner.lock):

# Create: the destination must be an absolute path that does not exist yet; sources are LABEL=/absolute/path,
# must not overlap and must not contain symlinks
terminux-cold-backup create /backup/terminux-20261110 \
  --source ecc=$HOME/.terminux/ecc --source dqe=$HOME/.terminux/dqe \
  --source orch=$HOME/.terminux/orchestration --source lineage=$HOME/.terminux/lineage

# Verify: recomputes the SHA-256 of every file
terminux-cold-backup verify /backup/terminux-20261110

# Restore: each target must equal the original path at backup time and must not exist now
terminux-cold-backup restore /backup/terminux-20261110 \
  --target ecc=$HOME/.terminux/ecc --target dqe=$HOME/.terminux/dqe \
  --target orch=$HOME/.terminux/orchestration --target lineage=$HOME/.terminux/lineage
  • Recommended content: ecc/ (event records), dqe/ (quality database and retention policy), orchestration/, lineage/ (including the artifact manifests), memory/ (there is no tool to rebuild the search index), terminux.db, tools/, packages/, preferences.json. run/ holds runtime files and does not need a backup.
  • Do not put the credentials file, the Profile, the policy or the keyring into ordinary backups; keep them safely and separately.
  • On success it prints JSON and exits with 0; when a precondition is not met it prints {"status": "error", "reason": …} and exits with 2.

14.3 Pre-upgrade check (--help only)

terminux-rollback-check --event-store ~/.terminux/ecc/event_store.db \
  --agent-socket ~/.terminux/run/<nodename>/terminux.sock --lineage-socket ~/.terminux/run/<nodename>/lineage.sock

It checks, read-only, whether the data formats in the event records are within the range that this version supports. It neither switches programs nor restores data.

14.4 Removing old data

  • Event records: python -m terminux_engine purge --from YYYY-MM-DD --to YYYY-MM-DD previews the number of events; only with --force are they deleted, after the events of that range have been written as JSONL to ~/.terminux/ecc/archive/. Run it while the daemon is stopped, with the Python of the environment where Terminux is installed (in the bundle: ~/.local/opt/terminux/current/venv/bin/python).
  • Quality database: see 9.6.
  • Lineage wrapper records: above 10 MiB the daemon compresses them with gzip and starts a new file automatically, keeping 3 backups.

14.5 Upgrading Terminux

  • Portable bundle: stop the daemon and run ./install.sh of the new version; after the Qt check passes, current switches to the new version and the old one is kept. Your data (~/.terminux) is not affected.
  • Source: after updating the source, run uv pip install './engine[...]' again, rebuild and reinstall the GUI, then restart the daemon.

14.6 Removing Terminux

~/.local/opt/terminux/current/uninstall.sh --version <version>     # remove one version
~/.local/opt/terminux/current/uninstall.sh --all                   # remove all versions

By default the data, settings and logs in ~/.terminux are kept; --purge-data deletes the data, and even with --yes you must type the full data path to confirm. The uninstaller modifies no rc file; remove the hook lines you no longer use yourself. For a source installation, delete the Python environment and the installed executables. To remove the wrappers and hooks first, run terminux_engine/resources/scripts/terminux-setup-wrappers --remove from the installed package: it removes only the files that Terminux created and that were not modified, and keeps all other files and your rc settings.


15. Troubleshooting

Symptom Likely cause What to do
@@ gives no answer or an error TERMINUX_LLM_BACKEND is not set; the credentials file is not 0600; the daemon is not running Run terminux-doctor; fix the setting and restart the daemon
The AI says it has no evidence to query No run is bound and the question contains no run id In Profile mode use @@/bind-run <receipt>; or write the run id in the question
CLOUD_AGENT_CAPABILITY_DENIED appears in an answer With a cloud backend, the AI can only query evidence This is expected; to run an explanation or a comparison, use the explicit commands in 10.4
Every AI request is refused in Profile mode The Profile or policy file is invalid, not 0600, endpoint/model differ from the actual settings, or the outbound record cannot be written Fix the files and restart the daemon; an invalid setting never falls back to an unrestricted mode
The daemon does not start (exit code 4, TERM_DAEMON_OWNER_EXISTS) Another daemon already exists (possibly on another host) Check host and pid in owner.json; use or stop that daemon on its host. Use terminux-launch --reset only after confirming that it no longer exists
The daemon does not start (exit code 2, TERM_AGENT_SOCKET_UNAVAILABLE) ~/.terminux has permissions that are too open (group/other writable), is a symlink or has the wrong owner, or another file occupies the socket path Fix it according to the path in the message; Terminux never deletes existing files on its own
The GUI connects, but neither @@ nor the DQE Viewer responds The daemon's lineage socket did not start Restart with TERMINUX_LOG_LEVEL=INFO and look for TERM_SOCKET_BIND_FAILED in daemon.log
@@open DQE Viewer does not open the Viewer The dqe_viewer executable cannot be found Install the Viewer in the same directory as the GUI, or set TERMINUX_DQE_VIEWER_BIN
The hooks have no effect in tcsh The source line is missing from the rc file, or TERMINUX_AUTO_SETUP_WRAPPERS=0 is set Configure as in 4.6; make sure ~/.terminux/tcsh_hooks.csh exists
terminux-launch warns with TERM_LAUNCH_WRAPPER_SETUP The daemon failed to deploy the hooks, or the deployment is disabled Check daemon.log as the message says
terminux-orfs-run stops at check-klayout (exit 1) klayout is not on PATH Add KLayout to PATH, or set it up in --env-script
terminux-orfs-run exits with 2 Running as root, a --work-home you do not own, a --ledger-db that points to the daemon's ledger, or a missing env script or make Fix it according to the message on stderr
terminux-orfs-run exits with 3 The run succeeded but the receipt was not written into the event records Make sure the event records are writable, or choose a writable location with --receipt-store
A command refuses with exit code 5 (TERM_DATABASE_REMOTE_OWNER) The daemon runs on another host Run the command on that host
daemon.log is empty Only ERROR messages are logged by default This is expected; restart with TERMINUX_LOG_LEVEL=INFO when you need details
The log shows TERM_ECC_PLAYBOOK_UNAVAILABLE No STA playbook is deployed (it is optional) Ignore it if you do not use a playbook; to use one, deploy it as in 4.5
The log shows TERM_EVENT_STORE_UNAVAILABLE The event-record file cannot be opened or written Fix the permissions of ~/.terminux/ecc and restart; until then packages and event records do not work
The bundle installation fails with missing libraries xcb or other system libraries are missing Ask the administrator to install the SONAMEs listed by terminux-qt-check (3.2)
terminux-orfs-run and other commands are not found in a bundle installation ~/.local/bin has only two entries Use ~/.local/opt/terminux/current/venv/bin/<command>, or add that directory to PATH

16. FAQ

Q: Can I use Terminux without an LLM? Yes. The terminal, lineage checks, ORFS runs, receipts, quality checks and the DQE Viewer need no LLM; only AI questions, explanations, comparisons and summaries do.

Q: Will the AI change my design or run tools by itself? No. With a cloud backend the AI can only query recorded execution evidence. An explanation or a comparison runs only after you create a proposal with an explicit command, approve it, and run it once.

Q: Does any data leave my machine? Only after you configure an LLM backend, and then as described in the table in 13.2, to the provider you chose. With a local provider the data stays on your machine.

Q: Can I use a local model? Yes. llama_cpp provides basic Q&A without the Agent; a local OpenAI-compatible service can be connected, but whether it completes the Agent flow is not verified yet.

Q: Do I need Docker or root? No. ORFS runs on the host under your account, and the bundle is installed in your home directory.

Q: Why did the command run even though the lineage check warned? The lineage check runs after the command has been submitted; its result is a notice and never blocks the command.

Q: What is lost when the daemon restarts? Event records, the quality database, receipts and artifact manifests are kept. Only what lives in memory is cleared: bound runs, proposals awaiting approval, plans and execution results.

Q: Can I use tcsh? Yes, with one line in the rc file (4.6); the tcsh hooks are not verified in 0.1.1.

Q: Is Terminux open source? No. Terminux is released under the PolyForm Shield License 1.0.0 and is source-available software. Any organization may use it free of charge, including for internal business and customer projects, but may not use it to provide a product or service that competes with Terminux.

Q: How do I report a problem? External pull requests are not accepted at this time; please report problems through GitHub Issues.


17. Appendix

A. Command reference

Command Purpose
terminux-launch (bundle: terminux) Starts or reuses the daemon, then opens the GUI
terminux (source installation) The GUI itself; --version, --self-check
terminux-daemon The daemon (normally started by terminux-launch)
terminux-relay Local relay on hosts that are not the owner
terminux-orfs-run Runs ORFS once
terminux-orfs-report Prints a report verified against the receipt and the artifact manifest
terminux-doctor Local diagnostics
terminux-qt-check --qt-dir DIR [--prefix DIR] Checks Qt and runs the GUI self-checks
dqe_viewer The DQE Viewer (opened by the GUI); --version, --smoke-exit
terminux-work Engineering Work
terminux-tool Registers your own EDA executables
terminux-package-install, -uninstall, -status Manage your own packages
terminux-package-new, -validate, -test, -doctor Package development
terminux-cold-backup Cold backup, verification, restore
terminux-rollback-check Data-compatibility check before an upgrade
dqe-scheduled-clean Scheduled DQE purge
terminux-corpus-replay A replay tool for simulated qualification data, not a real ORFS run

Among the Python commands in this table, all except terminux-qt-check and terminux-orfs-report accept --version; terminux and dqe_viewer accept --version as well.

B. Environment variables

Variable Purpose
TERMINUX_LLM_BACKEND openai_compatible, gemini, llama_cpp; unset = AI off
TERMINUX_OPENAI_MODEL, TERMINUX_OPENAI_TIMEOUT_SEC Model of the OpenAI-compatible service (default deepseek-chat) and timeout (default 120 seconds)
TERMINUX_GEMINI_MODEL Gemini model (default gemini-3.6-flash)
TERMINUX_LLM_MODEL_PATH, TERMINUX_LLM_DISABLE_THINKING Model file for llama_cpp; turn off the thinking mode
TERMINUX_EMBEDDING_BACKEND, TERMINUX_EMBEDDING_MODEL_PATH Embedding destination (noop, local, gemini) and the local model
TERMINUX_CREDENTIALS_FILE, TERMINUX_DISABLE_CREDENTIAL_FILE Location of the credentials file; 1 disables reading it entirely
TERMINUX_PROJECT_ID Declares a project (optional)
TERMINUX_PREFERRED_LANGUAGE Default before a language is chosen: zh-Hant, en, zh-Hans
TERMINUX_PLAYBOOK_PATH Location of the STA playbook
TERMINUX_LOG_LEVEL Log level of the daemon (default ERROR)
TERMINUX_GUI_BIN, TERMINUX_DQE_VIEWER_BIN The GUI or Viewer executable to use
TERMINUX_DQE_DB_PATH, TERMINUX_EVENT_STORE_PATH Locations of the quality database and the event records
TERMINUX_AUTO_SETUP_WRAPPERS 0: the daemon does not install hooks and wrappers
TERMINUX_ENABLE_LINEAGE_EXPLAINER_RUNTIME, TERMINUX_ENABLE_INTENT_FALLBACK_RUNTIME LLM assistance for lineage (off by default, see chapter 7)
TERMINUX_AGENT_TASK_PROFILE_FILE, TERMINUX_OUTBOUND_PAYLOAD_POLICY_FILE, TERMINUX_EGRESS_AUDIT_DIGEST, TERMINUX_EGRESS_AUDIT_KEYRING_FILE Profile mode (4.7)
TERMINUX_EAP3_BINDINGS_FILE Provider bindings for Engineering Work (11.2)
TERMINUX_HOME_DIR, TERMINUX_NODENAME, TERMINUX_ADVERTISE_HOST, TERMINUX_UNIX_ONLY_IPC Advanced: private base directory, host identity, advertised host name, local sockets only

C. Files and directories

Location Content
~/.terminux/credentials.json Credentials (0600)
~/.terminux/preferences.json Interface language
~/.terminux/ecc/event_store.db Event records (receipts, quality records, tasks and more)
~/.terminux/ecc/sta_signoff_playbook.yaml STA playbook (optional)
~/.terminux/dqe/dqe.sqlite Quality database
~/.terminux/dqe/retention_policy.json Retention policy of the Temporary workspace
~/.terminux/lineage/ledger.jsonl Lineage records
~/.terminux/lineage/artifact_manifests/ Artifact manifests
~/.terminux/lineage.<nodename>.jsonl Execution records of the wrappers
~/.terminux/orchestration/ledger.sqlite Execution state managed by the daemon
~/.terminux/memory/search_index.db Search index
~/.terminux/rag_knowledge/, ~/.terminux/rag_index/ Your own RAG knowledge and its index
~/.terminux/tools/user_tool_catalog.yaml The EDA tools you registered
~/.terminux/packages/ The packages you installed
~/.terminux/bin/, ~/.terminux/hooks/, ~/.terminux/bash_hooks.sh, ~/.terminux/tcsh_hooks.csh Wrappers and hooks (installed automatically by the daemon)
~/.terminux/run/owner.lock/owner.json The daemon's host and state
~/.terminux/run/<nodename>/ Sockets, daemon.log, outbound records (Profile mode)
~/.local/opt/terminux/ Installation location of the portable bundle

D. License and third-party software

Terminux is released under the PolyForm Shield License 1.0.0 (source-available, not open source as defined by the OSI); see LICENSE.md for the terms and THIRD_PARTY_NOTICES.md for third-party licenses. ORFS, OpenROAD, Yosys and KLayout are not shipped with Terminux and are installed separately by your site. isvn is an independently released product.