IPTinCan Documentation

Everything you need to set up and run your own IPTinCan server. From first download to production deployment.

Getting Started

IPTinCan is a self-hosted voice and text chat application built in C++. It consists of two components:

• Server (itc-server) — Handles connections, channels, messages, voice routing, and data storage via SQLite.
• Client (itc-client) — The desktop application with a graphical interface built on ImGui with SDL2/OpenGL.

Both are included in a single download package. The server runs as a background process or console application, and the client connects to it over TCP (text/control) and UDP (voice/video).

Download & Install

Windows

1. Download the latest Windows release from update.iptincan.com.
2. Extract the ZIP archive to a folder of your choice (e.g., C:\IPTinCan).
3. No installation required. The executables are portable.

Linux

1. Download the latest Linux release from update.iptincan.com.
2. Extract the archive:

   tar -xzf iptincan-linux-x64.tar.gz
   cd iptincan

3. Make the binaries executable:

   chmod +x itc-server itc-client

First Run

Starting the server

# Windows
itc-server.exe

# Linux
./itc-server

On first launch, the server will:

1. Create a default server.toml configuration file in the working directory.
2. Initialize a SQLite database (server.db).
3. Generate self-signed TLS certificates (if TLS is enabled).
4. Start listening on TCP port 3784 and UDP port 3785.

Connecting with the client

# Windows
itc-client.exe

# Linux
./itc-client

In the client, enter the server address in the connection bar. If connecting to a server on the same machine, use 127.0.0.1. For remote connections, use the server's IP address or domain name. Create an account on the server, and you are ready to go.

Server Setup

The server is a single binary that manages all connected clients, channels, messages, voice routing, and file storage. It uses SQLite for persistent data storage, so there is no separate database to install or manage.

Directory structure

iptincan/
  itc-server         # Server binary
  itc-client         # Client binary
  server.toml        # Server configuration (created on first run)
  server.db          # SQLite database (created on first run)
  certs/             # TLS certificates (if enabled)
    server.key
    server.crt
  uploads/           # Uploaded files and images
  assets/            # Client assets (fonts, icons)

Configuration

The server is configured via server.toml. Here is a reference configuration with all available options:

[server]
name = "My IPTinCan Server"
description = "A community chat server"
tcp_port = 3784
udp_port = 3785
bind_address = "0.0.0.0"
max_clients = 100
motd = "Welcome to the server!"

[tls]
enabled = true
cert_file = "certs/server.crt"
key_file = "certs/server.key"
auto_generate = true        # Auto-generate self-signed certs

[database]
path = "server.db"

[voice]
enabled = true
max_voice_channels = 20
opus_bitrate = 64000        # bits/sec (32000-128000)
noise_suppression = true

[video]
enabled = true
max_bitrate = 1500000       # 1.5 Mbps
max_fps = 30

[screen_share]
enabled = true
max_bitrate = 2000000       # 2 Mbps
max_fps = 25

[auth]
registration_enabled = true
require_2fa = false
steam_enabled = false
xbox_enabled = false

[auth.steam]
api_key = ""

[auth.xbox]
client_id = ""
client_secret = ""

[moderation]
automod_enabled = true
automod_keywords = []       # List of banned words
slowmode_default = 0        # Seconds (0 = disabled)

[licensing]
enabled = false
license_key = ""
api_url = "https://license.iptincan.com"

[discovery]
public = false              # List on server browser
tags = []

TLS / SSL Setup

IPTinCan supports TLS 1.2+ for encrypted transport. There are three options for TLS certificates:

Option 1: Auto-generated self-signed certificates

The simplest option. Enable TLS with auto_generate = true in server.toml, and the server will generate a self-signed certificate on first run. Clients will use trust-on-first-use (TOFU) fingerprint pinning to verify the server on subsequent connections.

[tls]
enabled = true
auto_generate = true

Option 2: Let's Encrypt (recommended for public servers)

For servers with a domain name, use Let's Encrypt for free, trusted certificates:

1. Install Certbot:

   sudo apt install certbot

2. Obtain a certificate:

   sudo certbot certonly --standalone -d chat.example.com

3. Configure the server:

   [tls]
   enabled = true
   cert_file = "/etc/letsencrypt/live/chat.example.com/fullchain.pem"
   key_file = "/etc/letsencrypt/live/chat.example.com/privkey.pem"
   auto_generate = false

4. Set up auto-renewal with a cron job:

   0 0 1 * * certbot renew --quiet && systemctl restart itc-server

Option 3: Custom certificate

Use any PEM-format certificate and private key. Point cert_file and key_file to your files in server.toml.

Docker Setup

IPTinCan provides official Docker images for easy deployment:

# Pull the latest image
docker pull iptincan/server:latest

# Run with default settings
docker run -d \
  --name iptincan \
  -p 3784:3784 \
  -p 3785:3785/udp \
  -v iptincan-data:/data \
  iptincan/server:latest

# Run with custom config
docker run -d \
  --name iptincan \
  -p 3784:3784 \
  -p 3785:3785/udp \
  -v /path/to/server.toml:/data/server.toml \
  -v iptincan-data:/data \
  iptincan/server:latest

Docker Compose

version: '3.8'
services:
  iptincan:
    image: iptincan/server:latest
    container_name: iptincan
    restart: unless-stopped
    ports:
      - "3784:3784"       # TCP (text/control)
      - "3785:3785/udp"   # UDP (voice/video)
    volumes:
      - ./server.toml:/data/server.toml
      - iptincan-data:/data
    environment:
      - ITC_SERVER_NAME=My Server
      - ITC_MAX_CLIENTS=100

volumes:
  iptincan-data:

Dynamic DNS

If you are hosting from a home connection with a dynamic IP address, IPTinCan offers free dynamic DNS subdomains under *.servers.iptincan.com.

Setup

1. Register your server with a chosen subdomain:

   # In server.toml
   [discovery]
   public = true
   hostname = "myserver.servers.iptincan.com"

2. The server will automatically update its DNS record when its public IP changes.
3. Friends can connect using myserver.servers.iptincan.com instead of an IP address.

Dynamic DNS is free for all registered servers. The subdomain is reserved as long as the server checks in at least once every 30 days.

Clustering

For large deployments, IPTinCan supports a primary-worker cluster architecture:

• Primary node — Handles database, authentication, and cluster coordination.
• Worker nodes — Handle client connections and voice routing, syncing state with the primary.

# Primary node config
[cluster]
enabled = true
role = "primary"
cluster_port = 3786
auth_secret = "your-hmac-secret-here"    # Shared secret for worker auth

# Worker node config
[cluster]
enabled = true
role = "worker"
primary_address = "10.0.0.1:3786"
auth_secret = "your-hmac-secret-here"

Worker nodes automatically synchronize their user roster, channel list, and permissions with the primary. The cluster gateway distributes clients across workers based on load.

Licensing

IPTinCan is free to use. License registration is optional and provides:

• Access to the server discovery browser (public listing).
• Dynamic DNS subdomains under *.servers.iptincan.com.
• Automatic update notifications.
• Usage analytics for your server (opt-in, never shared).

To register:

1. Visit iptincan.com/register to obtain a free license key.
2. Add the key to server.toml:

   [licensing]
   enabled = true
   license_key = "ITC-XXXX-XXXX-XXXX-XXXX"

3. Restart the server. It will validate the key and enable licensed features.

Servers without a license key work fully. All chat, voice, and video features function identically with or without a license.

Admin Panel

The client includes a built-in admin panel for server administrators. Access it via the gear icon in the sidebar (visible only to users with admin privileges).

The admin panel includes five tabs:

• Users — View all accounts, change roles, kick/ban users, reset passwords.
• Channels — Create, edit, and delete channels. Configure categories, permissions, and slow mode.
• Moderation — Review audit logs, manage warnings, configure auto-moderation keyword filters.
• Server — View server statistics, configure MOTD, manage discovery settings.
• Cluster — Monitor cluster node status, view connected worker nodes and their load.

Moderation

IPTinCan provides comprehensive moderation tools:

• Kick — Remove a user from the server. They can reconnect.
• Ban — Permanently block a user by account and/or IP address, with optional duration and reason.
• Timeout — Temporarily mute a user for a specified duration.
• Slow Mode — Limit message frequency per channel (e.g., one message every 5 seconds).
• Warnings — Issue formal warnings with notes. Warnings are tracked in the user's moderation history.
• Auto-Moderation — Configurable keyword filters that automatically delete messages and optionally timeout the sender.
• Audit Log — Every moderation action is logged with timestamp, moderator, target, and reason.

Client Guide

Connecting to a server

Enter the server address in the connection bar at the top of the window. The format is:

hostname:port      (e.g., chat.example.com:3784)
hostname           (uses default port 3784)
IP address:port    (e.g., 192.168.1.100:3784)

Creating an account

On first connection to a server, you will be prompted to create an account. Choose a username and password. Alternatively, you can sign in with Steam or Xbox if the server has those authentication methods enabled.

Chat features

• Markdown — Use **bold**, *italic*, ~~strikethrough~~, and `code` in messages.
• Code blocks — Triple backticks with optional language for syntax highlighting.
• Reactions — Right-click a message to add emoji reactions.
• Threads — Right-click a message and select "Start Thread" for focused discussions.
• File sharing — Drag and drop files into the chat window, or use the upload button.
• Image preview — Images are displayed inline with expandable previews.
• Link preview — URLs are fetched and displayed with title, description, and thumbnail.
• Custom emojis — Server admins can upload custom emojis accessible via :shortcode:.

Voice Settings

Voice chat uses the Opus codec over UDP for low-latency, high-quality audio.

Input modes

• Push-to-Talk (PTT) — Hold a configurable key to transmit. Default: V.
• Voice Activity Detection (VAD) — Automatic transmission when you speak. Adjustable sensitivity threshold.

Audio settings

• Input device — Select your microphone.
• Output device — Select your speakers or headphones.
• Input volume — Amplify or reduce your microphone level.
• Output volume — Master volume for all incoming audio.
• Per-user volume — Right-click a user in the channel list to adjust their individual volume.
• Noise suppression — FFT-based spectral subtraction to reduce background noise.
• Noise gate — Configurable threshold to cut audio below a certain level.

Keyboard Shortcuts

Ports & Protocols

FAQ