Buckets

ICBucket

ICPay Cloud guide

On-chain encrypted file storage

New bucketPricingGitLab
HomeIntroductionQuick StartInstallationConfigurationAuthenticationBasic UsageBest PracticesAPI OverviewAPI EndpointsAPI RequestsAPI ResponsesError CodesError HandlingTroubleshootingLocal DevelopmentProduction DeploymentConfiguration ReferenceTypes ReferenceChangelogFrequently Asked Questions
ICBucket

On-chain encrypted file storage

Overview

IntroductionQuick StartInstallation

Guides

ConfigurationAuthenticationBasic UsageBest Practices

API Reference

API OverviewAPI EndpointsAPI RequestsAPI Responses

Errors

Error CodesError HandlingTroubleshooting

Deployment

Local DevelopmentProduction Deployment

Reference

Configuration ReferenceTypes ReferenceChangelog

FAQ

Frequently Asked Questions
ICPay

© 2026 ICPay. All rights reserved.

contact@icpay.cloud

Products

  • ICFalcon
  • ICBucket
  • Canisters
  • Top up cycles
  • ICPay Wallet

Explore

  • Channels
  • Blog

Resources

  • Falcon CLI
  • ICP-Hub Packages
  • ICBucket Docs
  • Blog

Company

  • Charity
  • About
  • FAQ
  • Roadmap

Legal

  • Brands
  • Terms
  • Privacy
  • Transparency

Community

  • GitLab
  • X
  • LinkedIn
  • Discord
  • Support
ICPayICPay
  • Blog
Buckets

ICBucket

ICPay Cloud guide

On-chain encrypted file storage

New bucketPricingGitLab
HomeIntroductionQuick StartInstallationConfigurationAuthenticationBasic UsageBest PracticesAPI OverviewAPI EndpointsAPI RequestsAPI ResponsesError CodesError HandlingTroubleshootingLocal DevelopmentProduction DeploymentConfiguration ReferenceTypes ReferenceChangelogFrequently Asked Questions
ICBucket

On-chain encrypted file storage

Overview

IntroductionQuick StartInstallation

Guides

ConfigurationAuthenticationBasic UsageBest Practices

API Reference

API OverviewAPI EndpointsAPI RequestsAPI Responses

Errors

Error CodesError HandlingTroubleshooting

Deployment

Local DevelopmentProduction Deployment

Reference

Configuration ReferenceTypes ReferenceChangelog

FAQ

Frequently Asked Questions

Deployment

Local Development

Run and test ICBucket integrations locally using dfx replica simulation and mock storage actors.

Local Development

Test your ICBucket storage integrations in local development environments without spending real ICP or burning mainnet cycles.

Prerequisites

  • DFINITY SDK (dfx) installed on macOS / Linux / WSL.
  • Local replica running via dfx start --background.

Steps

1. Point the SDK to Local Replica

Set the environment variables to point to your local replica:

NEXT_PUBLIC_IC_HOST=http://127.0.0.1:4943
ICBUCKET_CANISTER_ID=bkyz2-fmaaa-aaaaa-qaaaq-cai
ICBUCKET_CDN_BASE=http://localhost:3000

2. Fetch Root Key in Development

When communicating with local replicas, instruct @dfinity/agent to fetch the root key:

import { HttpAgent } from "@dfinity/agent"

const agent = new HttpAgent({ host: "http://127.0.0.1:4943" })
if (process.env.NODE_ENV !== "production") {
  await agent.fetchRootKey()
}

Verification

Upload a test text file and inspect local canister state:

dfx canister call icbucket listFiles '(record { page = 1; pageSize = 10 })'

Related Pages

  • Production Deployment
  • Configuration Reference
  • Troubleshooting
PreviousTroubleshootingNextProduction Deployment

On this page

PrerequisitesSteps1. Point the SDK to Local Replica2. Fetch Root Key in DevelopmentVerificationRelated Pages
HomeIntroductionQuick StartInstallationConfigurationAuthenticationBasic UsageBest PracticesAPI OverviewAPI EndpointsAPI RequestsAPI ResponsesError CodesError HandlingTroubleshootingLocal DevelopmentProduction DeploymentConfiguration ReferenceTypes ReferenceChangelogFrequently Asked Questions
HomeIntroductionQuick StartInstallationConfigurationAuthenticationBasic UsageBest PracticesAPI OverviewAPI EndpointsAPI RequestsAPI ResponsesError CodesError HandlingTroubleshootingLocal DevelopmentProduction DeploymentConfiguration ReferenceTypes ReferenceChangelogFrequently Asked Questions
ICBucket

On-chain encrypted file storage

Overview

IntroductionQuick StartInstallation

Guides

ConfigurationAuthenticationBasic UsageBest Practices

API Reference

API OverviewAPI EndpointsAPI RequestsAPI Responses

Errors

Error CodesError HandlingTroubleshooting

Deployment

Local DevelopmentProduction Deployment

Reference

Configuration ReferenceTypes ReferenceChangelog

FAQ

Frequently Asked Questions