Skip to content

🤖 ThirdWeb Engine Configuration

Set up ThirdWeb Engine for automated transaction execution - the self-hosted automation service that handles automated bidding for your Stylus contracts.

🎯 What is ThirdWeb Engine?

ThirdWeb Engine is a self-hosted automation service that:

  • 🤖 Executes Transactions: Places backend triggered automated bids based on configured rules
  • 🔒 Secure Execution: Handles private keys securely in isolated containers
  • 📊 Monitoring: Provides transaction history and status tracking
  • 🌐 Multi-Network: Supports multiple blockchain networks simultaneously

Why Self-Hosted?

Self-hosting Engine v2 gives you full control over your automation infrastructure while maintaining security and reliability.

🔧 Prerequisites

Before configuring ThirdWeb Engine, ensure you have:

  • Docker & Docker Compose installed and running
  • ThirdWeb Account (free registration at thirdweb.com)
  • Deployed CMA Contracts from the previous step
  • Access to a deployment wallet for configuration

📋 Setup Overview

The configuration process involves:

  1. 🏗️ Create ThirdWeb Project - Set up your workspace
  2. 🔑 Configure Environment - Set up local environment variables
  3. 🐳 Deploy Engine Services - Start the self-hosted automation
  4. 🔗 Link to ThirdWeb Dashboard - Connect local instance to web interface
  5. 💰 Configure Wallets - Set up backend wallet for transactions
  6. 🌐 Add Custom Networks - Configure your Arbitrum networks

🏗️ Step 1: Create ThirdWeb Project

1.1 Login to ThirdWeb

Visit thirdweb.com and log in using your wallet

1.2 Create New Project

Create a new project for your automation setup:

Create Project
Create Project Submit

Domain Configuration

For testing, you can allow all domains. For production, specify your backend domain and thirdweb domain for enhanced security.

1.3 Save Project Keys

Copy and save your project keys securely - you'll need them for configuration:

Create Project Keys

Key Security

The wallet you use to log in will become the project admin. Keep your keys secure and never share them publicly.

🔑 Step 2: Configure Environment

2.1 Copy Environment Files

Copy the example environment files:

cp src/docker/.env.engine.example src/docker/.env.engine
cp src/docker/.env.engine-db.example src/docker/.env.engine-db

2.2 Configure Engine Environment

Edit src/docker/.env.engine with your ThirdWeb configuration:

# Required: Complex password for database encryption
ENCRYPTION_PASSWORD=your_complex_encryption_password_here

# Required: Your ThirdWeb API secret key
THIRDWEB_API_SECRET_KEY=your_thirdweb_api_secret_key

# Required: Admin wallet address (use your ThirdWeb login wallet)
ADMIN_WALLET_ADDRESS=0xYourThirdWebLoginWalletAddress

# Required: Backend wallet address (can be same as admin for testing)
BACKEND_WALLET_ADDRESS=0xYourThirdWebLoginWalletAddress

# Optional: Keep defaults for local deployment
POSTGRES_CONNECTION_URL=postgresql://scm-engine-db-user:scm-engine-db-pwd@scm-engine-db:5432/scm_engine_db?sslmode=disable
REDIS_URL=redis://scm-engine-redis:6381?family=0
PORT=3005
HOST=::

2.3 Configure Database Environment

Edit src/docker/.env.engine-db (keep defaults for local deployment):

POSTGRES_CONNECTION_URL=postgresql://scm-engine-db-user:scm-engine-db-pwd@scm-engine-db:5432/scm_engine_db?sslmode=disable
REDIS_URL=redis://scm-engine-redis:6381?family=0
PORT=3005

🐳 Step 3: Deploy Engine Services

3.1 Start Engine Services

Use the automated script to start all Engine services:

npm run engine:start

Or manually start with Docker Compose:

docker compose -f src/docker/docker-compose.yaml up -d scm-engine-db scm-engine-redis scm-engine

3.2 Verify Services

Check that all services are running:

docker compose -f src/docker/docker-compose.yaml ps

You should see:

  • scm-engine-db - PostgreSQL database
  • scm-engine-redis - Redis cache
  • scm-engine - ThirdWeb Engine service

3.3 Service Management

Additional commands for managing Engine services:

# Pause services
npm run engine:pause

# Stop and remove services
npm run engine:delete

# View logs
docker compose -f src/docker/docker-compose.yaml logs -f scm-engine

4.1 Allow HTTP Requests

HTTP Access Required

To allow the ThirdWeb frontend to communicate with your local Engine instance, visit this URL in your browser:

http://localhost:3005/json

Accept the HTTP security warning and allow insecure navigation.

4.2 Access Project Transactions

Navigate to your project's transactions page:

https://thirdweb.com/team/<USERNAME>/<PROJECT_NAME>/transactions

4.3 View Dedicated Engine

Click on "View Dedicated Engine" to access Engine management:

Create Project View Dedicated

4.4 Import Local Engine

Click "Import Engine" to connect your local instance:

Create Project Import Engine

4.5 Configure Engine Settings

Configure your local Engine instance:

Create Project Config Engine

Local Access Only

Only you can manage this instance since it's running on localhost. For team access, deploy to cloud or create a tunnel.

4.6 Verify Instance

After importing, you should see your Engine instance in your list.

💰 Step 5: Configure Backend Wallet

5.1 Import Backend Wallet

For testing, you can import the admin wallet as the backend wallet:

Create Project Engine Success
Create Project BE Wallet Import

Production Security

For production, use a separate wallet for backend operations. Backend wallets only need balance - if compromised, you can replace them easily.

5.2 Verify Wallet Import

Confirm the wallet is successfully imported:

Create Project BE Wallet Success

🔑 Step 6: Create Access Token

6.1 Generate Access Token

Go to the Access Tokens section and create a new token:

Create Project Access Token

6.2 Save Token

Copy and save your access token securely:

Create Project Access Token Success

Token Security

Keep this token secure - it's required for backend communication with Engine.

🌐 Step 7: Add Custom Networks

7.1 Add Local Testnode

Use your access token to add your local Arbitrum testnode:

ACCESS_TOKEN=<PASTE_YOUR_ACCESS_TOKEN>

curl --location 'http://localhost:3005/configuration/chains' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer '$ACCESS_TOKEN \
--data '{
  "chainOverrides": [
    {
      "name": "Arbitrum Local",
      "chain": "ETH",
      "rpc": [
        "http://host.docker.internal:8547"
      ],
      "nativeCurrency": {
        "name": "Ether",
        "symbol": "ETH",
        "decimals": 18
      },
      "chainId": 412346,
      "slug": "arbitrum-local"
    }
  ]
}'

Docker Networking

We use host.docker.internal:8547 instead of localhost:8547 because Engine runs in Docker containers and needs to access the host machine's localhost.

7.2 Add Other Networks

You can add any custom network to Engine by using the same request we used for adding Arbitrum Local Testnode

✅ Configuration Complete

Congratulations! Your ThirdWeb Engine is now configured and ready to:

  • 🤖 Execute automated transactions for cache bidding
  • 📊 Monitor transaction status through the ThirdWeb dashboard
  • 🔒 Securely manage private keys in isolated containers
  • 🌐 Support multiple networks for different environments

🔧 Next Steps

With Engine configured, proceed to SCM UI Backend - Configure the backend API service