I Built a Local AI Agent That Plans Before Executing Linux Commands (Now Fully Dockerized)

I Built a Local AI Agent That Plans Before Executing Linux Commands (Now Fully Dockerized)

Most “AI agents” that run shell commands follow a simple flow:

User prompt → LLM → Execute command

That’s powerful.

It’s also dangerous.

So I built ZkzkAgent, a fully local Linux AI assistant that thinks and routes before it acts.

---

🚨 The Problem with Most Terminal AI Wrappers

A lot of open-source agents do this:

• Send user prompt to an LLM
• Generate shell command
• Execute immediately

There’s:

• No routing logic
• No conditional branching
• No confirmation flow
• No safety model

For real system environments, that’s risky.

---

🧠 What Makes ZkzkAgent Different

ZkzkAgent introduces a structured agent architecture:

User
  ↓
Router Node
  ├── Conversation Node
  ├── Retrieval Node
  └── Tool Execution Node
        ↓
  Confirmation (if needed)
        ↓
  Execution

Instead of blindly executing:

✔ It decides what type of task this is
✔ It branches based on context
✔ It enforces confirmation for dangerous actions
✔ It logs and returns results back into the conversation loop

Built with:

• LangGraph (stateful agent flow)
• Ollama (local LLM execution)
• Explicit tool safety filters

---

🔐 Safety Design Principles

I designed ZkzkAgent with 5 rules:

1. No hidden execution
2. Human confirmation for destructive commands
3. Deterministic routing
4. Full local-first architecture
5. Transparent tool layer

This makes it suitable for:

• Developers
• Linux power users
• Self-hosted environments
• AI experimentation

---

🐳 New: Docker Support

One of the biggest barriers to adoption was setup complexity.

Now ZkzkAgent includes official Docker support.

You can spin it up in a clean, isolated environment without touching your base system.

git clone https://github.com/zkzkGamal/zkzkAgent
cd zkzkAgent
docker build -t zkzkagent .
docker run -it zkzkagent

Reproducible.
Isolated.
Clean.

---

🎯 Why I Built This

I’m deeply interested in agentic AI systems — not just chatbots.

I wanted to experiment with:

• Router-based architectures
• Branching decision logic
• Human-in-the-loop safety
• Local execution models

Instead of building another “AI assistant,” I focused on architecture control.

---

🔮 What’s Next

Planned improvements:

• More granular permission layers
• Plugin-style tool system
• Sandboxed execution modes
• Better observability dashboard

---

💬 Feedback Welcome

If you’re experimenting with:

• AI agents
• LangGraph workflows
• Local-first LLM systems
• OS-level automation

I’d love your thoughts.

Repository:
https://github.com/zkzkGamal/zkzkAgent