Orbital Orbkit

Orbkit is the local runtime that connects your CKB smart contract workspace to the Orbital platform. It acts as the bridge between the Orbital web frontend and your local machine, handling devnet management, contract preflight checks, contract building, deployment preparation, wallet funding, and project structure synchronization.

Instead of running complex CLI commands manually, you start Orbkit once, and the Orbital frontend sends commands to it in real time.

Prerequisites

Before installing Orbkit, ensure you have the following installed on your system:

• Node.js v20.19 or higher
• Rust toolchain (cargo, rustc)
• RISC-V target for CKB contracts:

  rustup target add riscv64imac-unknown-none-elf

• clang/LLVM (clang, llvm-ar) for CKB contract builds
• CKB CLI / OffCKB for local devnet flows. Orbkit can resolve local workspace OffCKB installs when available.

Installation & Initialization

You can install Orbkit globally or use it via npx.

Global install:

npm install -g orbkit

Initialize a new project:

npx orbkit init my-project
cd my-project
npm install

The compatibility binary also supports orbital init my-project after a global install.

This generates a complete workspace containing your Rust contract source code, an orbkit/ runtime directory, and a preconfigured .env file.

Configuration

Orbkit uses the local Orbital backend by default at http://127.0.0.1:4000/graphql. Use npx orbkit start --profile prod or npm run orbkit:prod when you want to connect to the hosted Orbital backend.

Quickstart

Generated workspaces include a local development API key. If your backend requires a custom helper key, set:

ORBKIT_API_KEY=<your-helper-api-key-or-internal-orbkit-key>

The ORBKIT_API_KEY authenticates your local runtime with the backend. You can generate this key in the Orbital frontend settings or find it in your backend environment variables.

Starting the Runtime

Once configured, check the local build environment, prepare devnet, and start Orbkit:

npx orbkit preflight
npx orbkit setup
npx orbkit start

Generated workspaces also include npm run dev, npm run preflight, and npm run orbkit aliases for the same local setup/runtime workflow.

When started, Orbkit will:

1. Generate a unique service ID, such as orbkit-4aa2cbce.
2. Connect to your configured backend by WebSocket for local mode or HTTP polling for hosted mode.
3. Run local preflight checks before workers register.
4. Register workspace capabilities for preflight, build, test, reproduce, deploy, fund, balance, and structure sync.
5. Publish workspace metadata from orbkit/orbital.config.js, including the resolved config path and contract paths, so the frontend does not need to guess local directories.
6. Listen for incoming commands from the Orbital frontend.

How It Works

You do not need to run build or deploy commands in your terminal. Orbkit listens to the Orbital frontend.

1. Project structure sync: When you open your project in the Orbital UI, the frontend asks the backend for your file tree. Orbkit reads your local contract/ directory and sends the structure to the UI.
2. Funding: If you need testnet/devnet CKB, click "Fund" in the UI. The backend tells Orbkit, which uses the local devnet funder to send CKB to your wallet.
3. Building: Click "Build" in the UI. Orbkit runs preflight, compiles your Rust contracts to the riscv64imac-unknown-none-elf target, and streams the build logs back to the frontend.
4. Deploying: Click "Deploy" in the UI. Orbkit runs preflight, prepares the deployment transaction from the contract metadata it registered, and broadcasts supported non-mainnet deployments after signing is complete.

Mainnet Deployment Safety

Mainnet single-key deploy/broadcast is intentionally disabled. A future mainnet path should use multisig deployment with explicit signature collection, permission boundaries, and final deployment confirmation. Until then, use mainnet build, reproduce, estimate, and bundle export for planning and review.

Portable Project Bundles

Export, verify, and extract deterministic Orbital project bundles:

npx orbkit export contract/my-project --network devnet --out ./my-project.orb
npx orbkit verify ./my-project.orb
npx orbkit extract ./my-project.orb --dir ./restored-project

Troubleshooting

Missing Rust Target

If builds fail with a target not found error, ensure you have added the RISC-V target:

rustup target add riscv64imac-unknown-none-elf

Preflight And WSL

Orbkit preflight checks Cargo, rustup, the CKB RISC-V target, clang/LLVM, npx, and the optional OffCKB CLI. On Windows, use explicit WSL preflight when your contract build tools are installed inside WSL:

$env:ORBKIT_PREFLIGHT_BUILD_ENV="wsl"
npx orbkit preflight

Use ORBKIT_PREFLIGHT_BUILD_ENV=host or leave it unset when your Rust, RISC-V target, clang/LLVM, and Node tooling are installed on the Windows host.

Runtime Shutdown

Press Ctrl+C once to ask Orbkit to stop workers, unregister services, and close subscriptions. Press Ctrl+C again to force exit. If shutdown cleanup hangs, Orbkit forces exit after ORBKIT_SHUTDOWN_TIMEOUT_MS milliseconds; the default is 8000.

Connection / API Key Errors

If Orbkit starts but the frontend says "Disconnected" or "Offline":

• Verify your ORBKIT_API_KEY exactly matches the key configured in your frontend/backend.
• Check your terminal logs for HTTP 401 Unauthorized or 404 Not Found errors during the registration step.
• Restart the Orbkit instance and refresh your dashboard.

Devnet Not Starting

If devnet:setup or funding fails, Orbkit relies on @offckb/cli. Ensure you have no conflicting local CKB nodes running on the default ports, usually 8114 for RPC and 8116 for Indexer.