LinuxAgent

A Linux ops CLI where LLM-generated commands must pass deterministic policy and human approval before execution.

Quick Start · 中文快速开始 · English manual · 中文手册 · v4.1.0 release notes · share feedback

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:

git clone https://github.com/Eilen6316/LinuxAgent.git
cd LinuxAgent
./scripts/bootstrap.sh

Create or edit ~/.config/linuxagent/config.yaml:

api:
  provider: deepseek
  api_key: "replace-me"

For local Ollama:

api:
  provider: ollama
  base_url: http://127.0.0.1:11434/v1
  model: llama3.1
  api_key: ""
  tokenparameter: maxtokens

Then validate and start:

linuxagent check
linuxagent

Try a read-only request:

check 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

you: find services listening on port 8080
intent        -> LLM classifies the request plan          -> LLM proposes: ss -tlnp sport = :8080 policy        -> CONFIRM (LLMFIRSTRUN) 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