Publish with IPNS

IPNS (InterPlanetary Name System) lets you publish content under a stable name that can be updated to point at new CIDs. This is useful for websites that update frequently; instead of changing DNS records every time, you update the IPNS record.

How IPNS fits into website hosting

When you create a website, you can set target_type to either ipfs or ipns:

• ipfs: The domain points directly at a CID. To update, change target_hash on the website record.
• ipns: The domain points at an IPNS name. To update, republish the IPNS name with a new CID. The domain doesn't change.

IPNS adds a layer of indirection. You update content by republishing the IPNS name instead of updating the website record.

Manage IPNS keys

List keys

pinner ipns keys list

const keys = await pinner.ipns.listKeys();
console.log(`You have ${keys.length} key(s)`);
for (const key of keys) {
  console.log(`- ${key.id}: ${key.ipns_name}`);
}

Create a key

pinner ipns keys create my-website-key

const key = await pinner.ipns.createKey({
  name: "my-website-key",
});
console.log("IPNS name:", key.ipns_name);

Delete a key

pinner ipns keys delete <key-name-or-id>

await pinner.ipns.deleteKey(keyId);

Publish content to an IPNS name

Point an IPNS name at a CID:

pinner ipns publish <cid> --key-name <key-name-or-id>

const result = await pinner.ipns.publish({
  key_id: key.id,
  cid: "QmYourCID",
});
console.log("Published:", result.name, "→", result.value);

Create a website with an IPNS target

const site = await pinner.websites.createWebsite({
  domain: "mysite.example.com",
  target_type: "ipns",
  target_hash: key.ipns_name,
});

Now when you update your site, publish a new CID to the same IPNS name; the domain follows automatically.

Republish

IPNS records have a limited lifetime. Republish to extend it:

pinner ipns republish <key-name-or-id>

await pinner.ipns.republish(key.ipns_name);

Resolve an IPNS name

Look up what CID an IPNS name currently points to:

pinner ipns resolve k51qzi5...

const resolved = await pinner.ipns.resolve("k51qzi5...");
console.log("Points to:", resolved.value);

When to use IPNS vs direct IPFS

IPNS resolution is slightly slower than direct IPFS because it adds a lookup step. For most sites, the difference is negligible.