Documentation

Build with confidence.

Everything you need to integrate, extend, and ship on KuberNodes. REST API, SDKs, CLI, and comprehensive guides.

Quick Start

From signup to deployed contract in 5 minutes.

Create an account

Create a project

Choose a chain (Ethereum, Solana, Polygon, etc.) and template.

POST /api/v1/projects
{
  "name": "my-dapp",
  "chain": "ethereum",
  "template": "hardhat-typescript"
}

Launch a workspace

Browser IDE opens with dependencies pre-installed.

POST /api/v1/workspaces
{
  "projectId": "proj_abc123",
  "size": "standard"
}

Use the AI assistant

Ask the AI to write, audit, or test your contracts.

POST /api/v1/ai/command
{
  "action": "Write an ERC-20 token with
             pausable and burnable extensions",
  "context": { "workspaceId": "ws_xyz" }
}

Deploy

Deploy to testnet or mainnet with a single command.

POST /api/v1/deployments
{
  "projectId": "proj_abc123",
  "chain": "ethereum",
  "network": "sepolia",
  "contract": "MyToken"
}

Reference

SDK & CLI

Portability

Export Bundles
Download code, configs, and deployment scripts.
CI/CD Integration
GitHub Actions, GitLab CI, and custom pipelines.
Migration Guide
Moving to or from KuberNodes.

Getting Started

Quick Start Guide

Get from zero to your first deployment in under 5 minutes. KuberNodes provides a complete cloud environment — no local tooling required.

1. Sign up at app.kubernodes.com/signup — GitHub OAuth or email.

2. Create a project — pick a chain and template (Hardhat, Foundry, Anchor, etc.).

3. Launch a workspace — browser IDE opens with all dependencies pre-installed.

4. Write or generate code — use the AI assistant to scaffold contracts.

5. Deploy — one-click to testnet or mainnet with automatic verification.

Platform Overview

KuberNodes is an AI-native Web3 development cloud. The architecture consists of:

•API Gateway — Central authentication, rate limiting, and request routing.
•Control Plane — Orchestrates workspaces, manages quotas, and enforces RBAC.
•Workspace Service — Provisions isolated cloud IDEs with pre-configured toolchains.
•AI Engine — Multi-model routing with suggest → approve → execute pipeline.
•Deploy Service — Multi-chain deployment with automatic contract verification.
•Analytics — Real-time usage tracking, cost attribution, and audit logging.

Templates & Chains

Pre-configured project templates with optimized toolchains:

Ethereum

Hardhat TypeScript, Foundry, OpenZeppelin Wizard

Solana

Anchor, Seahorse, Native Rust

Polygon

Hardhat + Polygon Bridge, zkEVM Starter

Avalanche

Hardhat + Subnet, Teleporter Cross-Chain

Arbitrum

Stylus Rust, Hardhat L2 Starter

Base

Hardhat + Base Bridge, OnchainKit Starter

API Reference

Authentication

JWT-based authentication with short-lived access tokens (15 min) and long-lived refresh tokens (7 days). API keys provide an alternative for CI/CD workflows.

POST /api/v1/auth/login        → { accessToken, refreshToken }
POST /api/v1/auth/refresh      → { accessToken }
POST /api/v1/auth/logout       → 204 (revokes refresh token)
POST /api/v1/auth/api-keys     → { key: "kn_live_..." }
DELETE /api/v1/auth/api-keys/:id → 204

Projects

Projects are the top-level organizational unit. Each project targets a specific blockchain and contains workspaces, deployments, and AI context.

GET    /api/v1/projects            → List all projects
POST   /api/v1/projects            → Create project { name, chain, template }
GET    /api/v1/projects/:id        → Project details
PATCH  /api/v1/projects/:id        → Update project settings
DELETE /api/v1/projects/:id        → Archive project

Workspaces

Cloud workspaces are isolated development environments with browser-based IDE, terminal, and pre-installed chain toolchains.

POST   /api/v1/workspaces          → Launch { projectId, size }
GET    /api/v1/workspaces/:id      → Status, URL, resource usage
POST   /api/v1/workspaces/:id/stop → Pause workspace (preserves state)
DELETE /api/v1/workspaces/:id      → Terminate and clean up

AI Commands

The AI engine processes natural-language commands through a suggest → approve → execute pipeline. All file modifications require explicit user approval.

POST /api/v1/ai/command              → Submit command { action, context }
GET  /api/v1/ai/actions/:id          → Action status and suggested changes
POST /api/v1/ai/actions/:id/approve  → Approve and execute
POST /api/v1/ai/actions/:id/reject   → Reject suggestion
GET  /api/v1/ai/tokens               → Token usage and remaining quota

