ic-basilisk-toolkit

Basilisk Toolkit — A set of ready-made tools on top of Basilisk CDK for IC Python canisters.

Live demo: https://ic-basilisk.tech/.

Overview

%task create heartbeat every 60s --code "print('alive')"
%task start 1
%task info 1
%task list

t = Task(name="sync")
TaskStep(task=t, code="print('syncing...')")
TaskSchedule(task=t, interval=60)
TaskManager().run()

%wallet balance
%wallet transfer ckBTC <principal> 1000

w = Wallet()
w.register_token("ckBTC", ledger="mxzaz-...", indexer="n5wcd-...")
yield from w.balance_of("ckBTC")
yield from w.transfer("ckBTC", to_principal, amount=1000)
yield from w.refresh("ckBTC", max_results=50)
w.list_transfers("ckBTC", limit=20)

%crypto encrypt "secret"
%group create team1
%group add team1 <principal>

cs = CryptoService(vetkey_service)
yield from cs.init_scope("my-scope")
cs.grant_access("my-scope", target_principal)
cs.create_group("team")
cs.add_member("team", principal)
cs.grant_group_access("my-scope", "team")
cs.revoke_access("my-scope", principal)

%fx ICP/USD

fx = FXService()
fx.register_pair("ICP", "USD")
yield from fx.refresh()         # fetch latest rates from XRC canister
fx.get_rate("ICP", "USD")       # cached float
fx.get_rate_info("ICP", "USD")  # full info with staleness metadata

%db types
%db list User 10
%db show User 1
%db search User name=alice
%db export User backup.json
%db import backup.json

u = User(name="alice")   # auto-persisted on creation
u.name = "bob"           # changes save automatically
bob = User['bob']
bob.friends

basilisk check-upgrade --canister my_app --network ic

from ic_python_logging import get_logger
logger = get_logger("my_module")
logger.info("processing")
logger.error("failed", exc_info=True)

%wget https://example.com/data.json /data.json

yield from wget("https://example.com/data.json", "/data.json")
run("/data.json")  # execute a downloaded Python script

%put local_script.py /app/script.py
%get /app/output.json result.json

basilisk-toolkit shell --canister my_app --network ic
basilisk-toolkit exec --canister my_app 'print(ic.time())'

basilisk-toolkit sshd --canister my_app --network ic
sftp -P 2222 localhost
ssh -p 2222 localhost

Type :help inside the shell for full command reference, or see the tip_jar template for a working example project.

Templates

Full-stack example canisters, each deployable as-is:

• Tip Jar — crypto donations in ckBTC / ckETH / ckUSDC / ICP with live exchange rates, encrypted messages, donor leaderboard. Live.
• File Registry — general-purpose on-chain file storage with HTTP serving, CORS, chunked upload for large WASMs, and per-namespace ACLs. Live.

Website

website/ is the static landing page at ic-basilisk.tech — it introduces basilisk and this toolkit and links out to the live template demos. Pure assets canister, no backend.

Installation

pip install ic-basilisk-toolkit

For shell/SFTP support (requires asyncssh):

pip install ic-basilisk-toolkit[shell]

CLI Usage

basilisk-toolkit exec 'print("hello")'                    # Execute code on canister
basilisk-toolkit shell --canister my_app --network ic      # Interactive shell
basilisk-toolkit sshd --canister my_app --network ic       # SSH/SFTP server

Schema Upgrade Checking & Data Browsing

See docs/SCHEMA_UPGRADE_CHECKING.md for the full guide on pre-deploy schema diffing, step-by-step migration examples, verbose mode, on-chain enforcement, and the read-only __browse__ query API.

Security note: The sshd command starts a local development proxy that accepts any password. It is intended for local use only — do not expose it on a public network without adding proper authentication.

Dependencies

• ic-basilisk — CDK (types, decorators, ic.* API)
• ic-python-db — Persistent entity ORM
• ic-python-logging — Structured logging

Disclaimer

This software is not production-ready. Do not deploy to mainnet or use with real assets or canister state you cannot afford to lose.

This software is in early development (alpha). It may contain bugs, breaking changes, and unknown security vulnerabilities. It has not undergone an independent security audit. Use at your own risk — see the Basilisk disclaimer for additional context.

• Not recommended for production deployments on the Internet Computer
• No guarantee of correctness, availability, or security
• APIs and behavior may change without notice

License

MIT — see LICENSE.