### Start Cocoon Client (Optional)

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Launches the Cocoon client component, which can be used to interact with the system during testing within TDX VMs with fake TON.

```bash
# Terminal 3: Start client (optional)
./scripts/cocoon-launch --test --fake-ton scripts/client.conf
```

--------------------------------

### Run All Cocoon Components Locally

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Starts all Cocoon components locally, including auto-building if necessary. This is useful for fast iteration and debugging without a VM or TON.

```bash
# Start all components (auto-builds on first run)
./scripts/cocoon-launch --local-all

# In another terminal: run benchmarks
cd benchmark
./run-benchmark.sh -c 1 -n 10
./run-benchmark.sh -c 2 -n 10
```

--------------------------------

### Start Cocoon Proxy in TDX VM

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Launches the Cocoon proxy component within a TDX VM using fake TON blockchain simulation. This is part of the testing setup for secure component execution.

```bash
# Terminal 1: Start proxy (in TDX VM)
./scripts/cocoon-launch --test --fake-ton scripts/proxy.conf
```

--------------------------------

### Testing with Real TON

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Instructions for running Cocoon tests using actual TON, requiring a TON config file and optional smart contract setup.

```APIDOC
## Use Case 3: Test Images with Real TON

Without `--fake-ton`, real TON will be used. A TON config file (e.g., `spec/mainnet-full-ton-config.json`) is required and should be passed via `--ton-config <path>`.

For testing purposes, you may create your own root smart contract. Using `--test` options disables TDX hash checks, making proxy addresses (e.g., `127.0.0.1:11001 127.0.0.1:11002`) the most crucial part for worker and client connections. The creation of proxy, worker, and client smart contracts is handled automatically.

**Note:** Testnet is not currently supported. Ensure you deposit TON into worker, client, and proxy accounts for testing.
```

--------------------------------

### Start Seal-Server for Production Deployment (Bash)

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

Starts the seal-server, which is essential for production deployments. It provides secure key derivation for TDX guests using an SGX enclave. This server must be running before workers are initialized and requires the exact enclave.so file from the distribution.

```bash
# Start seal-server (keep it running)
./seal-server --enclave-path enclave.so
```

--------------------------------

### Configure and Launch COCOON Worker (Production)

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

Demonstrates the steps to configure and launch the COCOON worker in production mode. It involves copying an example configuration file, editing it, and then running the launch script. Requires the seal-server to be running.

```bash
cp worker.conf.example worker.conf
vim worker.conf  # Edit with your settings (see inline comments for details)

# Production mode (requires seal-server running)
./scripts/cocoon-launch worker.conf
```

--------------------------------

### Health Client Tool

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Guide to using the `health-client` tool for detailed health monitoring of guest VM services via vsock.

```APIDOC
### Health Client

The `health-client` tool queries guest VM service status and logs using vsock, offering deeper insights than HTTP stats.

**Basic Usage:**
```bash
# Using instance names (recommended)
./health-client --instance worker <command> [args]
./health-client -i worker:3 <command> [args] # Instance 3

# Using CID directly
./health-client --cid 6 <command> [args]
```

**Instance Types and CID Patterns:**
- `worker` (`w`): CIDs 6, 16, 26, ...
- `proxy` (`p`): CIDs 7, 17, 27, ...
- `client` (`c`): CIDs 4, 14, 24, ...

**Available Commands:**
- `status [service]`: Overall health and service status.
- `sys`: System metrics (CPU, memory, disk, network).
- `svc <service>`: Detailed service info with recent logs.
- `logs <service> [lines]`: Service logs (default 100 lines).
- `tdx`: TDX attestation status (image hash + RTMRs).
- `gpu`: GPU metrics (utilization, memory, temp, power).
- `all`: All metrics combined.

**Monitored Services:**
- `cocoon-worker-runner`
- `cocoon-proxy-runner`
- `cocoon-vllm`
- `nvidia-tdx`

**Common Examples:**
```bash
# Check overall worker health
./health-client --instance worker status

# View GPU metrics for worker instance 0
./health-client -i worker gpu

# View logs for cocoon-vllm service on worker instance 1 (last 200 lines)
./health-client -i worker:1 logs cocoon-vllm 200
```
```

--------------------------------

### Build Cocoon Binaries with cocoon-launch

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Uses the `cocoon-launch` script to automatically initialize CMake and build the project's binaries. This is a convenient way to build for quick iteration.

```bash
./scripts/cocoon-launch --build-dir <path> --just-build
```

--------------------------------

### Start Cocoon Worker in TDX VM with GPU

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Launches the Cocoon worker component within a TDX VM, enabling GPU usage for AI inference. Requires setting the Hugging Face token for model downloads.

```bash
# Terminal 2: Start worker (in TDX VM, with GPU)
export HF_TOKEN=hf_...  # For model download
./scripts/cocoon-launch --test --fake-ton --gpu 0000:01:00.0 scripts/worker.conf
```

