Using the Octez Packages (2026)

This is a refresh of my article from 2023 and subsequently my article from 2025.

Octez packages

A few of us Tezos folk worked on a set of Octez packages in Debian Linux and Red Hat Linux packaging formats. Octez is the reference implementation of the Tezos blockchain software. Nomadic Labs took over the packaging scripts and rewrote them. However, they have decided to stop producing packages as of v26. I use the packages regularly at home and at work. I also think they are the best way for users to install Octez. And I don’t have much to do in the evenings, so I thought I’d have a go at producing them again.

I’ve updated my original build scripts, added systemctl infrastructure and also tried to align the packages with the Nomadic Labs ones. There are a few subtle differences, so if you are migrating, you might find it easier to deinstall theirs and reinstall these ones. Tzinit (Tezos Foundation in disguise) is currently hosting the packages.

The packages

There are several packages:

• octez-client - the client for manipulating wallets and signing items
• octez-node - the Octez node
• octez-dal-node - the Octez DAL node
• octez-baker - the Octez baking daemons and VDF service
• octez-smart-rollup-node - the Octez smart rollup daemons
• octez-signer - the remote signer, to hold keys on a different machine from the baker or client
• octez-zcash-params - the ZCash parameters used by the node, put into a separate package because they don’t change.

Also there are two packages that I’m still working on. You are unlikely to need them:

• octez-evm-node - the EVM endpoint node for Etherlink
• octez-teztale-archiver - the Teztale archiver, used to feed the Teztale explorer with data from the node.

The packages with servers are set up to run under a dedicated user called tezos. The signer package uses a user and group called tzsigner.

Where to get the packages

APT repositories

If you are using Debian Linux 13 (Trixie) or Ubuntu Linux 24.04 (Noble), the best way to get them is via the APT repository. You can add the catalogue to your system as follows. Make sure that gpg and curl are installed:

$ sudo apt install -y gpg curl

Then accept the public key of the APT repository:

$ curl -s "https://apt.tzinit.org/keys/tzinit.asc" | \
    sudo gpg --dearmor -o /etc/apt/keyrings/tzinit.gpg

You should double check that this is the real key of course. Its fingerprint is 181E6294A0770AE9AF0173B21F688E1201D819B4 and it has been signed with my PGP key F38491B6ACED413179251BD874A8093596A98C52.

$ curl -s "https://apt.tzinit.org/keys/tzinit.asc" | gpg --import
gpg: key 1F688E1201D819B4: "Tzinit Repository Key <packages@tezos.foundation>" not changed
gpg: Total number processed: 1
gpg:              unchanged: 1
$ gpg --list-keys
...
pub   ed25519 2026-07-13 [SC]
      181E6294A0770AE9AF0173B21F688E1201D819B4
uid           [ultimate] Tzinit Repository Key <packages@tezos.foundation>

Then add the APT repositories. For Debian 13 (Trixie):

echo "deb [signed-by=/etc/apt/keyrings/tzinit.gpg] https://apt.tzinit.org/debian trixie main" \
    | sudo tee /etc/apt/sources.list.d/tzinit-octez.list

For Ubuntu 24.04 (Noble) use:

echo "deb [signed-by=/etc/apt/keyrings/tzinit.gpg] https://apt.tzinit.org/ubuntu noble main" \
    | sudo tee /etc/apt/sources.list.d/tzinit-octez.list

Then update the catalogue:

$ sudo apt update

To install a package, simply use apt and the magic happens. For example:

$ sudo apt install -y octez-client octez-node octez-baker

In fact, installing octez-baker will install the client, node, DAL node and baker packages.

If you want to use development packages, instead of https://apt.tzinit.org/debian and https://apt.tzinit.org/ubuntu use https://apt.tzinit.org/DEVEL/debian and https://apt.tzinit.org/DEVEL/ubuntu. If you are running on older architecture that doesn’t support some newer CPU instructions, you can try these repositories instead: https://apt.tzinit.org/BLSTPORTABLE/debian and https://apt.tzinit.org/BLSTPORTABLE/ubuntu.

Direct downloads and RPMs

You can directly download the packages for Debian, Ubuntu and Rocky Linux from https://packages.tzinit.org/. Each downloadable package is signed with a detached signature file, so you can verify it against the public key above.

To install the client package on Debian or Ubuntu, you can do either:

apt install ./octez-client_25.0-1_amd64.deb

or

dpkg -i octez-client_25.0-1_amd64.deb

On Rocky Linux, use dnf to install directly from a URL. You need to do a bit more first. See the Packages site for instructions.

