Filecoin Nova

Move your website to the decentralized web. Nova creates an exact static copy of your site and deploys it to the Filecoin network in seconds -- no server migration, no infrastructure changes.

npx filecoin-nova demo https://your-site.com

Your site gets a permanent, censorship-resistant copy on Filecoin Onchain Cloud with a live URL. Keep your existing hosting, or replace it entirely.

• One command -- point Nova at your site and it handles everything
• No migration -- your existing site stays exactly as it is
• Low cost -- a fraction of traditional hosting fees
• No servers to manage -- content is stored onchain, served via IPFS gateways
• Works with any site -- static sites, React, Next.js, Vue, Nuxt, WordPress, Webflow
• ENS domains -- give your decentralized site a human-readable .eth.limo address

Try It Now

See what your site looks like on decentralized infrastructure. No account, no wallet, no cost.

In your browser: go to focify.me, paste a URL, and watch it deploy in real time.

From the command line:

npx filecoin-nova demo https://your-site.com

Your site is live in about 60 seconds at an IPFS gateway URL. This free demo uses the calibration testnet so you can evaluate before committing.

You can also deploy a local build directory:

npx filecoin-nova demo ./dist

Make Your Site Decentralized

Nova captures a pixel-perfect static copy of your site using a real browser, so JavaScript-heavy frameworks render correctly. Cross-origin API responses are captured and replayed so the copy works standalone.

# Create a decentralized copy of your site
nova clone https://your-site.com

# Limit how many pages to capture
nova clone https://your-site.com --max-pages 10

# Deploy and point an ENS domain at it
nova clone https://your-site.com --ens mysite.eth

# Capture only, review before deploying
nova clone https://your-site.com --no-deploy

Already have a static build? Deploy it directly:

# Deploy a build output directory
nova deploy ./dist

# Deploy with an ENS domain
nova deploy ./public --ens mysite.eth

# Deploy and remove previous versions
nova deploy ./dist --clean

# Deploy an archive
nova deploy site.zip

Nova accepts directories and archives (.zip, .tar.gz, .tgz, .tar).

When it's done, your site is live at:

https://mysite.eth.limo -- if you set up an ENS domain

https://<cid>.ipfs.dweb.link -- always available via IPFS gateway

A CID (Content Identifier) is a unique fingerprint for your content on IPFS. Same content always produces the same CID.

Deploy a Static Site End-to-End

Full decentralized hosting in one command: pin to Filecoin, host on your own Cloudflare domain via a bundled Worker, update DNSLink TXT, and set an ENS contenthash.

1. Drop a deploy.json next to your site:

{
  "hostname": "mysite.example.com",
  "cf_zone_id": "<your cloudflare zone id>",
  "ens_name": "mysite.eth"
}

Every field is optional:

• Omit hostname + cf_zone_id → skip Cloudflare hosting.
• Omit ens_name → skip ENS contenthash update.
• Add "dist": "site" → deploy a pre-built directory (no build step).
• Add "apiProxy": { "/api": "https://backend.example.com" } → Worker reverse-proxies those paths to your backend.

2. Deploy:

export NOVA_PIN_KEY=0x...              # FOC signing key
export NOVA_WALLET_ADDRESS=0x...       # FOC wallet
export NOVA_ENS_KEY=0x...              # optional, only if ens_name set
export CLOUDFLARE_API_TOKEN=...        # optional, only if hostname set

nova site deploy --site ./

On first run Nova provisions a Cloudflare Worker (filecoin-nova-gateway) + KV namespace in your account, creates a proxied DNS record, and binds the route. On every subsequent run it's a KV write + DNSLink PATCH + ENS update — seconds. All steps are idempotent; re-runs are safe.

3. GitHub Actions (reusable workflow):

name: Deploy
on:
  push: { branches: [main], paths: ['sites/**'] }
jobs:
  deploy:
    uses: FilOzone/filecoin-nova/.github/workflows/[email protected]
    secrets:
      NOVA_PIN_KEY:         ${{ secrets.NOVA_PIN_KEY }}
      NOVA_WALLET_ADDRESS:  ${{ secrets.NOVA_WALLET_ADDRESS }}
      NOVA_ENS_KEY:         ${{ secrets.NOVA_ENS_KEY }}
      NOVA_RPC_URL:         ${{ secrets.NOVA_RPC_URL }}
      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

The reusable workflow auto-detects sites (any directory containing a deploy.json), runs npm ci / optional check / build, then invokes nova site deploy for each. Matrix is serialised (max-parallel: 1) to avoid nonce collisions on the ENS delegate wallet.

Reuse an existing Worker + KV (for teams migrating from a self-managed gateway): set these as GitHub Actions variables (not secrets):

NOVA_WORKER_NAME       = <your existing worker script name>
NOVA_KV_NAMESPACE_ID   = <your existing KV namespace id>
NOVA_WORKER_UPLOAD     = skip

Nova will write to your existing KV and leave the Worker script alone.

AI Editor Integration (MCP)

Nova includes an MCP server so your AI editor can deploy and manage sites through conversation.

