ic-basilisk-toolkit 0.2.0

Basilisk Toolkit — Services, shell, and SFTP for IC Python canisters

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 Management	Create, schedule, and run background tasks
%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	ICRC-1 token registry, transfers, balance tracking
%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)
Encryption	vetKeys + per-principal envelopes + groups
%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	Exchange rate queries via the IC XRC canister
%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
Entities	Persistent ORM via ic-python-db
%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") u.save() User.load(1) User.instances() User.count()
Logging	Structured logging via ic-python-logging
from ic_python_logging import get_logger logger = get_logger("my_module") logger.info("processing") logger.error("failed", exc_info=True)
HTTP Fetch	Download a URL into the canister filesystem
%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
File Transfer	Move files between local machine and canister
%put local_script.py /app/script.py %get /app/output.json result.json
Interactive Shell	REPL for live canister interaction
basilisk-toolkit shell --canister my_app --network ic basilisk-toolkit exec --canister my_app 'print(ic.time())'
SFTP	Browse and edit canister filesystem over SSH
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

Data Browsing (read-only)

Canisters with __basilisk_features__ = ["browse"] expose a __browse__ query endpoint for instant, free, read-only data access:

from ic_basilisk_toolkit.shell import canister_browse, canister_schema, canister_keys, canister_get

# Get the canister's data schema
schema = canister_schema("my_canister", network="ic")

# List keys in a stable map (paginated)
keys = canister_keys("my_canister", "users", network="ic")

# Read a single value
value = canister_get("my_canister", "users", "alice", network="ic")

# Generic browse with any action
result = canister_browse("items", "my_canister", network="ic", map="users", limit=50)

Unlike __shell__ (which is an @update call requiring consensus and controller access), __browse__ is a @query — instant response, no cycles cost, and public by default.

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

License

MIT — see LICENSE.