Quick Start Guide

Get started with Alternate Futures in minutes. This guide will walk you through your first deployment to decentralized infrastructure.

What You'll Learn

By the end of this guide, you'll have:

Installed the Alternate Futures CLI
Authenticated with the platform
Deployed your first site to IPFS
Understood the basics of decentralized deployment

Time to complete: 5-10 minutes

Prerequisites

Before you begin, make sure you have:

An Alternate Futures account - Sign up here (free, no credit card required)
- You can sign in with email, Google, GitHub, or a Web3 wallet
Node.js 18 or later - Download here if you don't have it
- Check your version with node --version
A project to deploy (optional for learning)
- Any static site (HTML, CSS, JavaScript)
- Built output folder (usually dist, build, or public)
- Don't have one? We'll create a simple example below

Using the Web App

Coming Soon

The web application is currently in development. In the meantime, you can use the CLI or SDK to access the full platform.

Installation

CLISDK

bash

# Install the CLI globally
npm install -g @alternatefutures/cli

bash

# Install the SDK in your project
npm install @alternatefutures/sdk

Step 2: Authenticate

There are two ways to authenticate with Alternate Futures:

CLI

bash

# Login interactively
af login

This will open your browser where you can sign in with:

Email (magic link - no password needed)
Google account
GitHub account
Web3 wallet (MetaMask, Coinbase Wallet, etc.)

After signing in, the CLI automatically saves your credentials. You're ready to deploy!

Option 2: Personal Access Token (Recommended for CI/CD and Automation)

If you prefer tokens or need to automate deployments:

Log in via the CLI first: af login
Create a Personal Access Token: af pat create --name "My Development Token"
Copy the token (it starts with pat_...)
Note your project ID from af projects list
Set them as environment variables:

CLISDK

bash

# Set environment variables
export AF_TOKEN=pat_your_token_here
export AF_PROJECT_ID=prj_your_project_id

# Or add to your .bashrc/.zshrc for persistence
echo 'export AF_TOKEN=pat_your_token_here' >> ~/.bashrc
echo 'export AF_PROJECT_ID=prj_your_project_id' >> ~/.bashrc

typescript

import { AlternateFuturesSdk, PersonalAccessTokenService } from '@alternatefutures/sdk/node';

// Initialize with personal access token
const af = new AlternateFuturesSdk({
  accessTokenService: new PersonalAccessTokenService({
    personalAccessToken: process.env.AF_TOKEN,
    projectId: process.env.AF_PROJECT_ID,
  }),
});

Security Best Practices

Never commit tokens to version control. Here's why and how to keep them safe:

What are environment variables? Environment variables store sensitive information (like tokens) outside your code files. This keeps secrets safe and lets you use different tokens in development vs. production.

How to use them:

Store your token in a .env file:

env

AF_TOKEN=pat_your_token_here
AF_PROJECT_ID=prj_your_project_id

Add .env to your .gitignore file so Git doesn't track it
Your code reads from process.env.AF_TOKEN instead of hardcoding the key

Why this matters:

If you commit tokens to Git, they're visible in your repository history forever
Anyone with access to your repo could steal your tokens and rack up charges on your account
.gitignore tells Git to ignore certain files (like .env) when committing

New to these concepts?

Learn about .env files (official dotenv documentation)
Learn about environment variables on Docker Docs
Learn about .gitignore files (official Git documentation)
See our Glossary for more terms

Troubleshooting Authentication

"Command not found: af"

Make sure you installed the CLI: npm install -g @alternatefutures/cli
Try restarting your terminal
Check installation with npm list -g @alternatefutures/cli

"Login failed" or browser doesn't open

Try the API key method instead
Check your internet connection
Make sure you have an account at https://app.alternatefutures.ai

"Invalid token"

Double-check you copied the entire token (starts with pat_)
Make sure there are no extra spaces
Generate a new token if needed: af pat create --name "New Token"

Step 3: Deploy Your First Site

Now for the exciting part—deploying to decentralized infrastructure!

What does "deploy" mean? Deployment is the process of uploading your website files to a server so others can access them online. You'll upload to a decentralized network where your files are distributed across many computers worldwide, instead of using a traditional server (like AWS or a web hosting company).

Why is this different?

Traditional hosting: Your site lives on one company's servers. If they go down or delete your account, your site disappears.
Decentralized hosting: Your site is stored across hundreds of independent computers. No single company controls it, so it can't be taken down.

What you'll need: Just your website files in a folder (called the "build output" or "dist folder").

Don't Have a Site Ready?

No problem! You have two options:

Option 1: Use a Starter Template (Recommended)

We provide ready-to-deploy templates for popular frameworks. Choose one that fits your project:

React (Vite)

bash

# Clone the React template
git clone https://github.com/alternatefutures/template-react my-site
cd my-site

# Install dependencies
npm install

# Build for production
npm run build

# Initialize and deploy (build output is in ./dist)
af sites init
af sites deploy

Template Repository | React Docs | Vite Docs

Next.js (Static Export)

bash

# Clone the Next.js template
git clone https://github.com/alternatefutures/template-nextjs my-site
cd my-site

# Install dependencies
npm install

# Build static export
npm run build

# Initialize and deploy (build output is in ./out)
af sites init
af sites deploy

Template Repository | Next.js Docs

Vue.js (Vite)

bash

# Clone the Vue template
git clone https://github.com/alternatefutures/template-vue my-site
cd my-site

# Install dependencies
npm install

# Build for production
npm run build

# Initialize and deploy (build output is in ./dist)
af sites init
af sites deploy

Template Repository | Vue.js Docs | Vite Docs

Astro

bash

# Clone the Astro template
git clone https://github.com/alternatefutures/template-astro my-site
cd my-site

# Install dependencies
npm install

# Build for production
npm run build

# Initialize and deploy (build output is in ./dist)
af sites init
af sites deploy

Template Repository | Astro Docs

SvelteKit (Static Adapter)

bash

# Clone the SvelteKit template
git clone https://github.com/alternatefutures/template-sveltekit my-site
cd my-site

# Install dependencies
npm install

# Build static export
npm run build

# Initialize and deploy (build output is in ./build)
af sites init
af sites deploy

Template Repository | SvelteKit Docs

Hugo (Static Site Generator)

bash

# Clone the Hugo template
git clone https://github.com/alternatefutures/template-hugo my-site
cd my-site

# Build for production (requires Hugo installed)
hugo

# Initialize and deploy (build output is in ./public)
af sites init
af sites deploy

Template Repository | Hugo Docs

VitePress (Documentation)

bash

# Clone the VitePress template
git clone https://github.com/alternatefutures/template-vitepress my-site
cd my-site

# Install dependencies
npm install

# Build for production
npm run docs:build

# Initialize and deploy (build output is in ./docs/.vitepress/dist)
af sites init
af sites deploy

Template Repository | VitePress Docs

Framework Not Listed?

Any static site generator works with Alternate Futures! Just build your site and deploy the output directory. Common output folders: dist/, build/, out/, public/.

Option 2: Create a Simple HTML Site

If you just want to test quickly without a framework:

Creating a basic HTML site

bash

# Create a test directory
mkdir my-first-site
cd my-first-site