--------------------------------

### Production Deployment

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Steps for deploying Cocoon in a production environment, including running the `seal-server` and understanding differences from test deployments.

```APIDOC
## Use Case 4: Production Deployment

Execute `./cocoon-launch` for production deployment. It is recommended to run this from a downloaded archive to avoid rebuilding components.

Additionally, you must run the `seal-server`:
```bash
./seal-server --enclave-path enclave.so
```

The `enclave.so` file must be identical to the one from the archive. This is essential for sealing the key within the TDX guest, allowing it to communicate with `seal-server` for machine-specific key generation. Without `seal-server`, `cocoon-init` will fail.

Key differences from test deployment include the inability to access the guest via SSH and the verification of hashes by parties.
```

--------------------------------

### Clone Cocoon Repository and Initialize Build

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Clones the Cocoon Git repository with submodules and prepares the build environment using CMake. The `cocoon-launch` script handles CMake initialization and building.

```bash
git clone --recursive https://github.com/cocoon/cocoon
cd cocoon
```

--------------------------------

### Start COCOON Seal Server

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

Starts the COCOON seal-server, which is essential for production environments. It requires the signed enclave binary. This command should be run in a separate terminal as it needs to remain active.

```bash
# In a separate terminal, run seal-server
./bin/seal-server --enclave-path ./bin/enclave.signed.so
```

--------------------------------

### Example COCOON Worker Configuration

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Provides an example of the `worker.conf` file for a COCOON worker node. It includes essential configurations such as the owner address, the worker's private key, TON configuration file path, and the root contract address.

```bash
# Example worker.conf with wallet configuration
cat > worker.conf <<EOF
[cocoon]
type = worker
owner_address = EQCabc123def456...  # Where earnings are sent
node_wallet_key = xyz789uvw012...   # Private key for worker's revenue wallet
ton_config = mainnet-config.json
root_contract_address = EQCxyz789...
EOF
```

--------------------------------

### Build Test Image for Cocoon

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Builds a complete Debian-based TDX image required for testing Cocoon components within TDX VMs. This is a one-time, resource-intensive operation.

```bash
# Build image (one-time, takes ~10-30 minutes)
./scripts/build-image test
# Outputs to images/test/
```

--------------------------------

### Launch COCOON Worker in Test Modes

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

Provides examples for launching the COCOON worker in different test modes. The first option includes a debug shell and uses real TON. The second option uses a debug shell with fake TON.

```bash
# Test mode (with debug shell, real TON)
./scripts/cocoon-launch --test worker.conf

# Test mode (with debug shell, fake TON)
./scripts/cocoon-launch --test --fake-ton worker.conf
```

--------------------------------

### Setup GPU for TDX Passthrough (Bash)

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/gpu.md

This script facilitates the setup of a GPU for direct access within a TDX guest VM using VFIO. It enables confidential computing mode, detaches the GPU from the host driver, binds it to the vfio-pci driver, and configures udev rules. Requires root privileges for setup and restore operations.

```bash
# List available GPUs
./scripts/setup-gpu-vfio

# Setup GPU with PCI address 0000:01:00.0 for TDX passthrough
sudo ./scripts/setup-gpu-vfio --setup 0000:01:00.0

# Restore GPU to normal usage
sudo ./scripts/setup-gpu-vfio --restore 0000:01:00.0
```

--------------------------------

### Find SGX SDK Path (CMake)

Source: https://github.com/telegrammessenger/cocoon/blob/main/tee/sgx-enclave/CMakeLists.txt

This CMake script snippet attempts to locate the Intel SGX SDK installation path. It checks predefined variables, environment variables, and common installation directories. If the SDK is not found, it issues a warning and skips SGX enclave-related builds. It also validates the presence of the 'sgx.h' header file.

```cmake
if(DEFINED SGX_DIR)
  set(SGX_PATH ${SGX_DIR})
elseif(DEFINED ENV{SGX_SDK})
  set(SGX_PATH $ENV{SGX_SDK})
elseif(EXISTS /opt/intel/sgxsdk)
  set(SGX_PATH /opt/intel/sgxsdk)
elseif(EXISTS /home/arseny30/tdx/sgxsdk)
  set(SGX_PATH /home/arseny30/tdx/sgxsdk)
else()
  message(WARNING "SGX SDK not found - skipping sgx-enclave")
  return()
endif()

if(NOT EXISTS ${SGX_PATH}/include/sgx.h)
  message(WARNING "Invalid SGX SDK at ${SGX_PATH}")
  return()
endif()

message(STATUS "Found SGX SDK at ${SGX_PATH}")

set(SGX_LIB ${SGX_PATH}/lib64)
set(SGX_SIGNER ${SGX_PATH}/bin/x64/sgx_sign)
set(SGX_EDGER ${SGX_PATH}/bin/x64/sgx_edger8r)
```

--------------------------------

### Launch Local COCOON Environment and Run Benchmarks

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

