LinuxAgent
LLM-driven Linux operations assistant CLI with mandatory HITL safety, policy engine, runbooks, SSH guards, and audit trails.
A Linux ops CLI where LLM-generated commands must pass deterministic policy and human approval before execution. The project is written primarily in Python, first published in 2025. Key topics include: agent, audit, cli, hitl, langgraph.
LinuxAgent is not a free-form shell chatbot and not an autonomous remediator. It
lets an LLM propose Linux operations, but execution stays behind deterministic
policy checks, Human-in-the-Loop confirmation, SSH safety guards, output
redaction, and a hash-chained audit log.
The default runtime is Python v4. LangGraph remains the old Python runtime and
rollback anchor. A TypeScript v5 rewrite is in progress under ts/, with
@earendil-works/pi-agent-core as the target TS ReAct loop, but
linuxagent-ts remains experimental until the parity gates in
TypeScript v5 pass and maintainers approve a
separate cutover release.
Why It Exists
LLM command agents usually fail at the exact point operators care about: trust.
LinuxAgent keeps that trust boundary outside the model.
| Principle | What LinuxAgent does |
|---|---|
| The model is not trusted | First-time LLM-generated commands require confirmation |
| Safety is policy, not substring matching | Commands are tokenized and evaluated by a capability-based policy engine |
| Output may contain secrets | Tool output is guarded and redacted before model-facing analysis |
| SSH must not silently trust hosts | Remote execution uses known-host verification and shell-syntax guards |
| Every approval should be reviewable | HITL decisions are written to a 0o600 hash-chained audit log |
One-Minute Start
From a source checkout:
bashgit clone https://github.com/Eilen6316/LinuxAgent.git cd LinuxAgent ./scripts/bootstrap.sh
Create or edit ~/.config/linuxagent/config.yaml:
yamlapi: provider: deepseek api_key: "replace-me"
For local Ollama:
yamlapi: provider: ollama base_url: http://127.0.0.1:11434/v1 model: llama3.1 api_key: "" token_parameter: max_tokens
Then validate and start:
bashlinuxagent check linuxagent
Try a read-only request:
textcheck the Linux version
config.yaml must be owned by the current user and chmod 600; real secrets
are not loaded from .env. More provider paths are in the
Provider Matrix.
First Confirmation
When a first LLM-generated command appears, LinuxAgent shows the command,
policy result, matched rules, sandbox metadata, and risk summary before
execution.
Choose:
| Choice | Meaning |
|---|---|
Yes / [y] | Run this command once |
Yes, don't ask again / [a] | Allow the same argv command shape only in this conversation and the same /resume thread |
No / [n] | Refuse this operation |
Destructive commands, never_whitelist policy matches, and SSH batch
operations are never covered by conversation approval. Non-TTY confirmation
requests fail closed.
Use !uname -a for operator-authored direct command mode. Use /resume to
resume a saved conversation or pending HITL checkpoint, and /new to start a
fresh context.
What A Turn Looks Like
textyou: find services listening on port 8080 intent -> LLM classifies the request plan -> LLM proposes: ss -tlnp sport = :8080 policy -> CONFIRM (LLM_FIRST_RUN) confirm -> operator approves in terminal execute -> subprocess argv, no shell=True analyze -> concise operator summary audit.log -> hash-chained JSONL decision record
The status line keeps active task plans visible during long turns, including
when commands are being confirmed or executed.
Safety Boundaries
| Operation | Default behavior |
|---|---|
| User-authored read-only command | May run when policy returns SAFE |
| First LLM-generated command | CONFIRM |
| Conversation-approved LLM command | May skip repeat confirmation only for the same argv command shape in the same conversation thread |
| Destructive command | CONFIRM every time; never conversation-whitelisted |
| Command targeting root or protected paths | BLOCK when matched by policy |
| SSH batch across two or more hosts | Explicit batch confirmation with target hosts and remote profiles |
| Non-TTY confirmation request | Auto-deny |
| Unknown SSH host | Reject by default |
| Default sandbox runner | Records profile metadata only; no process isolation |
| Enabled safe sandbox profile unavailable | Fail closed before spawning |
LinuxAgent is intended for controlled operator-in-the-loop use. For deployment
boundaries, read Operator Safety,
Threat Model, and
Production Readiness.
Core Capabilities
| Capability | Why it matters |
|---|---|
| Capability-based policy engine | Produces SAFE / CONFIRM / BLOCK, risk scores, capabilities, and matched rules |
| Structured command plans | LLM output must validate before policy or execution paths |
| File patch workflow | Script/code/config edits use reviewed unified diffs and transactional apply |
| Read-only workspace tools | The planner can inspect allowed files before proposing changes |
| Explicit resume control | New sessions do not inherit previous chats unless /resume is used |
Direct ! command mode | Runs operator-authored commands without an AI-generated reply |
| SSH cluster guard | Batch confirmation, remote shell metacharacter blocking, and remote profile audit |
| Output protection | Command results are redacted and bounded before model-facing analysis |
| Hash-chained audit | linuxagent audit verify detects in-place edits, tail truncation, and deletion of the local audit log (via a tip-hash anchor sidecar) |
| Local advisory memory | Optional local memory can guide planning but never changes policy or HITL |
| Read-only MCP prototype | linuxagent mcp exposes policy classify and audit verify tools only |
Install Paths
| Path | Use when |
|---|---|
./scripts/bootstrap.sh | You are working from a source checkout and want linuxagent available from any directory |
pip install -c constraints.txt https://github.com/Eilen6316/LinuxAgent/releases/download/v4.1.0/linuxagent-4.1.0-py3-none-any.whl | You want the GitHub Release wheel |
pip install linuxagent | You want the PyPI package after release publication |
pip install -e ".[dev]" | You are developing or running the full local gate |
pip install -e ".[anthropic]" | You need the optional Anthropic provider |
Documentation
| Start here | Purpose |
|---|---|
| Quick Start / 中文快速开始 | Install, configure, and run the first safe request |
| Documentation index | Main navigation for all long-form docs |
| English manual / 中文手册 | User workflow overview |
| Provider Matrix | Provider setup paths and compatibility status |
| Operator Safety | Plain-language safety boundaries |
| Security Policy | Vulnerability reporting and supported versions |
| Development Guide | Local validation, architecture boundaries, and contribution checks |
| TypeScript v5 | Experimental rewrite status |
| Release Notes | Latest released changes |
Mirrors And Community
| Link | Notes |
|---|---|
| GitHub | Primary repository |
| GitCode | Mirror |
| Gitee | Mirror |
| QQ Group 281392454 | Community |
| CSDN intro | Project article |
License
MIT
Contributors
Showing top 2 contributors by commit count.