Using the packages

For the below we will assume that you are running everything on the same server. We will assume that you are using Debian or Ubuntu, and the APT repository. We assume that you know a bit about Tezos.

Setting up a node

Install the octez-client, octez-zcash-params and octez-node packages.

$ sudo apt install -y octez-client octez-zcash-params octez-node

The file /etc/default/octez-node ships with the package and is used to declare environment variables used by the node. The defaults should be good for most sites. In the file, you can change the location of the data directory. Additional command line options can be given using RUNTIME_OPTS.

# Data Directory
# An independent mount point of /var/tezos is recommended
#
DATADIR=/var/tezos/.tezos-node

# Other options to pass the node
#
RUNTIME_OPTS=""
# On a test network you might need:
#RUNTIME_OPTS="--synchronisation-threshold=0"

As the node will be running as tezos, you will need to configure it by assuming the role of the user. For example:

$ sudo su - tezos
$ octez-node config init --network=mainnet \
			--history-mode=rolling \
			--net-addr="[::]:9732" \
			--rpc-addr="127.0.0.1:8732"

Replace mainnet with the network URL of your choice. For example, for shadownet, use https://teztnets.com/shadownet or for the current protocol testnet use https://teztnets.com/currentnet.

Then as tezos obtain a snapshot and recover it (replacing mainnet with the network of your choice):

$ wget https://snapshots.tzinit.org/mainnet/rolling
$ octez-node snapshot import rolling
$ exit

As root, you can start the node as follows:

$ sudo systemctl enable octez-node
$ sudo systemctl start octez-node

The service will start immediately but it will also restart on boot. Observe the logs as follows:

$ tail -f /var/log/tezos/octez-node.log

If you are just wanting to run a node then congratulations - you have finished.

Setting up the baking key

If you are going to run a baker, you’ll need a baking key. Key security is very important. Here I’m going to assume that you are running on a test network, in which case you can use a key on disc safely. You should consider a remote signer if not. You can use a Ledger to hold the baking key - see much further below. However, the best keys to use for baking are tz4/BLS keys. We will need two - one for consensus and one for DAL attestations called a companion key.

To generate the keys use:

$ sudo su - tezos
$ octez-client gen keys baker_key --sig bls
$ octez-client gen keys companion --sig bls

Now fund your keys by moving funds on mainnet to the baker_key or by using a faucet on the test network (see the Teztnets site). You’ll need at least 6000tz, plus some for fees.

Then register your key as a delegate and stake 6000tz:

$ octez-client register key baker_key as delegate
$ octez-client stake 6000 for baker_key

Setting up the DAL node

The Data Availability Layer (DAL) will become mandatory in future Tezos releases, so it’s good to get into the practice of running it now. The DAL package is independent of the other packages. You should use it if you are running a baker. Install the octez-dal-node packages:

$ sudo apt install -y octez-dal-node

Now find your baking key, then configure the DAL node so it knows the address of your baker key:

$ sudo su - tezos
$ octez-client list known addresses
baker_key: tz4E9Sgyx2mRg6GmVZRGNo8dD2imaXx9zfAf (unencrypted sk known)
companion: tz4TJdBjeX5cnUFPUUXgiLbdEm1G7HgGceok (unencrypted sk known)
$ octez-dal-node config init --attester=tz4E9Sgyx2mRg6GmVZRGNo8dD2imaXx9zfAf
$ exit

If you run octez-node on a different machine, you can add an --endpoint to the configuration init. Or you can edit /etc/default/octez-dal-node and the RUNTIME_OPTS variable. You can also change the location of the DAL node’s data directory there:

# Data Directory
# An independent mount point of /var/tezos is recommended
#
DATADIR=/var/tezos/.tezos-dal-node

# Other options to pass the node
#
RUNTIME_OPTS=""

# For example, if your node is elsewhere:
#RUNTIME_OPTS="--endpoint=http://mynode.local:8732"

As root, enable and start the DAL node:

$ sudo systemctl enable octez-dal-node
$ sudo systemctl start octez-dal-node

You can observe the logs in /var/log/tezos/octez-dal-node.log.

Setting up the baker

The baker package assumes that a node is already running on the same machine. This section also assumes that a DAL node is running on the same machine. Install the octez-baker package:

$ sudo apt install octez-baker

The /etc/default/octez-baker file must be edited before the baker will run. You can leave the KEYS variable empty, but then the baker will try to bake with all keys in your wallet.

You also need to set LQ_VOTE, otherwise the baker will not start. This is the liquidity baking escape hatch vote and it’s something you should decide for yourself. On a test network, you can safely vote “pass”.

Here I’ve changed the configuration to reflect the two keys we have and also the pass vote. I’ve adjusted the DAL_OPTIONS to use the DAL node on the same machine.

# Data Directory
# An independent mount point of /var/tezos is recommended
#
DATADIR=/var/tezos/.tezos-node

KEYS="baker_key companion"

# To use DAL, install the DAL node package, configure and
# use localhost.
#
#DAL_OPTIONS="--without-dal"
DAL_OPTIONS="--dal-node http://localhost:10732"

# This must be set and is your decision
LQ_VOTE="pass"

# Other options to pass to the baker
#
RUNTIME_OPTS=""

Start the baker with systemctl as root:

$ sudo systemctl enable octez-baker
$ sudo systemctl start octez-baker

You can also start an accuser service. This will watch the network for naughty behaviour, such as double baking.

$ sudo systemctl enable octez-accuser
$ sudo systemctl start octez-accuser

There are log files in /var/log/tezos.

Running a VDF service

There’s little to do to configure the VDF service, other than to set up a rolling node on the same machine. There are VDF servers running on the network already, so you don’t need to run your own. But to do so, install the octez-baker package. Then enable the VDF service like so:

$ sudo systemctl enable octez-vdf
$ sudo systemctl start octez-vdf

Using the signer package

The signer package is designed to be independent of the other packages and by default the program runs under the tzsigner user. The package only supports HTTP signing. If you want to use HTTPS or socket signing, you will need to configure the signer to start up yourself.

Install the signer package.

sudo apt-get install octez-signer

Once installed, edit the file /etc/default/octez-signer. Key things to note by default:

• The signer by default will sign any message it is given and this may not be suitable for your production environment. The configuration needs tuning.
• The configuration is set up to run an HTTP daemon but only on localhost. Setting ADDRESS="0.0.0.0" will open the service.
• The HWM_CHECK should be set to -W on a production signer supporting baking to prevent the baking key from being used to double-bake
• You should consider setting MAGIC_BYTES to prevent certain operations such as funds transfer

If you are baking, once you have self-delegated the baking key a typical configuration to protect from funds transfer and double-baking is:

MAGIC_BYTES="-M 0x11,0x12,0x13"
HWM_CHECK="-W"

Once set up, you can enable the daemon as follows:

systemctl enable octez-signer
systemctl start octez-signer

By default, the logs are stored in /var/log/tezos/octez-signer.log.

You can create a key in the tzsigner account:

$ sudo su - tzsigner
$ octez-signer gen keys alice
$ octez-signer list known addresses
alice: tz1aUmQtyXxXZoFu5jPMkJLTPA4CRDd78Yxs (unencrypted sk known)

On the client where you will use the key you can connect it as follows for HTTP:

$ octez-client import secret key alice http://hostname-of-signer:6732/tz1aUmQtyXxXZoFu5jPMkJLTPA4CRDd78Yxs

To check it is working use:

$ octez-client sign bytes 0x03 for alice
Signature: sigTti9DXgXDNYn7Kv8TaYRT4mmkjMQb2sbw4DbPZ48UbXChHCwEpHpQsSxZKrAwEntsboMzjmokNZwshCRnGJVV1tPPsR1Z

Please see the Octez Signer Manual for more details.

Using a Ledger

In an old article Setting up a Tezos Baker in 5 steps we set up a Ledger and bake with it. There is more detail there, including how to install the applications on the Ledger. The key thing to remember is that the tezos user needs access to the Ledger USB device and this is not done by default. To allow this:

As root, create a file called 20-hw1.rules in the directory /etc/udev/rules.d containing the following lines:

# All Ledger devices
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", GROUP="tezos", OWNER="tezos", MODE="0600"

Reload the USB Device service with sudo systemctl reload udev.

You should be able to see the Ledger, import the keys from it and set up the Ledger to bake.

$ sudo su - tezos
$ octez-client list connected ledgers
$ octez-client import secret key my_ledger_key \
        "ledger://change-this-to-match-yours/ed25519/0h/0h"

$ octez-client setup ledger to bake for my_ledger_key

Unfortunately, a Ledger does not support tz4 keys for baking. But what you can do is store the master baking key on the Ledger (e.g. a tz1, 2 or 3 key) and delegate consensus and companion to two tz4 keys. If you want to use a Ledger for baking with a tz1, 2 or 3 key, it’s best to use it with octez-signer.