This section provides bash commands to set up and manage a local testing environment for the COCOON network. It includes starting all components locally, running performance benchmarks with varying concurrency and iterations, and executing custom inference tests. The commands cover launching the environment, navigating to the benchmark directory, and cleaning up by stopping all COCOON processes.

```bash
# Start all components locally (no VM, fake TON)
./scripts/cocoon-launch --local-all
# Starts:
# - Fake HTTP inference server (port 8000)
# - Local proxy (port 11000)
# - Local worker (port 12000)
# - Local client (port 10000)
# All components run as native processes with fake-TON

# In another terminal, run benchmarks
cd benchmark

# Single concurrent request, 10 iterations
./run-benchmark.sh -c 1 -n 10

# Two concurrent requests, 10 iterations
./run-benchmark.sh -c 2 -n 10

# Custom benchmark with real inference
cat > benchmark/test_inference.py <<EOF
import requests
import time

endpoint = "http://localhost:10000"
model = "Qwen/Qwen3-0.6B"

start = time.time()
response = requests.post(
    f"{endpoint}/v1/chat/completions",
    json={
        "model": model,
        "messages": [{"role": "user", "content": "Hello"}],
        "max_tokens": 50
    },
    timeout=30
)
elapsed = time.time() - start

result = response.json()
tokens = result["usage"]["completion_tokens"]
print(f"Response: {result['choices'][0]['message']['content']}")
print(f"Latency: {elapsed:.2f}s, Tokens: {tokens}, Tokens/s: {tokens/elapsed:.1f}")
EOF

python benchmark/test_inference.py

# Clean up
pkill -f cocoon-launch
```

--------------------------------

### COCOON Initialization Script

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/tdx-and-images.md

The `cocoon-init` script, run as the first service, initializes the system by mounting config, copying static files, calculating a config hash, extending RTMR[3], deriving a persistent key, marking initialization complete, generating a TLS certificate with TDX attestation, and starting application services.

```shell
#!/bin/bash

# 1. Mount config volume
# ... virtfs mount command ...

# 2. Copy static config
# ... cp command ...

# 3. Calculate config hash
# ... git hash-calculate command ...

# 4. Extend RTMR[3]
# ... RTMR extension command ...

# 5. Derive persistent key
# ... seal-client command ...

# 6. Mark initialization complete
# ... RTMR extension command ...

# 7. Generate TLS certificate
# ... gen-cert command ...

# 8. Start application services
# ... startup script execution ...

```

--------------------------------

### Build AI Model for Cocoon

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Builds an AI model, which includes downloading, creating a tar archive, and generating a dm-verity hash for validation. This is essential for using AI capabilities within Cocoon.

```bash
# Build model (downloads, creates tar + verity)
./scripts/build-model Qwen/Qwen3-0.6B

# Generates files: 
# - images/Qwen_Qwen3_0_6B.tar
# - images/Qwen_Qwen3_0_6B.verity
# - images/Qwen_Qwen3_0_6B.hash

# Output:
# <model_name>:<model_commit>:<verity_hash> <tar_path>
```

--------------------------------

### Prepare COCOON Worker Distribution Package

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Generates a distribution package for COCOON workers, including pre-built binaries, TDX images, configuration templates, and setup scripts.

```bash
# Generate worker distribution package
./scripts/prepare-worker-dist ../cocoon-worker-dist
# Creates distribution with:
# - Pre-built binaries (runners, seal-server, router)
# - TDX images
# - Configuration templates
# - Setup scripts
# Outputs to ../cocoon-worker-dist/
```

--------------------------------

### Manual CMake Build Configuration for Cocoon

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Manually configures the build process for Cocoon using CMake with specific build type and feature flags. This provides fine-grained control over the build.

```bash
mkdir build && cd buildcmake -GNinja \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DBUILD_SHARED_LIBS=OFF \
  -DTON_USE_JEMALLOC=ON \
  -DTON_USE_ABSEIL=OFF \
  -DTON_ONLY_TONLIB=ON \
  -DTON_USE_ROCKSDB=ON \
  .. 
cmake --build . -j$(nproc)
```

--------------------------------

### CMake Option for Installation

Source: https://github.com/telegrammessenger/cocoon/blob/main/tdport/CMakeLists.txt

Defines a build option to control whether the library should be installed. Defaults to ON, meaning installation is enabled unless explicitly turned off during the CMake configuration step.

```cmake
option(TDNET_ENABLE_INSTALL "Enable installation of the library." ON)
```

--------------------------------

### Install Static Library

Source: https://github.com/telegrammessenger/cocoon/blob/main/tdport/CMakeLists.txt

Configures the installation of the 'tdnet_ported' static library if the 'TDNET_ENABLE_INSTALL' option is enabled. It specifies the destination directories for the library and archive files based on CMAKE_INSTALL_LIBDIR.

```cmake
if (TDNET_ENABLE_INSTALL)
  install(TARGETS tdnet_ported EXPORT TdStaticTargets
    LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
  )
endif()
```

