Configuration Guide

This guide will show you how to get started with running orc! An ORC node requires a configuration file to get up and running. The path to this file is given to orc when starting a node.

orc --config path/to/orc.config

If a configuration file is not supplied, a minimal default configuration is automatically created and used, which will generate a private extended key, storage for shards, contracts, and network information. All of this data will be created and stored in $HOME/.config/orc, yielding a directory structure like this:

+- ~/.config/orc
  + - x_private_key    (Root/Parent HD identity key)
  + - config           (INI configuration file)
  + - orc.log         (Daemon log file, rotated periodically)
  + - /provider_vault  (Directory containing encrypted shards named by hash)
  + - /node_data       (MongoDB data directory)
  + - /node_hs         (Tor + hidden service data directory)

The locations of all of these files is defined in your configuration file. Below is an complete outline of each valid configuration property name, it's behavior, and default value(s). Valid configuration files may be in either INI or JSON format.


Default: $HOME/.config/orc/

The location to write the PID file for the daemon.


Default: $HOME/.config/orc/x_private_key

Path to private extended key file to use for master identity. Losing or destroying this file will lose access to your node and prevent retrieval of files. Back it up offline!


Default: 0

The index for deriving this child node's identity. This allows you to run multiple nodes with the same private extended key. If your private extended key was converted from an old non-hierarchically-deterministic private key, you must set the value to -1.


Default: $HOME/.config/orc/crypt_params

The path to read (or create on first run), the file that contains the unique salt used for key derivation and the initialization vector user for the encryption of secrets. Losing or destroying this file will lose access to your node and prevent decryption of files. Back it up offline!


Default: $HOME/.config/orc/node_data

Sets the directory to store MongoDB database files.


Default: 37017

Sets the TCP port to binding the mongod process.


Default: $HOME/.config/orc/provider_vault

Set the base directory (parent) for where shards will be placed. This directory stores other nodes' data shards, so be sure you set this to where you intend to provide capacity.


Default: 24HR

How often we should scan contract database to reap expired shards it is storing. Accepts human-readable strings like 3DAYS or 72HOURS


Default: 0GB

Define the maximum size you wish to allocate for farming shards. This can be increased later, but decreasing it will not delete existing data.


Default: 30M

The frequency interval we update our flags to reflect our available capacity.


Default: $HOME/.config/orc/node_hs

The path to the directory to instruct Tor to use for storing hidden service keys and other information.


Default: 80

Sets the virtual port number for your node's RPC onion service.


Default: 9088

Sets the local port to bind the node's RPC service.


Default: 0

Enables bandwidth metering and hibernation mode. When the property BandwidthAccountingEnabled is 1, we will enter low-bandwidth mode if the we exceed BandwidthAccountingMax within the period defined by BandwidthAccountingReset until the interval is finished.


Default: 5GB

Sets the maximum number of bandwidth to use per accounting interval for data transfer. Low-bandwidth RPC messages will still be allowed.


Default: 24HR

Resets the bandwidth accounting on an interval defined by this property.


Default: 1

More detailed logging of messages sent and received. Useful for debugging.


Default: $HEAD/.config/orc.log

Path to write the daemon's log file. Log file will rotate either every 24 hours or when it exceeds 10MB, whichever happens first.


Default: 3

Maximum number of rotated log files to keep.


Default: http://z2ybz7kjxjtfiwcervfh376swy4je3ye4yne2atoi727634qzjonk7id.onion:80

Add a map of network bootstrap nodes to this section to use for discovering other peers. Default configuration should come with a list of known and trusted contacts.



Sets the hostname or IP address to which the bridge service should be bound. It is important to set this value to a loopback address if authentication is disabled to prevent others from accessing your objects.


Default: 9089

Set the TCP port to which the bridge service's HTTP API should be bound.


Default: $HOME/.config/orc/tmp

Sets the path on the filesystem to a directory for storing temporary data for queued uploads.


Default: 24HR

If we haven't received a relayed capacity announcement from a peer within this defined timeframe, remove them from the provider pool until we receive an announcement again. Prevents attempting to use providers that are unlikely to be available.


Default: 6HR

If we have tried to store a shard with a peer and a failure occurred on the provider's end, temporarily remove them from the provider pool for this defined amount of time.


Default: 0

Redirects the Tor process log output through ORC's logger for the purpose of debugging.


Default: notice

Defines the verbosity level of the Tor process logging. Valid options are: debug, info, notice.


Default: 4

Sets the SOCKS proxy type for Tor communication. This currently defaults to 4 until this ticket is closed.



Defines a list of identities allowed to store and retrieve. The default policy allows allnodes to perform RPC calls necessary for discovering peers, storing metadata, and downloading public objects.

To establish a full trust policy with another known node, exchange your identity keys and add a wildcard policy: