Skip to main content

​
Go installation

TLS Client is primarily a Go library. Install it using Go modules: 
go get github.com/bogdanfinn/tls-client

​
Requirements

  • Go version: 1.24.1 or higher
  • Operating systems: Linux, macOS, Windows
  • Architectures: amd64, arm64

​
Dependencies

TLS Client automatically installs these dependencies:
  • github.com/bogdanfinn/fhttp - Fork of Go’s net/http with TLS fingerprinting support
  • github.com/bogdanfinn/utls - TLS library for client fingerprinting
  • github.com/bogdanfinn/quic-go-utls - QUIC implementation for HTTP/3 support
  • github.com/bogdanfinn/websocket - WebSocket support with TLS fingerprinting

​
Verify installation

Create a simple test to verify the installation:
main.go
package main

import (
    "fmt"
    "log"

    tls_client "github.com/bogdanfinn/tls-client"
    "github.com/bogdanfinn/tls-client/profiles"
)

func main() {
    options := []tls_client.HttpClientOption{
        tls_client.WithTimeoutSeconds(30),
        tls_client.WithClientProfile(profiles.Chrome_144),
    }

    client, err := tls_client.NewHttpClient(tls_client.NewNoopLogger(), options...)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Get("https://tls.peet.ws/api/all")
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    fmt.Printf("✓ TLS Client installed successfully! Status: %d\n", resp.StatusCode)
}
Run it: 
go run main.go

​
Language bindings

TLS Client provides FFI (Foreign Function Interface) bindings for multiple languages through a shared library.
The language bindings use a compiled shared library (.dll, .so, or .dylib) that wraps the Go code. You’ll need to download or compile the appropriate library for your platform.

​
Building the shared library

To build the shared library from source: 
cd cffi_dist
./build.sh
This creates platform-specific libraries in the dist/ directory:
  • Linux: tls-client-linux-amd64-<version>.so
  • macOS: tls-client-darwin-amd64-<version>.dylib
  • Windows: tls-client-windows-64-<version>.dll

​
Node.js installation

1

Install dependencies

Install the FFI library for Node.js:
npm install ffi-napi
2

Download the shared library

Download the appropriate shared library for your platform and place it in your project directory.
3

Create the client

Create a file client.js:
client.js
const ffi = require('ffi-napi');

// Load the TLS Client shared library
const tlsClient = ffi.Library('./tls-client-darwin-amd64-1.7.2.dylib', {
    'request': ['string', ['string']],
    'getCookiesFromSession': ['string', ['string']],
    'addCookiesToSession': ['string', ['string']],
    'freeMemory': ['void', ['string']],
    'destroyAll': ['string', []],
    'destroySession': ['string', ['string']]
});

// Configure request
const requestPayload = {
    tlsClientIdentifier: 'chrome_144',
    followRedirects: true,
    insecureSkipVerify: false,
    withoutCookieJar: false,
    timeoutSeconds: 30,
    sessionId: 'my-session-id',
    headers: {
        'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9',
        'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
        'accept-encoding': 'gzip, deflate, br',
        'accept-language': 'en-US,en;q=0.9'
    },
    headerOrder: [
        'accept',
        'user-agent',
        'accept-encoding',
        'accept-language'
    ],
    requestUrl: 'https://tls.peet.ws/api/all',
    requestMethod: 'GET',
    requestBody: '',
    requestCookies: []
};

// Make request
const response = tlsClient.request(JSON.stringify(requestPayload));
const result = JSON.parse(response);

console.log('Status:', result.status);
console.log('Body:', result.body);

// Free memory
tlsClient.freeMemory(response);
4

Run your code

node client.js
Make sure to update the library path to match your platform (.dylib for macOS, .so for Linux, .dll for Windows).

​
Python installation

1

Download the shared library

Download the appropriate shared library for your platform and place it in your project directory.
2

Create the client

Create a file client.py:
client.py
import ctypes
import json

# Load the TLS Client shared library
library = ctypes.cdll.LoadLibrary('./tls-client-darwin-amd64-1.7.2.dylib')

# Configure function signatures
request = library.request
request.argtypes = [ctypes.c_char_p]
request.restype = ctypes.c_char_p

getCookiesFromSession = library.getCookiesFromSession
getCookiesFromSession.argtypes = [ctypes.c_char_p]
getCookiesFromSession.restype = ctypes.c_char_p

addCookiesToSession = library.addCookiesToSession
addCookiesToSession.argtypes = [ctypes.c_char_p]
addCookiesToSession.restype = ctypes.c_char_p

freeMemory = library.freeMemory
freeMemory.argtypes = [ctypes.c_char_p]

destroySession = library.destroySession
destroySession.argtypes = [ctypes.c_char_p]
destroySession.restype = ctypes.c_char_p

