Table of Contents


We present here the general steps required to install and use the ThreeFold Grid Client.

The Grid Client is written using TypeScript to provide more convenience and type-checked code. It is used to deploy workloads like virtual machines, kubernetes clusters, quantum storage, and more.


To install the Grid Client, you will need the following on your machine:

  • Node.js ^18
  • npm 8.2.0 or higher
  • may need to install libtool (apt-get install libtool)

Note: nvm is the recommended way for installing node.

To use the Grid Client, you will need the following on the TFGrid:

  • A TFChain account
  • TFT in your wallet

If it is not the case, please visit the Get started section.


External Package

To install the external package, simply run the following command:

yarn add @threefold/grid_client

Note: For the qa, test and main networks, please use @2.1.1 version.

Local Usage

To use the Grid Client locally, clone the repository then install the Grid Client:

  • Clone the repository
    • git clone
  • Install the Grid Client
    • With yarn
      • yarn install
    • With npm
      • npm install

Note: In the directory grid_client/scripts, we provided a set of scripts to test the Grid Client.

Getting Started

You will need to set the client configuration either by setting the json file manually (scripts/config.json) or by using the provided script (scripts/client_loader.ts).

Client Configuration

Make sure to set the client configuration properly before using the Grid Client.

  • network: The network environment (dev, qa, test or main).

  • mnemonic: The 12 words mnemonics for your account.

    • Learn how to create one here.
  • storeSecret: This is any word that will be used for encrypting/decrypting the keys on ThreeFold key-value store.

  • ssh_key: The public SSH key set on your machine.

Note: Only networks can't be isolated, all projects can see the same network.

Generate the Documentation

The easiest way to test the installation is to run the following command with either yarn or npm to generate the Grid Client documentation:

  • With yarn
    • yarn run serve-docs
  • With npm
    • npm run serve-docs

Note: You can also use the command yarn run to see all available options.

How to Run the Scripts

You can explore the Grid Client by testing the different scripts proposed in grid_client/scripts.

  • Update your customized deployments specs if needed
  • Run using ts-node
    • With yarn
      • yarn run ts-node --project tsconfig-node.json scripts/zdb.ts
    • With npx
      • npx ts-node --project tsconfig-node.json scripts/zdb.ts

Reference API

While this is still a work in progress, you can have a look here.

Last change: 2024-02-28