ticca-tools 0.1.9
Standalone tool execution server for Ticca2 AI agents
License: MIT
Requires Python: >=3.10
Keywords: agents, ai, grpc, remote-execution, tools

# Ticca Tools

**Standalone tool execution server for Ticca2 AI agents**

[![PyPI](https://img.shields.io/pypi/v/ticca-tools.svg)](https://pypi.org/project/ticca-tools/)
[![Python](https://img.shields.io/pypi/pyversions/ticca-tools.svg)](https://pypi.org/project/ticca-tools/)
[![License](https://img.shields.io/pypi/l/ticca-tools.svg)](https://github.com/yourusername/ticca2/blob/main/LICENSE)

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:

```bash
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

```bash
# 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

```bash
# 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)

```bash
ticca-tools
```

### Custom port

```bash
ticca-tools --port 50052
```

### Load specific tool categories

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

### Show current configuration

```bash
ticca-tools config
```

### Reset configuration (regenerate credentials)

```bash
ticca-tools reset
```

## Commands

```bash
# 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

```bash
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

```bash
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

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

## Environment Variables

```bash
# 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

```bash
# Find process using port
lsof -i :50051

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

### Connection refused from main backend

```bash
# 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:

```bash
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):
```bash
python start_server.py --categories "File Operations,File Modifications"
```

**Server 2** (Commands only - isolated VM):
```bash
python start_server.py --categories "Command Runner"
```

**Server 3** (Browser automation):
```bash
python start_server.py --categories "Browser Control,Browser Navigation"
```

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