Quickstart

This guide walks you through creating a complete ICE connection between two peers. We’ll build a “ping-pong” application where two ICE agents establish a connection and exchange messages.

This example demonstrates local peer-to-peer communication. Both agents run on the same machine, but the same principles apply to remote connections.

Overview

Establishing an ICE connection involves:

Creating ICE agents on both sides
Gathering local candidates (network addresses)
Exchanging credentials and candidates with the remote peer
Performing connectivity checks
Using the established connection to send/receive data

Complete Example

Here’s a full working example that establishes an ICE connection between two peers:

Create the ICE agents

Each peer creates an Agent with network configuration:

agent, err := ice.NewAgentWithOptions(
    ice.WithNetworkTypes([]ice.NetworkType{ice.NetworkTypeUDP4}),
)
if err != nil {
    panic(err)
}
defer agent.Close()

WithNetworkTypes restricts which network protocols to use. Options include:

NetworkTypeUDP4 - IPv4 UDP (most common)
NetworkTypeUDP6 - IPv6 UDP
NetworkTypeTCP4 - IPv4 TCP
NetworkTypeTCP6 - IPv6 TCP

Set up event handlers

// Handle discovered candidates
agent.OnCandidate(func(candidate ice.Candidate) {
    if candidate == nil {
        return // Gathering complete
    }
    
    // Send candidate to remote peer
    candidateStr := candidate.Marshal()
    sendToRemotePeer(candidateStr)
})

// Monitor connection state
agent.OnConnectionStateChange(func(state ice.ConnectionState) {
    fmt.Printf("Connection state changed: %s\n", state.String())
})

OnCandidate is called with nil when candidate gathering completes.

Exchange ICE credentials

Get local credentials and share them with the remote peer:

// Get local credentials
localUfrag, localPwd, err := agent.GetLocalUserCredentials()
if err != nil {
    panic(err)
}

// Send to remote peer and receive theirs
sendCredentials(localUfrag, localPwd)
remoteUfrag, remotePwd := receiveRemoteCredentials()

The username fragment (ufrag) and password (pwd) are used to authenticate connectivity checks.

Gather candidates

Start gathering network candidates:

err = agent.GatherCandidates()
if err != nil {
    panic(err)
}

This discovers all available network paths (local addresses, STUN reflexive addresses, TURN relay addresses).

Add remote candidates

As you receive candidates from the remote peer, add them to your agent:

// When you receive a candidate from remote peer
candidateStr := receiveFromRemotePeer()
candidate, err := ice.UnmarshalCandidate(candidateStr)
if err != nil {
    panic(err)
}

err = agent.AddRemoteCandidate(candidate)
if err != nil {
    panic(err)
}

Establish the connection

One peer acts as “controlling” and dials, the other “accepts”:

var conn *ice.Conn

if isControlling {
    // Controlling side initiates
    conn, err = agent.Dial(context.TODO(), remoteUfrag, remotePwd)
} else {
    // Controlled side waits
    conn, err = agent.Accept(context.TODO(), remoteUfrag, remotePwd)
}
if err != nil {
    panic(err)
}
defer conn.Close()

One peer must be controlling and the other controlled. Both cannot be the same role.

Send and receive data

Once connected, use the ice.Conn like any net.Conn:

// Send data
message := []byte("Hello, ICE!")
n, err := conn.Write(message)
if err != nil {
    panic(err)
}

// Receive data
buffer := make([]byte, 1500)
n, err = conn.Read(buffer)
if err != nil {
    panic(err)
}
fmt.Printf("Received: %s\n", string(buffer[:n]))

Full Working Example

Here’s a complete ping-pong example that demonstrates the entire flow. This example uses HTTP for signaling (exchanging credentials and candidates):

package main

import (
	"bufio"
	"context"
	"flag"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"time"

	"github.com/pion/ice/v4"
	"github.com/pion/randutil"
)

var (
	isControlling                 bool
	iceAgent                      *ice.Agent
	remoteAuthChannel             chan string
	localHTTPPort, remoteHTTPPort int
)

// HTTP handler to receive remote credentials
func remoteAuth(_ http.ResponseWriter, r *http.Request) {
	if err := r.ParseForm(); err != nil {
		panic(err)
	}
	remoteAuthChannel <- r.PostForm["ufrag"][0]
	remoteAuthChannel <- r.PostForm["pwd"][0]
}

// HTTP handler to receive remote candidates
func remoteCandidate(_ http.ResponseWriter, r *http.Request) {
	if err := r.ParseForm(); err != nil {
		panic(err)
	}

	c, err := ice.UnmarshalCandidate(r.PostForm["candidate"][0])
	if err != nil {
		panic(err)
	}

	if err := iceAgent.AddRemoteCandidate(c); err != nil {
		panic(err)
	}
}

func main() {
	remoteAuthChannel = make(chan string, 3)

	flag.BoolVar(&isControlling, "controlling", false, "is ICE Agent controlling")
	flag.Parse()

	// Configure ports based on role
	if isControlling {
		localHTTPPort = 9000
		remoteHTTPPort = 9001
	} else {
		localHTTPPort = 9001
		remoteHTTPPort = 9000
	}

	// Start HTTP server for signaling
	http.HandleFunc("/remoteAuth", remoteAuth)
	http.HandleFunc("/remoteCandidate", remoteCandidate)
	go func() {
		if err := http.ListenAndServe(fmt.Sprintf(":%d", localHTTPPort), nil); err != nil {
			panic(err)
		}
	}()

	fmt.Printf("Local Agent is %s\n", map[bool]string{true: "controlling", false: "controlled"}[isControlling])
	fmt.Print("Press 'Enter' when both processes have started")
	bufio.NewReader(os.Stdin).ReadBytes('\n')

	// Create ICE agent
	var err error
	iceAgent, err = ice.NewAgentWithOptions(
		ice.WithNetworkTypes([]ice.NetworkType{ice.NetworkTypeUDP4}),
	)
	if err != nil {
		panic(err)
	}

	// Handle candidates
	iceAgent.OnCandidate(func(c ice.Candidate) {
		if c == nil {
			return
		}
		_, err := http.PostForm(
			fmt.Sprintf("http://localhost:%d/remoteCandidate", remoteHTTPPort),
			url.Values{"candidate": {c.Marshal()}},
		)
		if err != nil {
			panic(err)
		}
	})

	// Monitor connection state
	iceAgent.OnConnectionStateChange(func(c ice.ConnectionState) {
		fmt.Printf("ICE Connection State: %s\n", c.String())
	})

	// Exchange credentials
	localUfrag, localPwd, err := iceAgent.GetLocalUserCredentials()
	if err != nil {
		panic(err)
	}

	_, err = http.PostForm(
		fmt.Sprintf("http://localhost:%d/remoteAuth", remoteHTTPPort),
		url.Values{"ufrag": {localUfrag}, "pwd": {localPwd}},
	)
	if err != nil {
		panic(err)
	}

	remoteUfrag := <-remoteAuthChannel
	remotePwd := <-remoteAuthChannel

	// Gather candidates
	if err = iceAgent.GatherCandidates(); err != nil {
		panic(err)
	}

	// Establish connection
	var conn *ice.Conn
	if isControlling {
		conn, err = iceAgent.Dial(context.TODO(), remoteUfrag, remotePwd)
	} else {
		conn, err = iceAgent.Accept(context.TODO(), remoteUfrag, remotePwd)
	}
	if err != nil {
		panic(err)
	}

	// Send messages
	go func() {
		for {
			time.Sleep(time.Second * 3)
			val, _ := randutil.GenerateCryptoRandomString(15, "abcdefghijklmnopqrstuvwxyz")
			if _, err := conn.Write([]byte(val)); err != nil {
				panic(err)
			}
			fmt.Printf("Sent: '%s'\n", val)
		}
	}()

	// Receive messages
	buf := make([]byte, 1500)
	for {
		n, err := conn.Read(buf)
		if err != nil {
			panic(err)
		}
		fmt.Printf("Received: '%s'\n", string(buf[:n]))
	}
}

Run the example: Open two terminals and run the program with and without the -controlling flag. Press Enter in both when ready, and watch the connection establish!

Key Concepts Explained

ICE Candidates

Candidates represent possible network paths:

Host candidates: Your local IP addresses and ports
Server reflexive candidates: Your public IP (discovered via STUN)
Relay candidates: TURN server addresses (for difficult NAT scenarios)

Controlling vs Controlled

ICE requires one peer to be “controlling” (initiates nomination) and the other “controlled” (responds). This is separate from client/server - either peer can be controlling.

Connection States

Watch for these states during connection:

ConnectionStateNew          // Initial state
ConnectionStateChecking     // Testing candidate pairs
ConnectionStateConnected    // Connection established
ConnectionStateCompleted    // All checks done

Adding STUN/TURN Servers

For connections across the internet, add STUN/TURN servers:

agent, err := ice.NewAgentWithOptions(
    ice.WithNetworkTypes([]ice.NetworkType{ice.NetworkTypeUDP4}),
    ice.WithUrls([]*stun.URI{
        stun.MustParseURI("stun:stun.l.google.com:19302"),
    }),
)

For relay (TURN) support:

import "github.com/pion/stun/v3"

turnURI := stun.MustParseURI("turn:turn.example.com:3478?transport=udp")
agent, err := ice.NewAgentWithOptions(
    ice.WithUrls([]*stun.URI{turnURI}),
)

TURN servers require authentication. Configure credentials in the URI or use WithTURNCredentials option.

Continual Gathering

For applications that need to adapt to network changes (like mobile apps), enable continual gathering:

agent, err := ice.NewAgentWithOptions(
    ice.WithContinualGatheringPolicy(ice.GatherContinually),
    ice.WithNetworkMonitorInterval(2 * time.Second),
)

This monitors network interfaces and gathers new candidates when networks change.

Next Steps

Agent Configuration

Learn about all available agent options

Candidate Types

Deep dive into ICE candidates

NAT Traversal

Configure STUN and TURN servers

Examples

Explore more code examples

Get Started

Core Concepts

Guides

Advanced

Overview

Complete Example

Full Working Example

Key Concepts Explained

ICE Candidates

Controlling vs Controlled

Connection States

Adding STUN/TURN Servers

Continual Gathering

Next Steps

Agent Configuration

Candidate Types

NAT Traversal

Examples

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Overview

​Complete Example

​Full Working Example

​Key Concepts Explained

​ICE Candidates

​Controlling vs Controlled

​Connection States

​Adding STUN/TURN Servers

​Continual Gathering

​Next Steps

Agent Configuration

Candidate Types

NAT Traversal

Examples

Build docs developers (and LLMs) love

Overview

Complete Example

Full Working Example

Key Concepts Explained

ICE Candidates

Controlling vs Controlled

Connection States

Adding STUN/TURN Servers

Continual Gathering

Next Steps