ticca-tools 0.1.0

Standalone tool execution server for Ticca2 AI agents

Ticca Tools

Standalone tool execution server for Ticca2 AI agents

Deploy tool execution servers anywhere and connect them to your Ticca2 backend with copy-paste credentials.

Features

• 🚀 One-command deployment - Run with uvx ticca-tools
• 🔐 Auto-generated credentials - Unique Server ID + API key on first start
• 📋 Copy-paste registration - Paste credentials into web UI, done!
• 🔒 Secure by default - API key required on every gRPC call
• 🌐 Deploy anywhere - Run on any machine, even behind NAT
• 📦 Self-contained - All tools included, no backend dependencies

Quick Start

Option 1: Using uvx (Recommended)

No installation required! Run directly:

uvx ticca-tools

# OUTPUT:
╔════════════════════════════════════════════════════════════╗
║        🚀 Ticca2 Tool Server Started!                      ║
╠════════════════════════════════════════════════════════════╣
║  Server ID:  tool-server-a3f2c8b9-4d1e-4f8a-9c2b...       ║
║  API Key:    sk_live_8f7e6d5c4b3a2f1e0d9c8b7a6f5e...      ║
║  Address:    192.168.1.10:50051                            ║
║  Tools:      12 tools loaded                               ║
╠════════════════════════════════════════════════════════════╣
║  📋 COPY THESE TO TICCA2 WEB UI:                           ║
║     Settings → Tool Servers → Add Server                   ║
╚════════════════════════════════════════════════════════════╝

That's it! The server is running with auto-generated credentials.

Option 2: Install with pip/pipx

# Install globally with pipx
pipx install ticca-tools

# Or with pip
pip install ticca-tools

# Run it
ticca-tools

Option 3: Copy Package to Remote Machine

# Copy to remote machine
scp -r tools_package/ user@192.168.1.10:/opt/ticca-tools/
ssh user@192.168.1.10

# Install and run
cd /opt/ticca-tools
pip install -e .
ticca-tools

Registration

1. Start the server (see Quick Start above)
2. Copy the Server ID and API Key from the output
3. Open Ticca2 Web UI: http://localhost:4020
4. Go to Settings → Tool Servers → Add Server
5. Paste the credentials
6. Click "Add Server"

Done! The system will connect and discover available tools.

Usage

Start server (default settings)

ticca-tools

Custom port

ticca-tools --port 50052

Load specific tool categories

ticca-tools --categories "File Operations,Command Runner"

Show current configuration

ticca-tools config

Reset configuration (regenerate credentials)

ticca-tools reset

Commands

# Start server (default command)
ticca-tools
ticca-tools start --port 50051 --host 0.0.0.0

# Show current credentials
ticca-tools config

# Regenerate credentials
ticca-tools reset

# Help
ticca-tools --help

What's Included

• All tool implementations - file ops, commands, browser automation, etc.
• gRPC server - handles tool execution
• Auto-registration - generates unique ID and API key
• Health monitoring - reports status to main backend
• Security - API key authentication on all requests

Deployment Options

Option 1: Docker

docker build -t ticca-tools .
docker run -p 50051:50051 ticca-tools

# Copy the credentials from container logs
docker logs <container-id>

Option 2: Systemd Service

sudo cp systemd/ticca-tools.service /etc/systemd/system/
sudo systemctl enable ticca-tools
sudo systemctl start ticca-tools

# View credentials
sudo journalctl -u ticca-tools -n 50

Option 3: Manual

python start_server.py --port 50051 --host 0.0.0.0

Environment Variables

# Optional: Set custom port
export TICCA_TOOL_PORT=50051

# Optional: Set custom host
export TICCA_TOOL_HOST=0.0.0.0

# Optional: Regenerate API key on restart (default: persist)
export TICCA_REGENERATE_KEY=false

# Optional: Enable TLS
export TICCA_TLS_ENABLED=true
export TICCA_TLS_CERT=/path/to/cert.pem
export TICCA_TLS_KEY=/path/to/key.pem

File Structure

tools_package/
├── README.md                   # This file
├── requirements.txt            # Python dependencies
├── start_server.py            # Main entry point
├── config.json                # Server config (auto-generated)
├── proto/
│   └── tool_service.proto     # gRPC protocol definition
├── server/
│   ├── __init__.py
│   ├── grpc_server.py         # gRPC server implementation
│   ├── auth.py                # API key authentication
│   └── registry.py            # Tool registry
├── tools/
│   ├── __init__.py
│   ├── file_operations.py     # File reading/listing tools
│   ├── file_modifications.py # File editing/deletion tools
│   ├── command_runner.py      # Shell command execution
│   ├── agent_tools.py         # Agent invocation tools
│   └── browser/               # Browser automation tools
│       ├── __init__.py
│       ├── control.py
│       ├── navigation.py
│       └── ...
└── Dockerfile                 # Docker image definition

Security

• API Key Required: All gRPC calls must include valid API key
• TLS Support: Enable encrypted communication
• Firewall: Configure firewall to only allow main backend IP
• Least Privilege: Run as non-root user

Troubleshooting

Port already in use

# Find process using port
lsof -i :50051

# Use different port
python start_server.py --port 50052

Connection refused from main backend

# Check firewall
sudo ufw allow from 192.168.1.5 to any port 50051

# Check server is listening
netstat -tulpn | grep 50051

API key rejected

The API key is stored in config.json. If you need to regenerate:

python start_server.py --regenerate-key

Updating Tools

To update tool implementations:

1. Stop the server
2. Replace files in tools/ directory
3. Restart the server

No need to update the main Ticca2 backend!

Multi-Server Setup

You can run multiple tool servers:

Server 1 (File Operations only):

python start_server.py --categories "File Operations,File Modifications"

Server 2 (Commands only - isolated VM):

python start_server.py --categories "Command Runner"

Server 3 (Browser automation):

python start_server.py --categories "Browser Control,Browser Navigation"

Each gets a unique Server ID - register all in the web UI!