# Create a simple HTML file
cat > index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
    <title>My First Decentralized Site</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            max-width: 800px;
            margin: 50px auto;
            padding: 20px;
            text-align: center;
        }
        h1 { color: #4A90E2; }
    </style>
</head>
<body>
    <h1>🚀 Hello Decentralized Web!</h1>
    <p>This site is hosted on IPFS using Alternate Futures.</p>
    <p>No centralized servers. No single point of failure.</p>
</body>
</html>
EOF

# Create a dist folder (where build output typically goes)
mkdir dist
cp index.html dist/

Great! You now have a simple site ready to deploy. Continue to the next section to deploy it.

Deploy to a Storage Network

Now let's deploy your site to a decentralized storage network. You have three options:

Choosing a Storage Network

For this tutorial, use IPFS - it's the easiest to start with and works great for testing and learning.

What are these networks?

IPFS (InterPlanetary File System) - Like peer-to-peer file sharing but for your website. Instead of living on one server, your site lives everywhere. Best for: Testing, frequently updated sites. Cost: ~$0.15/GB/month
Filecoin - A marketplace where you rent storage from miners who compete to store your data cheaply. Best for: Large files, backups. Cost: ~$0.03/GB/month
Arweave - Pay once, store forever. Your data is permanent and can never be deleted. Best for: NFT metadata, permanent archives. Cost: ~$6/GB one-time

Want to learn more? See our storage network comparison guide or glossary entries for IPFS, Filecoin, and Arweave.

CLISDK

bash

# Initialize site configuration (creates af.config.json)
af sites init

# Follow the prompts to configure:
# - Site name
# - Build command (optional)
# - Output directory (dist, build, etc.)
# - Storage network (IPFS, Filecoin, Arweave)

# Deploy the site
af sites deploy

# You should see output like:
# ✓ Building site...
# ✓ Uploading files to IPFS...
# ✓ Deployment successful!
# ✓ CID: bafybei...
# ✓ URL: https://ipfs.io/ipfs/bafybei...

typescript

import { AlternateFuturesSdk, PersonalAccessTokenService } from '@alternatefutures/sdk/node';

// Initialize the SDK
const af = new AlternateFuturesSdk({
  accessTokenService: new PersonalAccessTokenService({
    personalAccessToken: process.env.AF_TOKEN,
    projectId: process.env.AF_PROJECT_ID,
  }),
});

// Upload to IPFS
const result = await af.ipfs().add('./dist');
console.log('CID:', result.pin.cid);

// List your sites
const sites = await af.sites().list();
console.log('Sites:', sites);

What Just Happened?

When you deployed, Alternate Futures:

Bundled your files - Packaged all files in the ./dist folder
Uploaded to IPFS - Sent them to the InterPlanetary File System
Generated a CID - Created a unique Content Identifier (like a fingerprint for your site)
Pinned the content - Ensured your files stay available on the network
Gave you a URL - Your site is now live and accessible worldwide!

What's a CID? It's a unique identifier for your content, like bafybei.... It's based on your content itself, so identical content always has the same CID.

View Your Deployments

CLISDK

bash

# List all your sites
af sites list

# View deployments for a specific site
af sites deployments --slug my-site

# Output shows:
# - Site name and slug
# - CID
# - URL
# - Deployment date

typescript

import { AlternateFuturesSdk, PersonalAccessTokenService } from '@alternatefutures/sdk/node';

const af = new AlternateFuturesSdk({
  accessTokenService: new PersonalAccessTokenService({
    personalAccessToken: process.env.AF_TOKEN,
    projectId: process.env.AF_PROJECT_ID,
  }),
});

// List all sites
const sites = await af.sites().list();

sites.forEach(site => {
  console.log(`${site.name}: ${site.slug}`);
});

Troubleshooting Deployment

"No such file or directory: ./dist"

Make sure the directory exists
Use the correct path to your build output
Try an absolute path: af sites deploy /full/path/to/dist --network ipfs

"Deployment failed" or timeout errors

Check your internet connection
Verify you're authenticated: af login
Try again—network issues can be temporary
Try a smaller deployment first to test

"No files found to deploy"

Make sure your directory isn't empty
Check for hidden .gitignore or .npmignore excluding files
List the directory contents: ls -la ./dist

Success!

Your site is now live on decentralized infrastructure! The URL works from anywhere in the world, and your content can't be taken down by any single company or server failure.

Try visiting your URL in a browser—you should see your site live!

Understanding Storage Networks

You deployed to IPFS, but Alternate Futures supports three decentralized storage networks. Here's a quick comparison:

Network	Best For	Cost	Permanence
IPFS	Testing, frequent updates, dynamic content	~$0.15/GB/month	While pinned
Filecoin	Large files, backups, cost-sensitive projects	~$0.03/GB/month	Contract-based
Arweave	NFTs, archives, immutable content	~$6/GB one-time	Permanent

Quick Guide:

Just learning? Use IPFS
Building an NFT project? Use Arweave
Need cheap storage for large files? Use Filecoin
Production website? Use IPFS with Arweave backup

Learn more in the Sites Guide or Storage Management Guide.

Next Steps

Congratulations! You've deployed your first site to decentralized infrastructure. Here's what to explore next:

Core Features

Deploying Sites - Learn about storage networks, custom domains, and advanced deployment options
Managing AI Agents - Deploy chatbots and AI assistants that run 24/7
Cloud Functions - Build serverless APIs and backend logic
Storage Management - Manage files across IPFS, Filecoin, and Arweave

Configuration

Authentication - Set up multi-method auth (email, social, Web3 wallets)
API Keys - Generate keys for programmatic access
Custom Domains - Connect your own domain name
Projects - Organize your deployments

Developer Tools

CLI Commands - Complete command reference
SDK API Reference - TypeScript SDK documentation
CI/CD Integration - Automate deployments with GitHub Actions, GitLab CI, etc.
Best Practices - Optimization tips and patterns

Advanced

Decentralized Registry - Self-hosted container registry
Private Gateways - Run your own IPFS gateway
ENS Integration - Link Ethereum Name Service domains

Need Help?

Glossary - Definitions of technical terms (coming soon)
GitHub Issues - Report bugs or request features
Community - Join our Discord or Twitter

What You Learned

In this quickstart, you:

✅ Installed the Alternate Futures CLI
✅ Authenticated with the platform
✅ Created a simple website
✅ Deployed it to IPFS
✅ Understood what CIDs are and how decentralized hosting works
✅ Got your first site live on decentralized infrastructure

You're now ready to build on the decentralized web! 🚀

Quick Start Guide ​

What You'll Learn ​

Prerequisites ​

Using the Web App ​

Installation ​

Step 2: Authenticate ​

Option 1: Interactive Login (Recommended for Getting Started) ​

Option 2: Personal Access Token (Recommended for CI/CD and Automation) ​

Security Best Practices

Troubleshooting Authentication ​

Step 3: Deploy Your First Site ​

Don't Have a Site Ready? ​

Option 1: Use a Starter Template (Recommended) ​

Option 2: Create a Simple HTML Site ​

Deploy to a Storage Network ​

What Just Happened? ​

View Your Deployments ​

Troubleshooting Deployment ​

Success! ​

Understanding Storage Networks ​

Next Steps ​

Core Features ​

Configuration ​

Developer Tools ​

Advanced ​

Need Help? ​

What You Learned ​

Quick Start Guide

What You'll Learn

Prerequisites

Using the Web App

Installation

Step 2: Authenticate

Option 1: Interactive Login (Recommended for Getting Started)

Option 2: Personal Access Token (Recommended for CI/CD and Automation)

Troubleshooting Authentication

Step 3: Deploy Your First Site

Don't Have a Site Ready?

Option 1: Use a Starter Template (Recommended)

Option 2: Create a Simple HTML Site

Deploy to a Storage Network

What Just Happened?

View Your Deployments

Troubleshooting Deployment

Success!

Understanding Storage Networks

Next Steps

Core Features

Configuration

Developer Tools

Advanced

Need Help?

What You Learned