Setup

Claude Code:

npm install -g filecoin-nova
claude mcp add filecoin-nova -s user -- nova-mcp

Claude Desktop: Settings > MCP > Add MCP Server. Set command to nova-mcp.

Cursor / Windsurf / VS Code:

| Editor | Config file | |--------|------------| | Cursor | ~/.cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | VS Code | .vscode/mcp.json |

{
  "mcpServers": {
    "filecoin-nova": {
      "command": "npx",
      "args": ["-y", "--package", "filecoin-nova", "nova-mcp"]
    }
  }
}

What you can ask

• "Deploy my site to Filecoin"
• "Make a decentralized copy of example.com"
• "Update the ENS for mysite.eth"
• "What's currently deployed on mysite.eth?"
• "Clean up old deployments"

No wallet needed to start. The AI uses nova_demo for instant free deploys, and guides you through permanent hosting when you're ready.

Tools

| Tool | What it does | |------|-------------| | nova_demo | Deploy for free, no wallet needed | | nova_clone | Clone a website into a deployable directory | | nova_deploy | Deploy to mainnet with optional ENS | | nova_ens | Point an ENS domain to a CID | | nova_status | Check what an ENS domain points to | | nova_info | Show details for a specific deployment | | nova_wallet | Show wallet balance and deposit status | | nova_download | Download content from IPFS | | nova_manage | List all stored content | | nova_manage_clean | Remove old content to reduce costs | | nova_poll | Check if a browser-signed transaction completed |

SKILL.md

Nova ships a SKILL.md in the npm package that teaches any AI assistant how to use the MCP tools. If your AI tool supports skill files, point it at node_modules/filecoin-nova/SKILL.md.

Auth

Nova is designed so you never need to paste private keys.

Demo mode (no auth)

nova demo works instantly. Free, calibration testnet, no wallet needed.

Private key (permanent hosting)

For deploys and storage management, set NOVA_PIN_KEY with your Filecoin private key:

export NOVA_PIN_KEY=0x...
nova deploy ./dist

Browser signing (no keys on disk)

If you prefer not to store a private key, Nova can open a browser page where you sign with MetaMask -- no keys to copy or paste:

# Deploy via browser signing
nova deploy ./dist
# Opens https://fil.focify.eth.limo, waits for confirmation

This works for any write operation (deploy, clean). Your key never leaves the browser.

Read-only access

Commands like nova manage, nova info, and nova wallet only need a wallet address -- no private key:

export NOVA_WALLET_ADDRESS=0x...
nova manage

Or pass it as a flag:

nova manage --wallet 0x...

ENS updates

ENS updates require an Ethereum wallet. Nova opens a browser page where you sign with MetaMask:

# Check what an ENS domain points to
nova ens mysite.eth

# Update ENS to point to a new CID
nova ens bafybei... --ens mysite.eth
# Opens signing page, waits for confirmation

Or set NOVA_ENS_KEY for automated ENS updates in CI:

export NOVA_ENS_KEY=0x...
nova ens bafybei... --ens mysite.eth

Environment variables

For CI/automation:

| Variable | What it does | |----------|-------------| | NOVA_PIN_KEY | Filecoin private key (deploy, clean) | | NOVA_WALLET_ADDRESS | Wallet address (read-only: manage, info, wallet) | | NOVA_ENS_KEY | Ethereum private key for ENS updates | | NOVA_ENS_NAME | Default ENS domain | | NOVA_RPC_URL | Custom Ethereum RPC | | NOVA_PROVIDER_ID | Storage provider ID |

Manage Storage

Each deploy creates pieces on Filecoin. Over time, previous versions accumulate. Nova helps you see what's stored and clean up what you don't need.

# See all stored content grouped by deploy (with timestamps and proof status)
nova manage

# Get details for a specific deployment
nova info bafybei...

# Check wallet balance and deposit status
nova wallet

# Download a previous deployment
nova download bafybei... ./local-copy

# Preview what would be cleaned up (safe dry-run)
nova manage clean

# Remove old/duplicate versions
nova manage clean --really-do-it

# Keep specific versions, remove everything else
nova manage clean --keep bafybei...,bafybei... --really-do-it

Cleanup is safe by default -- nova manage clean only shows a plan. You need --really-do-it and a confirmation to execute.

What You Need

For demo mode: just Node.js 20.10+.

For permanent hosting:

| What | Why | Get started | |------|-----|-------------| | Node.js 20.10+ | Runs Nova | Download from nodejs.org | | MetaMask with FIL and USDFC | FIL for gas, USDFC for storage | Set up MetaMask for Filecoin, then swap for USDFC | | MetaMask with ETH (optional) | Gas for ENS updates | Same MetaMask wallet | | An ENS domain (optional) | Human-readable URL | Register at app.ens.domains |

Commands

