tical-code: Honest AI Agent Deployment System

Core Philosophy: "Do NOT trust AI output, assume AI will hallucinate"

---

Overview

tical-code is an honest AI agent deployment system that doesn't trust AI outputs by default. Every tool execution is verified, every state is skeletonized, and every agent has stable reference points.

Three Pillars (v0.2)

1. Force-Verify System: Every tool MUST pass verification before returning results
2. Bootstrap Anchor: Stable reference points for AI grounding (SoulAgent compatible)
3. Memory Skeletonization: Aggressive summarization, preserve structure, enable recall

v0.3 New Features (Phase 1)

• Package Split: tical-code (Full) vs tical-code-lite (Minimal)
• Feature Detection: Auto-detect edition based on system capabilities
• Plugin System: Extensible architecture for specialized capabilities
• Enhanced CLI: tical config set/get commands
• Error Logging: Structured logging with rotation

v0.3 Security Hardening (P0 Fixes)

• Sandboxed Code Execution: Workflow CodeNode now uses sandbox with:
  • Three execution modes (Docker → RestrictedPython → RestrictedGlobals)
  • Whitelisted builtins only (no import, exec, file ops)
  • Timeout control (default 30s)
  • Memory limits (default 128MB)
• Autonomous Worker Loop: Worker now runs continuous AI loop:
  • 60-second heartbeat reporting
  • 7.5-minute system maintenance checks
  • Self-healing: crash auto-restart with backoff
  • Graceful shutdown on SIGTERM
• SSH Security Hardened:
  • Key-based auth only (no password)
  • Default user changed to ubuntu (not root)
  • Connection pooling for efficiency
• Lite/Full Import Isolation: Full-only modules check edition at import
• JSON Schema Validation: Uses battle-tested jsonschema library (Full)

---

Edition Comparison

Feature	Lite	Full
Core
Force-Verify System	✓	✓
Bootstrap Anchor	✓	✓
Memory Skeletonization	✓	✓
SSH Worker Management	✓	✓
CLI
tical setup	✓	✓
tical config	✓	✓
tical worker	✓	✓
tical anchor	✓	✓
tical memory	✓	✓
Plugins
Browser Automation	-	✓
Web Search	-	✓
X/Twitter Posting	-	✓
Trading (IB/Futu)	-	✓
Vision Analysis	-	✓
Messenger (Telegram)	-	✓
System Requirements
Min RAM	256MB	1GB
Min CPU	1 core	2 cores
Idle Memory	~50MB	~200MB
Use Case
Micro instances (Oracle)	✓	-
Single VPS	✓	✓
Multi-worker cluster	✓	✓
With plugins	-	✓

---

Quick Start

Installation

Lite Edition (minimal, 1C1G compatible):

pip install tical-code-lite
# or
pip install tical-code[lite]

Full Edition (with all plugins):

pip install tical-code[full]
# or
pip install tical-code  # default

Setup

# Auto-detect and setup
tical setup --edition auto

# Force specific edition
tical setup --edition lite
tical setup --edition full

# Check system detection
tical detect

Configuration

# View config
tical config get edition
tical config get log_level

# Set config
tical config set edition full
tical config set verify_level schema

# List all config
tical config list

Worker Management

# Add a worker
tical worker add tico-seoul [seoul-ip] --user root

# List workers
tical worker list

# Ping a worker
tical worker ping tico-seoul

# Execute command
tical exec tico-seoul "echo hello"

Anchors

# List anchors
tical anchor list

# Get anchor context
tical anchor context

# Get specific anchor
tical anchor get identity self

Status

tical status

---

Architecture

tical-code/
├── core/                    # Shared between Lite & Full
│   ├── verify.py            # Force-Verify system
│   ├── anchor.py            # Bootstrap Anchor
│   ├── memory.py            # Memory Skeletonization
│   ├── worker.py            # Base AI worker
│   ├── detection.py         # Feature detection
│   └── errors.py            # Error logging
├── cli/                     # CLI interface
│   ├── commands/            # Modular commands
│   └── config.py            # Config management
├── plugins/                 # Plugin system (Full)
│   ├── browser/             # Playwright/Selenium
│   ├── web-search/          # Web search
│   ├── trading/             # Trading APIs
│   ├── xurl/                # X/Twitter
│   ├── vision/              # Image analysis
│   └── messenger/           # Telegram/WeChat
└── deploy/                  # Deployment scripts

---

Plugin System

Every plugin MUST:

1. Inherit from TicalPlugin
2. Define metadata (name, version, edition)
3. Implement init() and shutdown()
4. Use @tool decorator for tools
5. Integrate Force-Verify
6. Use SkeletonMemory for persistence

from tical_code.plugins import TicalPlugin, tool, ToolResult, PluginEdition

class MyPlugin(TicalPlugin):
    metadata = PluginMetadata(
        name="my-plugin",
        version="0.1.0",
        edition=PluginEdition.FULL,
        dependencies=["some-package"],
    )
    
    async def init(self, context):
        self.use_memory()  # Use SkeletonMemory
    
    @tool
    async def my_tool(self, args: dict) -> ToolResult:
        # Verified tool execution
        return ToolResult(success=True, data={}, verified=True)

---

Security

• No AutoAddPolicy: SSH connections don't auto-trust hosts
• SA Key from Config: Security anchor key read from configuration
• Verification Required: Every tool output must be verified
• Minimal Dependencies: Lite edition has minimal attack surface

---

Development

# Clone
git clone https://github.com/tical-code/tical-code.git
cd tical-code

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
flake8 tical_code
black tical_code
isort tical_code

---

License

MIT License - see LICENSE

---

Links

• Documentation: https://tical-code.dev/docs
• GitHub: https://github.com/tical-code/tical-code
• PyPI: https://pypi.org/project/tical-code/