Deployments

Deploy compiled contracts to any supported chain and network. Automatic ABI extraction, constructor argument encoding, and block explorer verification.

POST /api/v1/deployments         → Deploy { projectId, chain, network, contract }
GET  /api/v1/deployments/:id     → Status, tx hash, address, verification
GET  /api/v1/deployments         → List deployments (filterable by project/chain)
POST /api/v1/deployments/:id/verify → Trigger source verification

Members & Roles

Organization-level member management with 5 built-in roles (owner, admin, developer, auditor, viewer) plus custom role support.

GET    /api/v1/org/members         → List members with roles
POST   /api/v1/org/members         → Invite member { email, role }
PATCH  /api/v1/org/members/:id     → Update role
DELETE /api/v1/org/members/:id     → Remove member
GET    /api/v1/org/roles           → List available roles and permissions

Analytics & Usage

Query compute usage, AI token consumption, deployment costs, and audit logs. All data is scoped to the authenticated user's organization.

GET /api/v1/analytics/usage      → CU usage, breakdown by project
GET /api/v1/analytics/costs      → Cost data, daily/monthly aggregates
GET /api/v1/analytics/ai         → AI token usage, model breakdown
GET /api/v1/audit/logs           → Audit trail (filterable by action, user, date)

AI Engine

AI Command Reference

Natural-language commands are classified and routed to specialized AI agents. Supported action categories:

Write Contract

Generate Solidity/Rust contracts from natural language specs.

Audit Code

Security analysis with vulnerability detection and fix suggestions.

Generate Tests

Create comprehensive test suites for existing contracts.

Explain Code

Line-by-line explanation of complex contract logic.

Optimize Gas

Analyze and suggest gas-optimization improvements.

Fix Bug

Debug failing tests or runtime errors with suggested patches.

Approval Pipeline

Every AI action follows the suggest → approve → execute pipeline:

1. Suggest

AI analyzes context and generates a proposed change with full diff preview.

2. Review

Developer reviews the diff, sees affected files, and reads the AI explanation.

3. Approve/Reject

Approve to apply changes to workspace, or reject to discard.

Agent Types

Specialized agents handle different categories of commands:

•ContractWriter — Generates Solidity, Vyper, or Anchor programs from specs.
•SecurityAuditor — Detects reentrancy, access control, and overflow vulnerabilities.
•TestGenerator — Creates Hardhat/Foundry test suites with edge-case coverage.
•GasOptimizer — Profiles gas usage and suggests storage/computation optimizations.
•CodeExplainer — Generates inline documentation and architectural overviews.

Model Routing

Commands are routed to the most appropriate model based on complexity:

Complexity	Model Tier	Use Cases
Low	Fast (GPT-4o-mini)	Code explanation, simple edits, formatting
Medium	Standard (GPT-4o)	Contract generation, test writing, bug fixes
High	Advanced (Claude Opus)	Security audits, complex refactors, architecture

Security & Compliance

Authentication Flow

Secure authentication with defense-in-depth:

•JWT access tokens (15 min TTL) with RS256 signatures.
•Refresh tokens (7 day TTL) stored in httpOnly cookies with rotation on each use.
•TOTP-based MFA with recovery codes.
•Session fingerprinting (IP + User-Agent) to detect token theft.
•Automatic lockout after 5 failed login attempts (15 min cooldown).

RBAC Model

Five built-in roles with granular permissions:

Role	Permissions
Owner	Full access, billing, delete org
Admin	Manage members, projects, settings
Developer	Create workspaces, deploy, use AI
Auditor	Read-only with audit log access
Viewer	Read-only dashboard access

Tenant Isolation

Each organization's data is fully isolated at the database level (row-level security), workspace level (separate containers with network policies), and AI context level (no cross-tenant prompt leakage). All inter-service communication uses mTLS with per-tenant encryption keys for data at rest.

Compliance

KuberNodes is designed for enterprise compliance: SOC 2 Type II audit trail with immutable event logs, GDPR data subject rights (export/delete), configurable data residency regions, and a comprehensive audit log capturing every authenticated API call with full request metadata.

SDK & CLI Reference

JavaScript SDK

import { KuberNodes } from '@kubernodes/sdk';

const kn = new KuberNodes({
  apiKey: 'kn_live_abc123...',
  // or: accessToken: 'eyJ...'
});

// List projects
const projects = await kn.projects.list();

// Create and launch workspace
const ws = await kn.workspaces.create({
  projectId: projects[0].id,
  size: 'standard'
});

// Send AI command
const action = await kn.ai.command({
  action: 'Write a pausable ERC20 token',
  context: { workspaceId: ws.id }
});