| Command | What it does | |---------|-------------| | nova demo <url-or-path> | Deploy for free, no wallet needed | | nova clone <url> | Capture your site and deploy to Filecoin | | nova deploy [path] | Deploy a local directory or archive | | nova ens <name> | Check what an ENS domain points to | | nova ens <cid> --ens <name> | Point an ENS domain to a CID | | nova info <cid> | Show details for a specific deployment | | nova wallet | Show wallet balance and deposit status | | nova download <cid> [dir] | Download content from IPFS | | nova manage | List all stored content | | nova manage clean | Remove old/duplicate content |

Options:

| Flag | Commands | What it does | |------|----------|-------------| | --no-deploy | clone | Capture only, don't deploy | | --no-ens | clone, deploy | Skip ENS prompt and ENS update | | --max-pages <n> | clone, demo | Max pages to crawl (default: 50, 0 = unlimited). Includes sitemap-discovered pages. Top-level pages are prioritised over deep links. | | --screenshots | clone | Save before/after comparison | | --output <dir> | clone | Output directory | | --label <text> | clone, deploy | Label for this deploy (shown in nova manage) | | --ens <name> | clone, deploy, ens | ENS domain (e.g. mysite.eth) | | --rpc-url <url> | clone, deploy, ens | Custom Ethereum RPC | | --provider-id <id> | clone, deploy | Storage provider ID | | --clean | clone, deploy | Remove all previous versions after deploy | | -w, --wallet <addr> | info, wallet, manage | Wallet address for read-only commands | | --calibration | clone, deploy, info, wallet, manage | Use testnet instead of mainnet | | --json | clone, deploy, ens, info, wallet, download, manage | Machine-readable JSON output | | --really-do-it | manage clean | Execute the cleanup | | --keep <cid,...> | manage clean | Keep specific CIDs, remove the rest | | --remove <cid,...> | manage clean | Remove specific CIDs only | | --keep-copies | manage clean | Keep all copies (Nova stores 2 copies by default for redundancy) | | --dataset-id <id> | manage | Target a specific dataset |

GitHub Action

Nova provides a GitHub Action for automated deploys on every push or pull request.

Basic deploy on push

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: FilOzone/filecoin-nova/.github/action@main
        with:
          path: ./public
        env:
          NOVA_PIN_KEY: ${{ secrets.NOVA_PIN_KEY }}

Build + deploy + ENS + PR previews

name: Deploy
on:
  push:
    branches: [main]
  pull_request:
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: FilOzone/filecoin-nova/.github/action@main
        id: nova
        with:
          build-command: 'npm ci && npm run build'
          path: ./dist
          ens-name: ${{ github.ref == 'refs/heads/main' && 'mysite.eth' || '' }}
          clean: ${{ github.ref == 'refs/heads/main' }}
          calibration: ${{ github.event_name == 'pull_request' }}
          label: ${{ github.sha }}
        env:
          NOVA_PIN_KEY: ${{ secrets.NOVA_PIN_KEY }}
          NOVA_ENS_KEY: ${{ github.ref == 'refs/heads/main' && secrets.NOVA_ENS_KEY || '' }}

PR pushes deploy to calibnet (no secrets needed), main pushes deploy to mainnet with ENS and cleanup.

Inputs

| Input | Default | Description | |-------|---------|-------------| | path | . | Directory to deploy | | build-command | | Build command to run first | | node-version | 22 | Node.js version | | ens-name | | ENS domain to update | | label | | Deployment label | | provider-id | | Target specific storage provider | | clean | false | Remove old pieces after deploy | | calibration | false | Use calibration testnet | | comment | true | Post PR comment with deploy URL | | nova-version | latest | Nova version to install |

Outputs

| Output | Description | |--------|-------------| | cid | IPFS CID of the deployed content | | gateway-url | IPFS gateway URL | | ens-url | ENS gateway URL (if ENS was updated) | | tx-hash | ENS update transaction hash |

Auth

Pass auth via environment variables. For calibnet deploys without NOVA_PIN_KEY, the action automatically uses demo mode (no secrets needed).

| Variable | Required | What it does | |----------|----------|-------------| | NOVA_PIN_KEY | For mainnet | Filecoin private key | | NOVA_ENS_KEY | For ENS | Ethereum private key for ENS updates |

Rollback

Content on Filecoin is immutable. To roll back, point ENS to a previous CID:

nova ens <old-cid> --ens mysite.eth

Use as a Library

import { deploy } from "filecoin-nova";

const result = await deploy({
  path: "./public",
  pinKey: process.env.NOVA_PIN_KEY,
  ensName: "mysite.eth",
  ensKey: process.env.NOVA_ENS_KEY,
});

console.log(result.cid);        // bafybei...
console.log(result.ethLimoUrl);  // https://mysite.eth.limo

How It Works

1. Capture -- Nova renders your site in a real browser, downloads every page and asset, and rewrites URLs to local paths. The result is a self-contained static copy.
2. Deploy -- The copy is packaged as a CAR file and uploaded to Filecoin Onchain Cloud, stored onchain as content-addressed pieces. Your site gets an IPFS CID.
3. Resolve -- If you set up an ENS domain, Nova updates its contenthash so anyone can visit yoursite.eth.limo. The content is served through IPFS gateways worldwide.

License

MIT