--------------------------------

### Query System Information with CID using health-client

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

This command queries the system information for a specific worker instance identified by its CID. It utilizes the health-client tool and requires the CID as an argument.

```bash
./health-client --cid 16 sys

```

--------------------------------

### CMake Version Check and Installation Option

Source: https://github.com/telegrammessenger/cocoon/blob/main/tee/CMakeLists.txt

Ensures the minimum required CMake version (3.10) is used and sets an option to enable or disable library installation. The FATAL_ERROR message halts the build if the CMake version is insufficient. The option defaults to ON, meaning installation is enabled by default.

```cmake
if ((CMAKE_MAJOR_VERSION LESS 3) OR (CMAKE_VERSION VERSION_LESS "3.10"))
  message(FATAL_ERROR "CMake >= 3.10 is required")
endif()

option(TDCOCOON_ENABLE_INSTALL "Enable installation of the library." ON)

if (NOT DEFINED CMAKE_INSTALL_LIBDIR)
  set(CMAKE_INSTALL_LIBDIR "lib")
endif()
```

--------------------------------

### Basic CMake Project Setup

Source: https://github.com/telegrammessenger/cocoon/blob/main/CMakeLists.txt

Initializes the CMake project, setting the minimum required version and project name with version. It also configures position-independent code, which is essential for shared libraries.

```cmake
cmake_minimum_required(VERSION 3.16 FATAL_ERROR)

project(COCOON VERSION 0.5 LANGUAGES C CXX)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
```

--------------------------------

### Launch COCOON Worker with Overridden Options

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

Shows how to launch the COCOON worker while overriding configuration options directly via command-line arguments. This allows for dynamic adjustments to instance, worker coefficient, and model.

```bash
./scripts/cocoon-launch --instance 1 --worker-coefficient 2000 --model Qwen/Qwen3-0.6B worker.conf
```

--------------------------------

### Download and Extract COCOON Worker

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

This snippet shows how to download the latest COCOON worker distribution using wget and extract it using tar. It then navigates into the extracted directory.

```bash
wget https://ci.cocoon.org/cocoon-worker-release-latest.tar.xz 
tar xzf cocoon-worker-release-latest.tar.xz 
cd cocoon-worker-release-latest
```

--------------------------------

### Query GPU Information with CID using health-client

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

This command queries the GPU information for a specific worker instance identified by its CID. It utilizes the health-client tool and requires the CID as an argument.

```bash
./health-client --cid 16 gpu

```

--------------------------------

### HTTP Stats Endpoints

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Details on accessing and interpreting HTTP statistics provided by Cocoon instances for monitoring.

```APIDOC
### HTTP Stats

HTTP statistics are available on specific ports for client, proxy, and worker instances. For additional instances, multiply the instance number by 10 and add it to the base port.

- **Client:** Port 10000
- **Proxy:** Port 11000
- **Worker:** Port 12000

**Available Endpoints:**
- `/stats`: Provides human-readable statistics.
- `/jsonstats`: Provides statistics in JSON format.
- `/perf`: Shows current performance statistics.

**Example Usage:**
```bash
# Worker instance 0
curl http://localhost:12000/stats

# Worker instance 1
curl http://localhost:12010/jsonstats
```
```

--------------------------------

### Generate RA-TLS Router Configuration (Bash)

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Generates an example JSON configuration file for the RA-TLS router. This file can be customized and then used to configure the router's behavior, including policies and proxy settings.

```bash
# Generate example config
./router --generate-config > router.json
```

--------------------------------

### Launch Multiple COCOON Workers

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

Illustrates how to run multiple COCOON workers concurrently on the same machine, typically one per GPU. Each worker is assigned a unique instance number and specified GPU.

```bash
# Worker 1 on GPU 0
./scripts/cocoon-launch --instance 0 --gpu 0000:01:00.0 worker.conf &

# Worker 2 on GPU 1
./scripts/cocoon-launch --instance 1 --gpu 0000:41:00.0 worker.conf &
```

--------------------------------

### Use JSON Configuration File for RA-TLS Router (Bash)

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Loads and applies router configurations from a JSON file. This method allows for declarative management of proxy settings, policies, and certificates, simplifying complex setups.

```bash
cat > router.json <<EOF
{
  "cert": "worker_cert.pem",
  "key": "worker_key.pem",
  "policies": {
    "strict": {
      "type": "tdx",
      "allowed_image_hashes": ["abc123..."]
    }
  },
  "proxies": [
    {"type": "socks5", "listen": "1080", "policy": "strict"},
    {"type": "reverse", "listen": "9000", "forward": "localhost:8000", "policy": "strict"}
  ]
}
EOF
./router --config router.json
```

--------------------------------

### Monitor Worker Health and System Metrics (Bash)

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

Utilizes the health-client tool to monitor worker status, system, GPU metrics, and service logs. Provides commands to check various aspects of worker and system performance. Use '--help' for full usage details.

```bash
# Check worker health
./health-client --instance worker status

# View system metrics
./health-client -i worker sys

# View GPU metrics
./health-client -i worker gpu

# View service logs
./health-client -i worker logs cocoon-vllm 100

# Get all metrics
./health-client -i worker all
```

--------------------------------

### Create Cocoon Static Library

Source: https://github.com/telegrammessenger/cocoon/blob/main/tee/CMakeLists.txt

Defines the main Cocoon library as a static library named 'cocoon'. It links against various other libraries including OpenSSL, dl, zlib, tdnet_ported, tdutils, and conditionally the attestation libraries if available. It also sets up include directories for both build and install configurations.

```cmake
add_library(cocoon STATIC ${COCOON_SOURCE})
target_link_libraries(cocoon PUBLIC tdutils PRIVATE ${OPENSSL_CRYPTO_LIBRARY} ${CMAKE_DL_LIBS} ${ZLIB_LIBRARIES} tdnet_ported ${ATTESTATION_LIBRARIES})
target_include_directories(cocoon SYSTEM PRIVATE $<BUILD_INTERFACE:${OPENSSL_INCLUDE_DIR}>)
target_include_directories(cocoon PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>/..)
target_include_directories(cocoon PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>)
target_include_directories(cocoon PUBLIC $<BUILD_INTERFACE:${TL_TD_AUTO_INCLUDE_DIR}>)
```

--------------------------------

### GPU PCI Address Identification

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

This command is used to identify the PCI address of NVIDIA GPUs installed on the system, which is required for the `gpu` configuration option in `worker.conf`.

```bash
lspci | grep -i nvidia
```

--------------------------------

### Set Default Installation Directory

Source: https://github.com/telegrammessenger/cocoon/blob/main/tdport/CMakeLists.txt

Sets the default installation directory for libraries if it's not already defined. This ensures a consistent installation path across different build configurations.

```cmake
if (NOT DEFINED CMAKE_INSTALL_LIBDIR)
  set(CMAKE_INSTALL_LIBDIR "lib")
endif()
```

--------------------------------

### Build Production TDX Image (Bash)

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Builds a production-ready TDX VM image. This process involves compiling necessary components and outputs a set of files including firmware, kernel, initrd, command line, and a hash of the image components. The build can take a significant amount of time.

```bash
# Build production image (takes 10-30 minutes, ~2GB output)
./scripts/build-image prod
```

--------------------------------

### Worker Deployment and Configuration

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Instructions and configuration details for deploying and launching a COCOON worker to serve AI models.

```APIDOC
## Worker Deployment and Configuration

Configure and deploy a COCOON worker to serve AI models and earn TON cryptocurrency.

### Download and Extract Worker

```bash
# Download and extract worker distribution
wget https://ci.cocoon.org/cocoon-worker-release-latest.tar.xz
tar xzf cocoon-worker-release-latest.tar.xz
cd cocoon-worker-release-latest
```

### Start Seal Server

```bash
# Start seal-server (required for production, provides secure key derivation)
./bin/seal-server --enclave-path ./bin/enclave.signed.so &
```

### Worker Configuration File (`worker.conf`)

Create a configuration file for the worker.

```bash
cat > worker.conf <<EOF
[cocoon]
type = worker
model = Qwen/Qwen3-0.6B
owner_address = EQAbc123...xyz
gpu = 0000:01:00.0
node_wallet_key = base64_encoded_private_key
hf_token = hf_your_token_here
ton_config = mainnet-config.json
root_contract_address = EQCxyz789...abc
instance = 0
worker_coefficient = 1000
persistent = persistent-worker-0.img
EOF
```

**Configuration Fields:**
- **`type`**: (string) Type of the node, should be `worker`.
- **`model`**: (string) The AI model to serve (e.g., `Qwen/Qwen3-0.6B`).
- **`owner_address`**: (string) TON address of the worker owner.
- **`gpu`**: (string) PCI address of the GPU to use.
- **`node_wallet_key`**: (string) Base64 encoded private key for the TON wallet.
- **`hf_token`**: (string) Hugging Face API token.
- **`ton_config`**: (string) Path to TON configuration file.
- **`root_contract_address`**: (string) Address of the root smart contract.
- **`instance`**: (integer) Worker instance identifier.
- **`worker_coefficient`**: (integer) Coefficient for worker pricing.
- **`persistent`**: (string) Path to the persistent worker image.

### Launch Worker

```bash
# Launch worker in production mode
./scripts/cocoon-launch worker.conf

# Launch worker in test mode with debug shell
./scripts/cocoon-launch --test --fake-ton worker.conf

# Override configuration via command line
./scripts/cocoon-launch --instance 1 --worker-coefficient 2000 --model Qwen/Qwen3-0.6B worker.conf

# Run multiple workers on different GPUs
./scripts/cocoon-launch --instance 0 --gpu 0000:01:00.0 worker.conf &
./scripts/cocoon-launch --instance 1 --gpu 0000:41:00.0 worker.conf &
```
```

