User Guide
User Guide
Applies to Terminux 0.1.1. Commands and features may differ in other versions.
Contents
- Before you start
- Quick start
- Installation
- Configuration
- Starting, stopping and status
- Using the Terminux terminal
- Lineage checks
- Running ORFS
- Quality checks (DQE) and the DQE Viewer
- Using the AI
- Bounded tasks and Engineering Work (not verified)
- Other tools
- Data, privacy and security
- Maintenance
- Troubleshooting
- FAQ
- 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:
-
Make sure the host is Linux x86_64 and Qt 6.7 or later (default Desktop gcc 64-bit components) is installed.
-
Download
terminux-<version>-linux-x86_64.tar.gzandSHA256SUMS, verify them and install:Follow the Installation tutorial for the independent checksum, STOP and subsequent installation sequence.
-
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 -
Choose the backend and start:
export TERMINUX_LLM_BACKEND=openai_compatible terminux -
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.jsonWith the portable bundle,
terminux-orfs-runis in~/.local/opt/terminux/current/venv/bin/; use the full path or add that directory toPATH. -
Type
@@open DQE Viewerto 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?(replacerun_…with the full run id, which isrun_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>, andcurrentpoints to the version in use.currentis switched only after the Qt check passes; on failure it is left unchanged. - Upgrades keep the old versions.
~/.local/binreceives only two entries:terminux(runsterminux-launch, which starts the daemon and opens the GUI) andterminux-qt-check. The other commands are in~/.local/opt/terminux/current/venv/bin/; use their full path or add that directory to yourPATH.- 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_compatiblebackend 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,
terminuxis the GUI itself; start Terminux withterminux-launch, which makes sure the daemon is running first. In the portable bundle,~/.local/bin/terminuxalready isterminux-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_FILEselects 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=1is 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
}
}
toolscan currently only bequery_orchestration_evidence;context_sectionscan only beconversation_history.allowed_runslists pre-approved run ids and attempts; normally leave it empty and let users bind runs throughrun_binding.- All four keys of
run_bindingare required: how many runs one session may bind (1–8), the receipt's runner (terminux-orfs-runishost_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"
}
endpointmust equal<TERMINUX_OPENAI_BASE_URL>/v1/chat/completionsandmodelmust equalTERMINUX_OPENAI_MODEL; otherwise every request is refused.approved_data_classeslists the data classes that may be sent;timing_path_evidence(per-stage timing-path data) is never sent unless listed. All five keys oflimitsare required.allowed_payload_sha256must be empty instructural_c2mode; inexact_digestmode 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-launchreads~/.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.logcontainsTERM_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 useterminux-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-launchon another host startsterminux-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=1to 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-guiis 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:
klayoutmust be onPATHwhen you run the command, or be added toPATHby--env-script. Without it the flow stops atcheck-klayoutwith 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-runto 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
-
Run the flow with
terminux-orfs-run. The receipt written to--receipt-outcontains the run'srun_idandattempt; the quality summary at the end of stdout also shows the run id. -
Bind the run (requires Profile mode, 4.7):
@@/bind-run /absolute/path/to/receipt.jsonOn 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-runremoves it. -
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.
-
Check for yourself:
@@open DQE Viewerand look at the checks under the "Fail" filter;terminux-orfs-reportprints 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 |
@@/proposalslists the proposals;@@/plansand@@/plan <plan_id>show plans, and@@/cancel-plan <plan_id> <plan_digest>cancels a plan.@@/resultslists execution results;@@/use-result <result_id> <result_digest>includes that result in later questions, and@@/clear-resultstops 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-planand/approve-allare always refused; every step must be approved with/approveand run with/executeon 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-runand/unbind-run;/plan-only,/approve,/execute,/task…,/work…and the others returnLOCAL_COMMAND_DISABLED_IN_PROFILE_MODE. Conversely,/bind-runis 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_compatiblebackend only; with another backend Terminux returnsPROFILE_PROVIDER_UNSUPPORTEDand 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.mkand 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 andterminux-work listreports 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>authorizecan 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.sqliteexists 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.
--designand--variantmay 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-doctoronly 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-DDpreviews the number of events; only with--forceare 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.shof the new version; after the Qt check passes,currentswitches 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.