← Back to OpsTerm

🔧 Tech Stack

This document explains the technology used in OpsTerm — from the programming language to the communication protocol.

🎯 Summary

Zero mandatory dependencies — just Python 3 stdlib. Everything is built-in.
The only optional dependency: pip install cryptography (for vault).

🐍 Language: Python 3

Why Python?

Why NOT Go / Rust?

Python is the most practical choice for a CLI tool that must be zero-dependency and portable.

📦 Zero-Dependency Strategy

This is OpsTerm's main selling point. How is it done?

What Typically Uses Third-Party Libraries:

Custom YAML Parser

OpsTerm's YAML parser is minimal — it only supports the YAML subset that OpsTerm uses:

Supported:
- Key-value: key: value
- Nested mapping via indentation
- Lists: - item
- Nested objects in lists
- Comments (#)
- Strings, numbers, booleans, null

NOT supported:
- YAML anchors (&anchor, *alias)
- Multi-line strings (|, >)
- Inline JSON ({key: value})
- Complex types (timestamps, sets)

Why not use PyYAML?
1. Dependency — users would need to pip install it first
2. Overkill — we only use a small YAML subset
3. Maintainable — the parser is only ~80 lines, easy to understand

🗄️ SQLite History

Schema:

CREATE TABLE IF NOT EXISTS history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TEXT DEFAULT (datetime('now','localtime')),
    mode TEXT,        -- 'ai', 'ssh', 'workflow', 'pipe', 'shell', 'scp', 'vault'
    input TEXT,       -- command/question (max 500 chars)
    output TEXT       -- response (max 2000 chars)
);

Why SQLite?

• Built into Python (import sqlite3)
• Zero config — database file created automatically
• Permanent — history persists even after closing the terminal
• Searchable — can be queried using SQL

🔗 Protocol: OpenAI-Compatible API

The AI client uses a format that is compatible with OpenAI.

Request:

POST /v1/chat/completions
Authorization: Bearer ***
Content-Type: application/json

{
    "model": "deepseek-chat",
    "messages": [
        {"role": "system", "content": "You are a terminal assistant..."},
        {"role": "user", "content": "how to check disk usage"}
    ],
    "temperature": 0.3,
    "max_tokens": 1024
}

Response:

{
    "id": "chatcmpl-...",
    "choices": [{
        "message": {
            "role": "assistant",
            "content": "$ df -h /"
        }
    }]
}

Supported Providers:

🔐 Vault Encryption

Primary (recommended): cryptography.fernet.Fernet

Master Password
       │
       ▼
   PBKDF2 (SHA-256, 600k iterations, salt)
       │
       ▼
   AES-128-CBC (Fernet)
       │
       ▼
   Base64-encoded token
       │
       ▼
   vault.json

Fallback (no cryptography): HMAC + XOR

If cryptography is not installed, OpsTerm uses a fallback encryption:
1. Key derivation: PBKDF2 from hashlib (stdlib)
2. Encryption: XOR cipher with random IV
3. Integrity: HMAC-SHA256

⚠️ This fallback is less secure than AES. Recommended: pip install cryptography

📡 SSH/SCP Communication

SSH Command Building:

# Direct SSH
ssh -i ~/.ssh/id_ed25519 -p 22 ubuntu@43.157.204.199 -t

# Multi-hop via ProxyJump
ssh -J ubuntu@10.0.0.1:22 ubuntu@43.157.204.199 -t

SCP Command Building:

# Upload
scp -i ~/.ssh/id_ed25519 local.txt ubuntu@host:/remote/path/

# Download
scp -i ~/.ssh/id_ed25519 ubuntu@host:/remote/path/ local.txt

# Via jump host
scp -o ProxyJump=ubuntu@bastion:22 file.txt ubuntu@internal:/path/

Interaction:

• SSH: os.execvp() → replaces the process, interactive
• SCP: subprocess.run() → blocking until complete
• Workflow SSH: subprocess.run() → non-interactive, command via SSH

🐚 Zsh Plugin Integration

Hooks Used:

Aliases:

alias ai-last='ai last'
alias ai-explain='ai explain-last'

How ai-ti (AI + Terminal Integration) works:

ai-ti() {
    # 1. Ask AI
    ai "$*"

    # 2. Extract command from response (lines starting with $)
    # 3. Ask user: run it?
    # 4. If yes, execute
}

🎯 Comparison with Alternatives

Next: 🤔 Design Decisions →