--------------------------------

### Configure nlohmann-json Build Options

Source: https://github.com/telegrammessenger/cocoon/blob/main/CMakeLists.txt

Sets internal CMake variables for the 'nlohmann-json' library to disable building tests and installation. This is often done when the library is included as a subdirectory and not meant to be built or installed independently.

```cmake
set(JSON_BuildTests OFF CACHE INTERNAL "")
set(JSON_Install OFF CACHE INTERNAL "")
add_subdirectory(third-party/nlohmann-json)
```

--------------------------------

### Prepare Spec Script - Bash Shell Script

Source: https://github.com/telegrammessenger/cocoon/blob/main/reprodebian/cocoon-init/README.md

The main bash script for preparing a specification directory. It copies files from a source directory to an output directory, calculates a SHA-256 hash of the content, and creates metadata files. It respects .gitignore rules, excludes specific directories, and normalizes file permissions. Requirements include bash, git, find, tar, and awk.

```bash
#!/bin/bash

# Script to create a deterministic copy of a source directory with SHA-256 content hash.

# Usage: ./prepare-spec.sh SRC_DIR SPEC_OUT

set -e

SRC_DIR="$1"
SPEC_OUT="$2"

if [ -z "$SRC_DIR" ] || [ -z "$SPEC_OUT" ]; then
    echo "Usage: $0 SRC_DIR SPEC_OUT"
    exit 1
fi

# Ensure source directory exists
if [ ! -d "$SRC_DIR" ]; then
    echo "Error: Source directory '$SRC_DIR' not found."
    exit 1
fi

# Clean and create output directory
rm -rf "$SPEC_OUT"
mkdir -p "$SPEC_OUT/runtime"

# --- Copy files respecting .gitignore and excluding specific patterns ---
# Use git archive to get files respecting .gitignore. This approach is efficient and handles exclusions well.
# We need to temporarily change directory to SRC_DIR for git archive to work correctly.

pushd "$SRC_DIR" > /dev/null

# Generate a list of files to include, excluding .git, runtime/, and potential spec metadata files
# git ls-files --cached --exclude-standard can be used, but git archive is more direct for tarring.

# Create a temporary tarball of the source directory, respecting .gitignore
temp_tar="$(mktemp)"
git archive --format=tar --output="$temp_tar" HEAD

# Extract the tarball to a staging directory within the SPEC_OUT directory
# We'll then filter out unwanted files and process the rest.
staging_dir="${SPEC_OUT}/staging_area"
mkdir -p "$staging_dir"
tar -xf "$temp_tar" -C "$staging_dir"

# --- Process extracted files --- 

# Define files/dirs to exclude from hashing and copying to the final spec structure
EXCLUDE_PATTERNS=(
    ".git"
    "runtime/"
    "spec.tree"
    "spec.meta"
    "*.spec.tree"
    "*.spec.meta"
)

# Use find to process files, normalize permissions, and copy them
find "$staging_dir" -type f -print0 | while IFS= read -r -d $'\0' file;
do
    relative_path="${file#$staging_dir/}"
    skip=0

    # Check against exclude patterns
    for pattern in "${EXCLUDE_PATTERNS[@]}"; do
        if [[ "$relative_path" == $pattern ]]; then
            skip=1
            break
        fi
    done

    if [ "$skip" -eq 0 ]; then
        # Normalize permissions (644 for files)
        chmod 644 "$file"
        # Copy to the final destination
        cp "$file" "$SPEC_OUT/"
    fi
done

# Process directories: normalize permissions for directories (755)
find "$staging_dir" -type d -print0 | while IFS= read -r -d $'\0' dir;
do
    relative_path="${dir#$staging_dir/}"
    skip=0

    # Check against exclude patterns for directories
    for pattern in "${EXCLUDE_PATTERNS[@]}"; do
        if [[ "$relative_path" == $pattern ]]; then
            skip=1
            break
        fi
    done

    if [ "$skip" -eq 0 ]; then
        # Normalize permissions (755 for directories)
        chmod 755 "$dir"
        # Ensure directory exists in the output, if it was not created by copying files into it
        mkdir -p "$SPEC_OUT/$relative_path"
    fi
done

# --- Copy runtime/ directory as-is --- 
if [ -d "$SRC_DIR/runtime" ]; then
    cp -R "$SRC_DIR/runtime" "$SPEC_OUT/"
    # Ensure runtime directory itself has correct permissions if it wasn't handled by find above
    chmod 755 "$SPEC_OUT/runtime"
fi

# Clean up staging area and temp tarball
rm -rf "$staging_dir"
rm "$temp_tar"

popd > /dev/null

# --- Calculate SHA-256 hash of the copied content --- 
# We need to ensure the order of files is deterministic. Sorting helps.
# We will tar the content of SPEC_OUT (excluding runtime/ and metadata files) and hash the tarball.

content_tar="$(mktemp)"
find "$SPEC_OUT" -maxdepth 1 -type f -not -name 'spec.tree' -not -name 'spec.meta' -print0 | sort -z |
xargs -0 tar -cf "$content_tar"

# Calculate SHA-256 hash
spec_hash=$(sha256sum "$content_tar" | awk '{print $1}')

# Create spec.tree file
echo "$spec_hash" > "$SPEC_OUT/spec.tree"

# --- Create spec.meta file --- 
cat << EOF > "$SPEC_OUT/spec.meta"
{
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "source_dir": "$(realpath "$SRC_DIR")",
  "hash_algorithm": "sha256",
  "content_hash": "$spec_hash"
}
EOF

# Clean up temporary tarball
rm "$content_tar"

echo "Spec prepared successfully in '$SPEC_OUT' with hash: $spec_hash"

exit 0

```

