NanoCore

NanoCore is a powerful CLI tool designed to orchestrate and manage multiple NodeServers in a unified environment. It provides automatic port management, environment variable injection, and real-time server monitoring.

Features

• NodeServer Registration: Register NodeServers with automatic port assignment
• Dependency Management: Automatic installation of dependencies for registered NodeServers
• Environment Variables: Per-NodeServer environment variable management
• Auto-detection: Automatically detects and uses the correct start command
• Real-time Monitoring: Watches for configuration changes and manages server lifecycle
• Discovery WebSocket: Built-in WebSocket server for service discovery and real-time updates
• Asset Server: HTTP server for managing server assets and configurations

Installation

npm install -g nanocore

Configuration

Server Configuration

Each Volted nodeserver requires a nanoserver.json file in its root directory with the following structure:

{
  "serverDisplayName": "My NodeServer",
  "serverPackageId": "my-node-server",
  "language": "javascript",
  "domain": "my-domain"
}

Setup Scripts

NanoCore supports custom setup scripts for both Python and Node.js projects:

Python Projects

If a setup.py file is present in your project root, NanoCore will:

1. Create and activate a virtual environment
2. Install dependencies from requirements.txt (if present)
3. Run python setup.py install using the virtual environment

Node.js Projects

For Node.js projects, you can use the postinstall script in your package.json:

{
  "scripts": {
    "postinstall": "your-setup-commands"
  }
}

The postinstall script will be automatically executed after npm install during server registration.

Global Configuration

NanoCore uses a nanocore.config.json file to store server configurations. This file is automatically created and managed by NanoCore.

• Linux/macOS: ~/.config/nanocore/nanocore.config.json (or as specified by XDG_CONFIG_HOME)
• Windows: %APPDATA%\nanocore\nanocore.config.json

You can override the default location by setting the NANOCORE_CONFIG environment variable:

export NANOCORE_CONFIG=/path/to/custom/nanocore.config.json

Asset Server Configuration

The asset server can be configured using the following environment variables:

• ASSET_HTTP_PORT: Port for the asset server (default: 3001)
• ASSET_STORAGE_PATH: Path where assets are stored (default: ~/NanoCoreAssets)
• ASSET_API_TOKEN: Authentication token for asset server access (default: 'changeme')
• ASSET_HOST: Host for the asset server (default: 'localhost')

Asset Management API

All endpoints require an Authorization: Bearer <ASSET_API_TOKEN> header unless otherwise noted.

| Method & Path | Purpose | Notes / Body | |---------------|---------|--------------| | POST /assets | Upload a file asset. | Multipart form-data: file (required), type (image\|video\|audio\|file, default file), meta (JSON string) | | GET /assets/:uuid/presigned | Get a short-lived download URL for an asset. | Returns { url, expiresIn } | | GET /assets/:uuid/download | Download an asset. | Works with token query param (from presigned URL) or auth header | | GET /assets/:uuid/meta | Fetch metadata for one asset. | Returns the full AssetMeta object | | GET /assets | List assets. | Query params: type, hash | | DELETE /assets/:uuid | Delete an asset. | Returns { success: true, uuid } |

Dependency Management API (models/assets)

All endpoints require an Authorization: Bearer <ASSET_API_TOKEN> header.

| Method & Path | Purpose | Params / Body | |---------------|---------|---------------| | GET /nodeservers/:serverDisplayName/dependencies | List declared dependencies for the given NodeServer and indicate whether each one is already installed. | URL param serverDisplayName | | POST /nodeservers/:serverDisplayName/dependencies | Install (download) a missing dependency. | JSON body: { "filename": "my.ckpt" } or { "hash": "sha256:..." } | | DELETE /nodeservers/:serverDisplayName/dependencies | Remove an installed dependency. | Query string: filename=<name> or hash=<sha256> |

Each dependency object returned by the GET route has the shape:

{
  "serverDisplayName": "My NodeServer",
  "filename": "model.ckpt",
  "hash": "sha256:...",
  "type": "checkpoint",
  "providers": [ { "type": "ipfs", "cid": "..." } ],
  "installed": true
}

installed indicates if the file exists locally (checked via hash).

NodeServer Management API

| Method & Path | Purpose | Body | |---------------|---------|------| | POST /nodeservers | Clone a GitHub repository and register it as a NodeServer (same logic as nanocore add). | { "repository": "username/repo" } |

Commands

Register a NodeServer

Register a new NodeServer with automatic port assignment and dependency installation:

nanocore register [serverPath]

If no path is provided, the current directory will be used. The command will read the nanoserver.json file from the specified path for configuration.

Start All Servers

Start all registered NodeServers:

nanocore start

This command will:

1. Start all registered servers
2. Assign ports automatically
3. Inject environment variables
4. Watch for configuration changes
5. Start the discovery WebSocket server for service discovery
6. Handle graceful shutdown with Ctrl+C

List Registered Servers

Display all registered NodeServers and their configurations:

nanocore list

Install Dependencies for a Server

Install Node dependencies for a server directory (defaults to the current directory if omitted):

nanocore install [path]

The command checks for a package.json and runs npm install.

Add a Server from GitHub

Clone, register, and install dependencies for a NodeServer hosted on GitHub in one step:

nanocore add <githubUser/repository>

Example:

nanocore add voltedai/nano-fal

Set Environment Variables

Set environment variables for a specific NodeServer by display name or package id (stored in nanoserver.json):

nanocore env <server> <key> <value>

• <server> can be either the server's display name or its package id
• <key> is the environment variable name
• <value> is the value to store in nanocore.config.json

Example:

nanocore env nano-fal-ai FAL_KEY your-secret-token

Unregister a Server

Remove a server from NanoCore management:

nanocore unregister [serverPath]

If no path is provided, the current directory will be used. The command will remove the server configuration associated with the specified path.

Port Management

• Base port: 24000
• Ports are automatically assigned incrementally
• Each NodeServer gets a unique port
• Ports are persisted in the configuration

Environment Variables

Each NodeServer can have its own set of environment variables:

• Automatically injected at startup
• Persisted in the configuration
• Can be modified at runtime
• Default variables:
  • PORT: Assigned port number
  • PYTHON_ENV: Set to 'development' by default
  • DOMAIN: Shared human-readable domain generated by NanoCore
  • SERVER_UID: Unique identifier of the NodeServer
  • NANOCORE_HTTP_ENDPOINT: Asset server endpoint
  • NANOCORE_TOKEN: Asset server authentication token

Development

Project Structure

nanocore/
├── src/
│   ├── ws/             # Discovery WebSocket server implementation
├── src/
│   ├── assets/          # Asset server implementation
│   ├── commands/        # CLI commands
│   ├── lib/            # Shared utilities
│   └── config.ts       # Configuration management
├── package.json
└── tsconfig.json

Building

npm run build

Development Mode

npm run dev

Generate Protocol Buffers

npm run proto

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT