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. It consists of two components:

• Server (itc-server) — A C++ binary that handles connections, channels, messages, voice routing, and data storage via SQLite.
• Client — A Flutter app for Windows, macOS, iOS, and Android. Connects to your server over TCP (text/control) and UDP (voice/video).

The server runs as a background process or console application. The client app is downloaded separately and connects to it using a server address or connection code.

Download & Install

Server

1. Download the latest server binary for your platform from update.iptincan.com.
2. Extract the archive to a folder of your choice.
3. No installation required. The server binary is portable.

Client App

The IPTinCan client is a Flutter app available for multiple platforms:

• Windows — Download from update.iptincan.com.
• macOS — Download from update.iptincan.com.
• iOS — Available on the App Store.
• Android — Available on Google Play.

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 (itc-server.db).
3. Create a default admin account (username: chatter, password: chatter).
4. Start listening on TCP port 3784, UDP port 3785, and REST port 3786.

Connecting with the client

Open the IPTinCan app. On the connect screen, you can enter your server details in one of two ways:

• Manual entry — Type the server address (e.g., chat.example.com or 192.168.1.100) and port.
• Connection code — Enter a connection code in ITC-xxxxx format. Connection codes encode the server name, host, port, and TLS setting as a base64 string, making it easy to share server details.

Once connected, log in with the default credentials (chatter / chatter) or create a new account if registration is enabled. You can also sign in with Steam, Xbox, or Google if the server has those authentication methods enabled.

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
  server.toml        # Server configuration (created on first run)
  itc-server.db      # SQLite database (created on first run)
  server-cert.pem    # TLS certificate (if TLS enabled)
  server-key.pem     # TLS private key (if TLS enabled)
  uploads/           # Uploaded files and images

Configuration

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

[server]
name = "My IPTinCan Server"
description = "A community chat server"
bind_address = "0.0.0.0"
tcp_port = 3784
udp_port = 3785
rest_port = 3786
max_users = 100
motd = "Welcome to IPTinCan!"
log_level = "info"                  # trace, debug, info, warn, error
shutdown_grace_seconds = 5
max_storage_bytes = 0               # 0 = unlimited
tags = ["gaming", "community"]

[database]
path = "itc-server.db"

[tls]
enabled = true
cert_path = "server-cert.pem"
key_path = "server-key.pem"

[auth]
allow_registration = true
session_ttl_seconds = 86400         # 24 hours
default_user = "chatter"
default_password = "chatter"

[license]
key = ""
server_url = "https://license.iptincan.com"
public_server = false               # List on server browser
heartbeat_interval = 300            # Seconds

[steam]
enabled = false
api_key = ""
callback_base_url = "http://localhost:3786"

[xbox]
enabled = false
client_id = ""
client_secret = ""
callback_base_url = "http://localhost:3786"

[google]
enabled = false
client_id = ""
client_secret = ""
callback_base_url = "http://localhost:3786"

[cluster]
enabled = false
role = "primary"                    # "primary" or "worker"
node_name = "node-1"
cluster_port = 3787                 # Inter-node TCP
cluster_udp_port = 3788             # Inter-node UDP voice relay
cluster_secret = ""                 # Shared HMAC secret (min 16 chars)
primary_address = ""                # Workers only: address of primary
primary_cluster_port = 3787

[vpn]
enabled = false
subnet = "10.8.0.0/24"
dns_server = "1.1.1.1"
max_bandwidth_kbps = 0              # 0 = unlimited
tun_device_name = "itc-vpn0"

[notifications]
admin_email = ""
billing_worker_url = ""
billing_admin_token = ""

TLS / SSL Setup

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

Option 1: Self-signed certificates

Generate a self-signed certificate using OpenSSL, then point the server at it. Clients will use trust-on-first-use (TOFU) fingerprint pinning to verify the server on subsequent connections.

# Generate a self-signed cert
openssl req -x509 -newkey rsa:4096 -keyout server-key.pem \
  -out server-cert.pem -days 365 -nodes -subj "/CN=iptincan"

[tls]
enabled = true
cert_path = "server-cert.pem"
key_path = "server-key.pem"

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_path = "/etc/letsencrypt/live/chat.example.com/fullchain.pem"
   key_path = "/etc/letsencrypt/live/chat.example.com/privkey.pem"

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_path and key_path to your files in server.toml.

Docker Setup

IPTinCan provides 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 \
  -p 3786:3786 \
  -v iptincan-data:/data \
  iptincan/server:latest

# Run with custom config
docker run -d \
  --name iptincan \
  -p 3784:3784 \
  -p 3785:3785/udp \
  -p 3786:3786 \
  -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)
      - "3786:3786"       # REST API / OAuth callbacks
    volumes:
      - ./server.toml:/data/server.toml
      - iptincan-data:/data

volumes:
  iptincan-data:

Dynamic DNS

If you are hosting from a home connection with a dynamic IP address, IPTinCan supports free dynamic DNS subdomains for managed hosting customers.

How it works

Managed hosting plans (Community and Organization tiers) receive a custom subdomain under *.iptincan.com. The DNS records are automatically managed by our DNS worker and kept in sync with your server's IP address.

For self-hosted servers, you can use any third-party dynamic DNS service (No-IP, DuckDNS, etc.) and point it at your server's IP address. Clients can then connect using the hostname instead of an IP.

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"
node_name = "primary-1"
cluster_port = 3787                 # Inter-node TCP
cluster_udp_port = 3788             # Inter-node UDP voice relay
cluster_secret = "your-hmac-secret-here"   # Min 16 characters

# Worker node config
[cluster]
enabled = true
role = "worker"
node_name = "worker-1"
cluster_port = 3787
cluster_udp_port = 3788
cluster_secret = "your-hmac-secret-here"
primary_address = "10.0.0.1"
primary_cluster_port = 3787

Worker nodes automatically synchronize their user roster, channel list, and permissions with the primary. The cluster uses HMAC authentication to verify inter-node communication. Voice packets are relayed between nodes over UDP port 3788.

VPN

IPTinCan includes a built-in full-tunnel VPN that routes client internet traffic through the server. This is useful for privacy, accessing geo-restricted content, or connecting clients on the same virtual network.

[vpn]
enabled = true
subnet = "10.8.0.0/24"
dns_server = "1.1.1.1"
max_bandwidth_kbps = 0              # 0 = unlimited
tun_device_name = "itc-vpn0"

The VPN uses a TUN device on the server and assigns each client an IP address from the configured subnet. On Windows, the server uses WinTUN; on Linux, it creates a standard TUN device. Clients can enable the VPN from the Settings panel in the app. Android clients use the native VpnService API.

Licensing

IPTinCan is free to self-host. License registration is optional and provides:

• Access to the server discovery browser (public listing).
• Automatic update notifications.
• Managed hosting features (custom subdomains, backups, etc.).

To register:

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

   [license]
   key = "ITC-XXXX-XXXX-XXXX-XXXX"
   server_url = "https://license.iptincan.com"
   public_server = true                # List on server browser
   heartbeat_interval = 300

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

Servers without a license key work fully. All chat, voice, video, and VPN 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 eight 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 Config — View server statistics, configure MOTD, manage server settings.
• Cluster — Monitor cluster node status, view connected worker nodes and their load.
• Access Tokens — Generate and manage API access tokens for programmatic server access.
• Approvals — Review and approve/deny pending user registration requests (when approval mode is enabled).
• VPN — View connected VPN sessions, manage bandwidth limits, and configure VPN settings.

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.

Access Tokens

Access tokens allow programmatic access to the server's REST API on port 3786. Admins can generate tokens from the Access Tokens tab in the admin panel. Tokens can be scoped and revoked at any time.

User Approval

When user approval mode is enabled, new account registrations are held in a pending state until an administrator approves them. This is useful for private communities that want to vet new members before granting access.

Pending registrations appear in the Approvals tab of the admin panel. Admins can approve or deny each request. Approved users receive access immediately; denied users are notified and their registration is discarded.

Client Guide

Connecting to a server

Open the IPTinCan app. On the connect screen, enter your server details:

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

You can also use a connection code (format: ITC-xxxxx) which encodes the server name, address, port, and TLS setting. Connection codes make it easy to share server details with friends.

Authentication

IPTinCan supports multiple sign-in methods:

• Username & password — Create an account directly on the server.
• Steam — Sign in with your Steam account (OpenID 2.0).
• Xbox — Sign in with your Microsoft/Xbox account (OAuth 2.0).
• Google — Sign in with your Google account (OAuth 2.0).

Available sign-in methods depend on what the server administrator has enabled. OAuth buttons appear on the connect screen when available.

Chat features

• Markdown — Use **bold**, *italic*, ~~strikethrough~~, and `code` in messages.
• Code blocks — Triple backticks with optional language for syntax highlighting.
• Reactions — React to messages with built-in or custom emojis.
• Threads — Start threaded discussions on any message.
• File sharing — Drag and drop files into the chat, 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:.
• Custom status — Set a custom status message and emoji visible to other users.
• Direct messages — Send private messages to individual users.

Video calls & screen sharing

Start a video call from any voice channel. Video calls support up to 8 participants with adaptive quality. Screen sharing is available with adjustable resolution and frame rate.

VPN

If the server has VPN enabled, you can activate it from the Settings panel. The VPN routes your internet traffic through the server, providing an encrypted tunnel. On Android, this uses the native VpnService API.

Server browser

Browse public IPTinCan servers from the app. Search and filter by tags, view server details and ping, and bookmark servers for quick access.

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.
• 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 — Adjust individual volume for each user.
• Noise suppression — FFT-based spectral subtraction to reduce background noise.
• Noise gate — Configurable threshold to cut audio below a certain level.

Ports & Protocols

FAQ