--------------------------------

### Prepare Cross-Compiling Target

Source: https://github.com/telegrammessenger/cocoon/blob/main/CMakeLists.txt

Creates a custom target 'prepare_cross_compiling_cocoon' that depends on other targets required for cross-compilation setup. This target is only added if cross-compiling is not detected.

```cmake
if (NOT CMAKE_CROSSCOMPILING)
  if (TDUTILS_MIME_TYPE)
    set(TDMIME_AUTO tdmime_auto) 
  endif()
  add_custom_target(prepare_cross_compiling_cocoon DEPENDS tl_generate_common cocoon_tl_generate_common ${TDMIME_AUTO})
endif()
```

--------------------------------

### Deploy and Configure COCOON Worker (Bash)

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Steps to download, extract, and configure a COCOON worker for AI inference. This includes setting up the seal-server, defining worker configurations in `worker.conf`, and launching the worker in production or test modes. It covers overriding configurations and running multiple workers.

```bash
# Download and extract worker distribution
wget https://ci.cocoon.org/cocoon-worker-release-latest.tar.xz
tar xzf cocoon-worker-release-latest.tar.xz
cd cocoon-worker-release-latest

# Start seal-server (required for production, provides secure key derivation)
./bin/seal-server --enclave-path ./bin/enclave.signed.so &

# Create worker configuration
cat > worker.conf <<EOF
[cocoon]
type = worker
model = Qwen/Qwen3-0.6B
owner_address = EQAbc123...xyz
gpu = 0000:01:00.0
node_wallet_key = base64_encoded_private_key
hf_token = hf_your_token_here
ton_config = mainnet-config.json
root_contract_address = EQCxyz789...abc
instance = 0
worker_coefficient = 1000
persistent = persistent-worker-0.img
EOF

# Launch worker in production mode
./scripts/cocoon-launch worker.conf

# Launch worker in test mode with debug shell
./scripts/cocoon-launch --test --fake-ton worker.conf

# Override configuration via command line
./scripts/cocoon-launch --instance 1 --worker-coefficient 2000 --model Qwen/Qwen3-0.6B worker.conf

# Run multiple workers on different GPUs
./scripts/cocoon-launch --instance 0 --gpu 0000:01:00.0 worker.conf &
./scripts/cocoon-launch --instance 1 --gpu 0000:41:00.0 worker.conf &

```

--------------------------------

### Verify TDX Support on Host

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Checks if the Linux kernel supports Intel TDX by searching kernel messages. This is a crucial step for enabling confidential computing features.

```bash
# Check TDX support in kernel messages
dmesg | grep -i tdx

# Should see messages about TDX initialization
```

--------------------------------

### Verify Cocoon Worker Stats

Source: https://github.com/telegrammessenger/cocoon/blob/main/docs/deployment.md

Retrieves statistical information about the running Cocoon worker using HTTP requests. This helps in verifying the worker's operational status and performance.

```bash
# Check worker stats (JSON)
curl http://localhost:12000/jsonstats

# Check worker is running
curl http://localhost:12000/stats
```

--------------------------------

### Sign SGX Enclave (CMake)

Source: https://github.com/telegrammessenger/cocoon/blob/main/tee/sgx-enclave/CMakeLists.txt

This CMake snippet configures the signing process for the SGX enclave. It uses the 'sgx_sign' tool, a private key, and a configuration file to sign the compiled enclave binary. A custom command generates the signed enclave file ('enclave.signed.so'), and a custom target 'enclave-sign' is created to depend on this signed output.

```cmake
add_custom_command(
  OUTPUT enclave.signed.so
  COMMAND faketime -f ${SGX_ENCLAVE_EPOCH} ${SGX_SIGNER} sign
          -key ${CMAKE_CURRENT_SOURCE_DIR}/Enclave_private.pem
          -config ${CMAKE_CURRENT_SOURCE_DIR}/Enclave.config.xml
          -enclave $<TARGET_FILE:enclave> -out enclave.signed.so
  DEPENDS enclave Enclave_private.pem Enclave.config.xml
  COMMENT "Signing enclave"
)

add_custom_target(enclave-sign ALL DEPENDS enclave.signed.so)
```

