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!