// Subscribe to real-time events
kn.events.on('deployment:status', (event) => {
  console.log(event.status); // 'deploying' | 'success' | 'failed'
});

CLI Reference

# Authenticate
kn login

# Project management
kn projects list
kn projects create --name my-dapp --chain ethereum --template hardhat-ts

# Workspace management
kn workspace launch --project my-dapp --size standard
kn workspace stop --id ws_abc123

# Deployments
kn deploy --project my-dapp --chain ethereum --network sepolia --contract MyToken
kn deploy status --id dep_xyz

# AI commands
kn ai "Write an ERC-721 with royalties" --project my-dapp
kn ai approve --action act_123

Webhooks

Subscribe to platform events via HTTPS webhooks. Each webhook delivery includes an HMAC-SHA256 signature header for verification.

// Webhook events:
deployment.created    // New deployment initiated
deployment.succeeded  // Contract deployed and verified
deployment.failed     // Deployment failed
workspace.started     // Workspace is ready
workspace.stopped     // Workspace paused or terminated
ai.action.completed   // AI action finished processing
member.invited        // New member invited to org

Portability

Export Bundles

Download everything you need to run your project independently:

•Full source code with all dependencies.
•Deployment scripts and contract ABIs.
•Environment configs (Hardhat/Foundry/Anchor).
•Docker Compose for local development environment.

# Export via CLI
kn export --project my-dapp --format zip
kn export --project my-dapp --format docker

CI/CD Integration

# GitHub Actions
- uses: kubernodes/deploy@v1
  with:
    api-key: ${{ secrets.KN_API_KEY }}
    project: my-dapp
    chain: ethereum
    network: sepolia

# GitLab CI
deploy:
  image: kubernodes/cli:latest
  script:
    - kn login --api-key $KN_API_KEY
    - kn deploy --project my-dapp --network sepolia

Migration Guide

Moving to KuberNodes from an existing setup:

•From Remix — Import .sol files directly. KuberNodes auto-detects Solidity version.
•From Hardhat — Drop in your hardhat.config.ts. All plugins are pre-installed.
•From Foundry — Import foundry.toml and src/ directory. Forge is pre-configured.
•Leaving KuberNodes — Export Bundle includes everything to run standalone.

API Endpoints

Base URL: https://api.kubernodes.com

Method	Endpoint	Description
POST	`/api/v1/auth/login`	Authenticate and receive JWT
POST	`/api/v1/auth/refresh`	Refresh access token
GET	`/api/v1/projects`	List all projects
POST	`/api/v1/projects`	Create a new project
POST	`/api/v1/workspaces`	Launch a workspace
DELETE	`/api/v1/workspaces/:id`	Stop and remove workspace
POST	`/api/v1/ai/command`	Send AI command
GET	`/api/v1/ai/actions/:id`	Check action status
POST	`/api/v1/ai/actions/:id/approve`	Approve AI action
POST	`/api/v1/deployments`	Deploy contract
GET	`/api/v1/deployments/:id`	Deployment status
GET	`/api/v1/analytics/usage`	Usage metrics

Authentication

JWT Bearer Token

All API requests require a Bearer token in the Authorization header. Tokens are short-lived (15 minutes) with refresh tokens for session continuity.

// Login to get tokens
const res = await fetch('https://api.kubernodes.com/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'dev@example.com',
    password: '...'
  })
});

const { accessToken, refreshToken } = await res.json();

// Use token for subsequent requests
const projects = await fetch('https://api.kubernodes.com/api/v1/projects', {
  headers: { Authorization: `Bearer ${accessToken}` }
});

API Keys

For CI/CD and programmatic access, generate API keys from the dashboard. Keys are scoped to specific projects and permissions.

// Using API key
const res = await fetch('https://api.kubernodes.com/api/v1/deployments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'kn_live_abc123...'
  },
  body: JSON.stringify({
    projectId: 'proj_abc123',
    chain: 'ethereum',
    network: 'sepolia',
    contract: 'MyToken'
  })
});

SDKs & CLI

JavaScript SDK

npm install @kubernodes/sdk

TypeScript-first SDK with full type coverage. Handles auth, retries, and WebSocket subscriptions automatically.

CLI

npm install -g @kubernodes/cli

Deploy from your terminal. Manage projects, workspaces, and deployments without leaving the command line.

GitHub Action

uses: kubernodes/deploy@v1

Integrate deployments into your CI/CD pipeline. Supports multi-chain deploys and automated verification.

Need help?

Join our developer community or reach out to support. We respond to questions within 24 hours.

Join Discord Start Building