--------------------------------

### Build COCOON Images

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Scripts to build test and model images for the COCOON project. The test image includes SSH access and debug tools. The model image is built with dm-verity verification and downloads models from Hugging Face, outputting tar archives and hash files.

```bash
# Build test image (includes SSH access and debug tools)
./scripts/build-image test
# Outputs to images/test/
```

```bash
# Build model image with dm-verity verification
./scripts/build-model Qwen/Qwen3-0.6B
# Downloads model from Hugging Face
# Creates tar archive with dm-verity hashing
# Outputs:
# - images/Qwen_Qwen3_0_6B.tar
# - images/Qwen_Qwen3_0_6B.verity (dm-verity hash tree)
# - images/Qwen_Qwen3_0_6B.hash (root hash)
# Prints: Qwen/Qwen3-0.6B:abc123def456 /path/to/tar
#         (model_name:commit:verity_hash path)
```

--------------------------------

### Library Creation and Dependencies

Source: https://github.com/telegrammessenger/cocoon/blob/main/CMakeLists.txt

Creates a static library named 'git' from the post-configure file and sets public include directories. It also establishes a build dependency on a target named 'check_git'.

```cmake
# Create a library out of the compiled post-configure file.
add_library(git STATIC ${POST_CONFIGURE_FILE})
target_include_directories(git PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
add_dependencies(git check_git)
```

--------------------------------

### CMake Module Path Setup

Source: https://github.com/telegrammessenger/cocoon/blob/main/CMakeLists.txt

Adds the 'CMake' subdirectory of the current source directory to the CMake module path. This allows CMake to find custom modules located within the project's 'CMake' folder.

```cmake
message("Add cocoon")
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/CMake" ${CMAKE_MODULE_PATH})
```

--------------------------------

### Retrieve Available Models (Python)

Source: https://context7.com/telegrammessenger/cocoon/llms.txt

Fetches a list of available models from the API endpoint using a GET request. The response is a JSON object containing a list of model details.

```python
models_response = requests.get(f"{endpoint}/v1/models")
models = models_response.json()
```

--------------------------------

### Create Sync Time Utility Executable

Source: https://github.com/telegrammessenger/cocoon/blob/main/CMakeLists.txt

Defines the 'sync-time' executable, which is a utility for synchronizing time. It lists its source file and links it with the 'cocoon_common' library.

```cmake
# Sync time utility
add_executable(sync-time runners/utils/sync_time.cpp )
target_link_libraries(sync-time PRIVATE cocoon_common )
```

--------------------------------

### Build SGX Enclave Library (CMake)

Source: https://github.com/telegrammessenger/cocoon/blob/main/tee/sgx-enclave/CMakeLists.txt

This CMake configuration defines how to build the SGX enclave as a shared library. It specifies compilation options such as architecture (-m64), optimization level (-O2), and visibility control. It also sets up include directories and links against necessary SGX libraries and runtime components for trusted execution.

```cmake
add_library(enclave SHARED Enclave.cpp Enclave_t.c)
target_compile_options(enclave PRIVATE -m64 -O2 -DNDEBUG -DEDEBUG -nostdinc -nostdinc++ -fvisibility=hidden -fpie -fstack-protector-strong)
target_include_directories(enclave PRIVATE ${CMAKE_CURRENT_BINARY_DIR} ${SGX_PATH}/include ${SGX_PATH}/include/tlibc ${SGX_PATH}/include/libcxx)
target_link_libraries(enclave "-m64 -Wl,--no-undefined -nostdlib -nodefaultlibs -nostartfiles -L${SGX_LIB} 
  -Wl,--whole-archive -lsgx_trts -Wl,--no-whole-archive 
  -Wl,--start-group -lsgx_tstdc -lsgx_tcxx -lsgx_tkey_exchange -lsgx_tcrypto -lsgx_tservice -Wl,--end-group 
  -Wl,-Bstatic -Wl,-Bsymbolic -Wl,--no-undefined -Wl,-pie,-eenclave_entry -Wl,--export-dynamic 
  -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/Enclave.lds -Wl,--defsym,__ImageBase=0")
set_target_properties(enclave PROPERTIES 
  LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/Enclave.lds
  ENABLE_EXPORTS OFF
  LINK_WHAT_YOU_USE OFF)
```

--------------------------------

### Access Worker Statistics via HTTP (Bash)

Source: https://github.com/telegrammessenger/cocoon/blob/main/scripts/dist-worker/README.md

Retrieves worker statistics using cURL. Supports both human-readable ('/stats') and JSON-formatted ('/jsonstats') outputs, as well as performance metrics ('/perf'). Different ports are used for different worker instances.

```bash
# Worker instance 0
curl http://localhost:12000/stats
curl http://localhost:12000/jsonstats  # JSON format

# Worker instance 1
curl http://localhost:12010/stats
```