Skip to main content

Getting Started

Cygnus is a fast and lightweight storage provider for the Atlas Protocol network, written in Go. It runs as a standalone daemon that connects to the Atlas blockchain, serves file uploads/downloads, responds to proof challenges, and sweeps stray files. The source lives at github.com/Atlas-DePIN/cygnus.

This guide walks through setting up and running your own storage provider.

Prerequisites​

  • Go 1.22+
  • ATL tokens for the provider wallet — registering a provider requires a 10,000 ATL deposit (returned when the provider is sunsetted)
  • A reachable hostname or public IP for the provider's API server (port 3333 by default)
  • Enough disk space for total_bytes_offered plus the local data index

Install​

Download the latest release from the cygnus repository:

curl -LO https://github.com/Atlas-DePIN/cygnus/releases/download/v0.1.0/cygnus-linux-amd64
chmod +x cygnus-linux-amd64
mv cygnus-linux-amd64 /usr/local/bin/cygnus
note

Releases are not published yet — check the repository for updates, or build from source while waiting.

Verify the install:

cygnus version

Initialize​

cygnus init

This creates the config folder and wallet:

  1. Generates config.yaml with sensible defaults.
  2. Prompts for wallet setup — choose 1. Create a new wallet or 2. Import from mnemonic.
  3. If creating a new wallet, a BIP39 mnemonic is generated. Save it in a secure location — it cannot be recovered if lost.

The wallet is stored in the Cosmos keyring (default backend: test) under the key name cygnus.

Fund the provider wallet​

Before the provider can start, send 10,000 ATL to the wallet address printed during cygnus init. This amount is held as a security deposit and is returned when the provider is sunsetted (removed from the network).

If you didn't note the address down, you can find it again in the wallet info file:

cat ~/.cygnus/wallet.json   # shows the "address" field

Configuration​

The generated config.yaml lives in the home directory (~/.cygnus/config.yaml by default):

data_directory: ~/.cygnus/data      # where file data is stored

chain_config:
  chain_id: atlas-1
  keyring_backend: test
  rpc_addr: https://rpc.atlasprotocol.cloud
  grpc_addr: grpc.atlasprotocol.cloud:443
  gas_price: "0.03uatl"
  gas_adjustment: 2.0

api_config:
  port: 3333                        # provider API port
  max_upload_size: 4294967296       # 4 GiB max upload
  pause_uploads_for_proofs: true    # prioritize proofs over uploads
  fsync_uploads: false

provider_name: My First Provider
hostname: localhost                   # public hostname or IP
total_bytes_offered: 10000000000    # 10 GB of committed capacity
cache_merkle_trees: true

stray_sweep:
  enabled: true
  interval_seconds: 60
  max_claims_per_sweep: 25
  max_concurrent_claims: 5

Key fields to set before starting:

  • hostname — your provider's public hostname or IP. This is what clients use to reach your API server. Set it to your actual domain/IP, not localhost.
  • total_bytes_offered — the amount of capacity you are committing to the network, in bytes.
  • provider_name — a human-readable label for your provider.
  • api_config.port — the port your API server listens on (default 3333). Open it in your firewall.

Start the provider​

cygnus start

On startup, Cygnus:

  1. Connects to the chain via gRPC and loads the wallet.
  2. Fetches storage module parameters (proof round/window blocks).
  3. Checks whether the wallet is a registered provider on-chain. If not registered, it automatically broadcasts a RegisterProvider transaction using the configured hostname and capacity (requires 10,000 ATL in provider wallet).
  4. Starts the API server, chain event listener, block polling, and stray-file sweeper.

Registration notes​

  • The wallet address used to register is the provider identity on-chain. Its hostname and total_bytes_offered are recorded in the provider record.
  • If the wallet does not have sufficient ATL balance for the 10,000 ATL deposit, registration fails and the provider does not start.
  • If the wallet was already registered under a different hostname or capacity, start logs a warning — use cygnus sync to push config changes.

See Sync & Maintenance for updating your on-chain provider record and keeping the node clean, and the Provider API for the REST endpoints your node exposes.