Skip to content

The Daemon

All desktop and server peers run as a daemon, which contains an embedded IPFS node. Much like the IPFS daemon, the program (textile) ships with a command-line client.

The daemon can be used to run an account peer or a cafe peer.


A daemon is a program that operates as a long-running 'background' process (without a terminal or user interface). In most cases, the daemon exposes a network API (usually HTTP / TCP) that allows other programs to interact with it while it's running. Most daemons ship with a command-line client for this API.


Download and extract the latest release for your OS and architecture or jump to Docker.

macOS and Linux:

tar xvfz go-textile_$VERSION_$OS-$ARCH.tar.gz

Move textile anyplace in your PATH or run the install script, which puts it in /usr/local/bin:



Extract the zip file and move textile.exe anyplace in your PATH.


See available tags here.


Once you have textile available on your system, you can run your own peer.

Create a new wallet

The first step is to create a new wallet.

Textile uses a hierarchical deterministic (HD) wallet to derive account keys from a set of unique words, called a mnemonic phrase.

Initialize a wallet with the command-line client (this will not persist anything to your filesystem):

textile wallet init

This will output something like,

| field speak key various picture captain laugh produce word cage estate space |
WARNING! Store these words above in a safe place!
WARNING! If you lose your words, you will lose access to data in all derived accounts!
WARNING! Anyone who has access to these words can access your wallet accounts!

Use: `wallet accounts` command to inspect more accounts.

--- ACCOUNT 0 ---

You may optionally specify a word count and password that will be required along with your mnemonic phrase when accessing the wallet's account keys (run with --help for usage).


Every key "inside" an HD wallet can be derived from this mnemonic phrase. Effectively, the wallet is the mnemonic phrase.

The output contains information about the wallet's first account, or the keys at index 0. Account seeds (private keys) always starts with an "S" for "secret" and account addresses (public keys) always start with a "P" for "public".

Access wallet accounts

Most users will only be interested in the first account keys, but you can access deeper indexes with the accounts sub-command:

textile wallet accounts "field speak key various picture captain laugh produce word cage estate space" --depth 3
--- ACCOUNT 0 ---
--- ACCOUNT 1 ---
--- ACCOUNT 2 ---

See textile wallet accounts --help for more.

Initialize an account peer

Next, use an account seed from your wallet to initialize a new account peer. Here, we just grab the account seed from the first account above:

textile init --seed SSkyezjKSb979BYYkwhgbq8GyB5HRry3gtf8CJBaNRKpFdt6


Use your own seed. Never share it or your wallet mnemonic phrase with anyone!

There are a dozen or so additional options that are available when initializing. textile init --help:

  textile [OPTIONS] init [init-OPTIONS]

Initialize the node repository and exit.

Help Options:
  -h, --help                   Show this help message

[init command options]
      -s, --seed=              Account seed (run 'wallet' command to generate new seeds).
      -p, --pin-code=          Specify a pin code for datastore encryption.
      -r, --repo-dir=          Specify a custom repository path.

    Address Options:
      -a, --api-bind-addr=     Set the local API address. (default:
      -c, --cafe-bind-addr=    Set the cafe REST API address. (default:
      -g, --gateway-bind-addr= Set the IPFS gateway address. (default:

    Cafe Options:
          --cafe-open          Open the p2p Cafe Service for other peers.
          --cafe-public-ip=    Required with --cafe-open on a server with a public IP address.
          --cafe-url=          Specify the URL of this cafe, e.g.,
          --cafe-neighbor-url= Specify the URL of a secondary cafe. Must return cafe info, e.g., via a Gateway:, or a Cafe API:

    IPFS Options:
          --server             Apply IPFS server profile.
          --swarm-ports=       Set the swarm ports (TCP,WS). Random ports are chosen by default.

    Log Options:
      -n, --no-log-files       Write logs to stdout instead of rolling files.
      -d, --debug              Set the logging level to debug.

Anyone familiar with IPFS will recognize the similarities with these steps. Much like ipfs init, textile init creates an IPFS node repository on disk.

Initialize a cafe peer

Anyone can run a cafe peer and offer services to the network. You do not need to rely on Textile's cafe network, or anyone else's network for that matter!

Cafe peers are initialized by adding some additional flags to textile init:

textile init --seed SSkyezjKSb979BYYkwhgbq8GyB5HRry3gtf8CJBaNRKpFdt6 --server --cafe-open

--server: This flag applies the IPFS server profile and is highly recommended for cafe peers.

--cafe-open: This flag "opens" the cafe, meaning that it will expose an additional "service" API over libp2p and HTTP.

--cafe-url: Optional, http://<SWARM_IP>:40601 by default. Set this value if your peer is behind a DNS-based load balancer and/or requires HTTPS. For example, Textile's federated cafes run behind EC2 load balancers with HTTPS listeners, which route traffic to the cafe API port (--cafe-bind-addr). See Cafe.CafeHost.URL for details on how the default value of SWARM_IP is determined.


Cafe service clients are issued JWT sessions used for authentication. These sessions contain the public URL of the cafe peer's service API so that it can be leveraged over HTTP.

Later, when the peer is started, it's service info will be visible at the cafe URL, e.g.,

    "peer": "12D3KooWQue2dSRqnZTVvikoxorZQ5Qyyug3hV65rYnWYpYsNMRE",
    "address": "P6th8SM6V3uSVQWgQz8AkFos3rwYzky2K7Bt6vx4h1jZGZne",
    "api": "v0",
    "protocol": "/textile/cafe/1.0.0",
    "node": "0.1.11",
    "url": "",
    "swarm": [

You can modify the init settings anytime but editing the config file and restarting the peer. Read more about the cafe host config settings here.

Run the daemon

Now that you have initialized as either an account peer or a cafe peer, you can finally start the daemon:

textile daemon

See textile daemon --help for more options.

Run the daemon with Docker

The docker images have internal logic that will fist initialize a peer if needed before starting the daemon, enabling a single run command:

Run an account peer with docker

docker run -it --name textile-peer \
  -p 4001:4001 -p 8081:8081 -p 5050:5050 -p \
  -v /tmp/textile:/data/textile textile/go-textile:latest

Run a cafe peer with docker

docker run -it --name textile-cafe-peer \
  -p 4001:4001 -p 8081:8081 -p 5050:5050 -p -p 40601:40601 \
  -v /tmp/textile:/data/textile textile/go-textile:latest-cafe

You may need to include -e CAFE_HOST_URL="" or similar if the cafe peer will behind a DNS-based load balancer or required HTTPS. See the init section above for more.


At last, your Textile peer is online. Now you're ready to start the tour!