# Configure request
request_payload = {
    'tlsClientIdentifier': 'chrome_144',
    'followRedirects': True,
    'insecureSkipVerify': False,
    'withoutCookieJar': False,
    'timeoutSeconds': 30,
    'sessionId': 'my-session-id',
    'headers': {
        'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9',
        'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
        'accept-encoding': 'gzip, deflate, br',
        'accept-language': 'en-US,en;q=0.9'
    },
    'headerOrder': [
        'accept',
        'user-agent',
        'accept-encoding',
        'accept-language'
    ],
    'requestUrl': 'https://tls.peet.ws/api/all',
    'requestMethod': 'GET',
    'requestBody': '',
    'requestCookies': []
}

# Make request
request_payload_json = json.dumps(request_payload).encode('utf-8')
response = request(request_payload_json)
result = json.loads(response.decode('utf-8'))

print(f"Status: {result['status']}")
print(f"Body: {result['body']}")

# Free memory
freeMemory(response)
3

Run your code

python client.py

​
C# installation

1

Install Newtonsoft.Json

Install the JSON library:
dotnet add package Newtonsoft.Json
2

Download the shared library

Download the Windows DLL and place it in your project directory.
3

Create the client

Create a file Client.cs:
Client.cs
using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using Newtonsoft.Json;

class RequestResult
{
    public string Id { get; set; }
    public string Body { get; set; }
    public object Cookies { get; set; }
    public Dictionary<string, List<string>> Headers { get; set; }
    public int Status { get; set; }
    public string Target { get; set; }
    public string UsedProtocol { get; set; }
}

class RequestPayload
{
    public string TlsClientIdentifier { get; set; } = "chrome_144";
    public bool FollowRedirects { get; set; } = true;
    public bool InsecureSkipVerify { get; set; } = false;
    public bool WithoutCookieJar { get; set; } = false;
    public int TimeoutSeconds { get; set; } = 30;
    public string SessionId { get; set; } = "my-session-id";
    public Dictionary<string, string> Headers { get; set; } = new Dictionary<string, string>();
    public List<string> HeaderOrder { get; set; }
    public string RequestUrl { get; set; }
    public string RequestMethod { get; set; }
    public string RequestBody { get; set; }
}

class TLSClient
{
    [DllImport("tls-client-windows-64-1.7.2.dll", CallingConvention = CallingConvention.Cdecl)]
    public static extern IntPtr request(byte[] requestPayload, string sessionID);

    [DllImport("tls-client-windows-64-1.7.2.dll", CallingConvention = CallingConvention.Cdecl)]
    public static extern IntPtr freeMemory(string memory);

    static void Main(string[] args)
    {
        var payload = new RequestPayload
        {
            Headers = new Dictionary<string, string>
            {
                { "accept", "text/html,application/xhtml+xml,application/xml;q=0.9" },
                { "user-agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" },
                { "accept-encoding", "gzip, deflate, br" },
                { "accept-language", "en-US,en;q=0.9" }
            },
            HeaderOrder = new List<string> { "accept", "user-agent", "accept-encoding", "accept-language" },
            RequestUrl = "https://tls.peet.ws/api/all",
            RequestMethod = "GET",
            RequestBody = ""
        };

        string payloadJson = JsonConvert.SerializeObject(payload);
        byte[] payloadBytes = System.Text.Encoding.UTF8.GetBytes(payloadJson);

        IntPtr responsePtr = request(payloadBytes, payload.SessionId);
        string responseJson = Marshal.PtrToStringAnsi(responsePtr);
        
        var result = JsonConvert.DeserializeObject<RequestResult>(responseJson);
        
        Console.WriteLine($"Status: {result.Status}");
        Console.WriteLine($"Body: {result.Body}");

        freeMemory(responseJson);
    }
}
4

Run your code

dotnet run

​
Platform-specific notes

​
Linux

On Linux, you may need to install additional dependencies: 
sudo apt-get update
sudo apt-get install -y build-essential

​
macOS

On macOS, you may need to allow the dylib in System Preferences:
  1. Try to run your application
  2. Go to System Preferences → Security & Privacy
  3. Click Allow Anyway for the blocked library
  4. Run your application again

​
Windows

On Windows, ensure you have:
  • Visual C++ Redistributable installed
  • The DLL in the same directory as your executable or in your system PATH

​
Troubleshooting

Make sure the shared library path is correct and matches your platform:
  • macOS: .dylib
  • Linux: .so
  • Windows: .dll
Use an absolute path if relative paths don’t work:
library = ctypes.cdll.LoadLibrary('/absolute/path/to/tls-client.dylib')
Ensure the shared library architecture matches your runtime:
  • Use amd64 libraries for 64-bit systems
  • Use arm64 libraries for ARM-based systems (like Apple Silicon)
On Linux/macOS, make the library executable:
chmod +x tls-client-*.so
# or
chmod +x tls-client-*.dylib
If you see errors about Go version compatibility, ensure you’re using Go 1.24.1 or higher:
go version
Update Go if needed from golang.org/dl

​
Next steps

Quickstart

Make your first request with TLS Client.

Configuration

Learn about all available client options.

Browser profiles

Explore available browser profiles for TLS fingerprinting.

Examples

Browse complete examples for different use cases.

Build docs developers (and LLMs) love

Get started for freeTalk to us