Celaut Skill

SKILL.md

---
name: celaut-bridge-skill
version: 1.2.0
description: Bridge skill for the Celaut decentralised-compute network — install the Celaut node (nodo), package projects into content-addressed microVM services, execute and observe workloads, and discover on-chain "Unstoppable Skills" via the read-only MCP server (publishing is via the reputation-system TypeScript library).
author: Community Contribution
license: MIT
compatibility:
  # Verified against celaut-project/nodo `dev` @ 68a25ac9 (2026-07-31).
  # Tracks the nodo CLI surface on the `stable`/`dev` branches.
  nodo: ">=1 (stable/dev)"
system_requirements:
 apps:
 - curl
 - git
 - sudo
 - iptables
 - bc
 # node + npm: required only to run the Celaut Skills MCP server (§5).
 - node
 - npm
 # Note: docker and java are NOT host requirements. Nodo auto-provisions both
 # under MAIN_DIR (bash/install_docker.sh, bash/install_java.sh) and drives an
 # isolated Docker daemon; the host's Docker is never used.
---

# Celaut Bridge Skill

This skill (formatted according to the [agentskills.io](https://agentskills.io/)
specification) enables any AI agent to interface with the Celaut ecosystem. It
provides automated context to install the Celaut node (`nodo`), package project
services into reproducible **content-addressed** specifications, execute
deterministic decentralized workloads inside **microVMs**, and discover
**Unstoppable Skills** (Celaut Skills). The only agent-accessible read path to
Skills is the read-only **Model Context Protocol (MCP)** server; publishing is
done with the `reputation-system` TypeScript library (there is **no `nodo` CLI
for Skills**).

> **Verified against** celaut-project/nodo `dev` @ `68a25ac9` on 2026-07-31.
> This file lives in the repo it documents (`docs/skill/SKILL.md`) and links to
> its sibling docs by relative path, so a checkout is self-contained. The
> distributable hub bundle is generated by `build-hub-bundle.sh` (do not edit the
> generated `skill-hub/`).

> ⚠️ **Before you touch funds, wallets, or the chain, read this.** Nodo is
> **alpha** software (bugs and breaking changes are expected). All payments,
> service remunerations, and reputation submissions settle on the **Ergo**
> blockchain, and **every Ergo transaction is final and irreversible**. Users
> **self-custody** their keys: there is **no recourse, refund, or support** for
> lost assets, leaked mnemonics, or theft. Read the full
> [Know Your Assumptions](./KyA.md) before configuring a wallet or paying a peer.

## 0. Core Concepts (read first)

Understand these before running anything. Full glossary:
[`../CONCEPTS.md`](./CONCEPTS.md); the underlying paradigm is
[celaut-project/paradigm](https://github.com/celaut-project/paradigm).

* **Deterministic / content-addressed:** a service is a specification identified
  by the hash of its content (its **service id**). The same specification always
  has the same id; byte-identical rebuilds from source are not guaranteed.
  `.celaut.bee` is the importable package; a raw
  `.celaut` is for hash verification only.
* **microVM execution:** services **run** as isolated Cloud Hypervisor (`ch`)
  microVMs — never Docker containers. Docker, if used at all, only builds the
  filesystem during packing (§2).
* **Gas:** the compute unit clients pay for. A client tops up gas by generating a
  **deposit token** — a locally-generated identifier, not an on-chain asset — and
  submitting an Ergo transaction carrying that identifier plus ERG; the node
  verifies it and credits gas. Nodes run a single hot wallet
  (`ledgers.ergo.WALLET_MNEMONIC`); clients pay its derived P2PK address, and
  excess is swept to an optional cold address. See
  [`../ERGO.md`](./ERGO.md).
* **Ergo relationship:** Celaut is multi-ledger *by design*; Ergo is the ledger
  implemented today — "not necessarily the only ledger to be used"
  ([`../ERGO.md`](./ERGO.md)).
* **Peers:** nodes reciprocally offer and request services from each other, so a
  workload can run locally or on a peer.
* **Service composition:** a project can declare `dependencies` in
  `pack_config.json`; with `dependencies_env` the packer injects each resolved
  dependency's content hash into the build as an env var. See
  [`../PACKING.md`](./PACKING.md).

## 1. Celaut Node Installation & Management

The Celaut node (`nodo`) orchestrates service execution across decentralized peer
networks. **Supported platform:** Ubuntu 22.04 LTS (or a compatible Debian-based
distro) on **x86_64 or aarch64**. Installation root is `TARGET_DIR` (default
`/nodo`), where `config.yaml` and local runtimes live.

Before installing, check whether nodo is already present (see §6, rule 2):

```bash
command -v nodo
```

### Recommended Installation (Official Script)

Downloads and runs the automated installer. Requires `sudo` to configure system
routing (`iptables`) and the virtualization runtime:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/celaut-project/nodo/stable/install.sh | sudo bash
```

**Verify-first alternative (sanctioned).** If piping a remote script into `sudo
bash` is against your policy, download it, inspect it, then run it — this is an
approved path, not a deviation:

```bash
curl --proto '=https' --tlsv1.2 -sSf \
  https://raw.githubusercontent.com/celaut-project/nodo/stable/install.sh -o /tmp/nodo-install.sh
less /tmp/nodo-install.sh      # review before running
sudo bash /tmp/nodo-install.sh
```

### Alternative Installation (From Source & Development)

For a local source checkout (so code changes can be tested by restarting the
service). `$HOME/nodo` is a placeholder — use any path you control:

```bash
git clone https://github.com/celaut-project/nodo.git "$HOME/nodo"
cd "$HOME/nodo"
sudo ./install.sh --source-dir "$HOME/nodo"
```

To install from a specific branch (e.g. `dev`):

```bash
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/celaut-project/nodo/dev/install.sh | sudo bash -s -- --branch dev
```

For manual bootstrapping without `install.sh` (no-sudo path, exact package and
runtime steps), follow the **Manual Installation Guide**:
[`../INSTALL.md`](./INSTALL.md). To uninstall, see [`../UNINSTALL.md`](./UNINSTALL.md).

---

## 2. Packaging Celaut Services (.celaut)

To deploy a service you package a project into a deterministic Celaut service
specification with `nodo pack`. **Do not guess the input format — read
[`../PACKING.md`](./PACKING.md) before packing.** The essentials are below.

> **Note on Containerization (fixed per the two-backend reality):** Docker is used
> **only** for the packaging phase, never for execution — running services are
> Cloud Hypervisor microVMs (`ch`), so `docker ps` never shows a running instance.
> `nodo pack` has **two backends**, selected by `packer.local` in `config.yaml`:
> the **default** (`packer.local: false`) sends the project to an **external
> packer-service** that runs Docker/buildx inside its *own* sealed microVM — **no
> Docker is installed on your host**; the **opt-in** (`packer.local: true`) builds
> locally with nodo's **isolated** Docker toolchain, provisioned on demand. See
> §2 prerequisites and [`../INSTALL.md`](./INSTALL.md) step 9.

### Prerequisite: configure a packer backend (`config.yaml`)

`nodo pack` is **not** zero-config. `config.yaml` lives at `$TARGET_DIR/config.yaml`
(default `/nodo/config.yaml`). Pick one backend:

```yaml
# DEFAULT — delegate to an external packer-service (no local Docker).
# Set the packer's published service id under core_services (single source of truth):
core_services:
  - name: "packer"
    id: "<packer-service id>"
# …then run a packer instance so nodo can resolve its ip:port:  nodo execute <packer-service id>
```

```yaml
# OPT-IN — build locally with nodo's isolated Docker toolchain:
packer:
  local: true
```

Full key reference: [`../CONFIG.md`](./CONFIG.md).

### Packer Workflow

```bash
# Package a project directory into a Celaut service specification
nodo pack /path/to/project
```

**Minimal `service.json`** (in the project's `.service/` dir or its root). Only
`architecture` is strictly required; `init.entry_path` points at the in-image
executable:

```json
{
    "tag": "my-worker",
    "architecture": "linux/amd64",
    "init": { "entry_path": ["usr", "local", "bin", "worker"] }
}
```

**Dockerfile rule.** The Dockerfile only produces a **filesystem snapshot — the
container is never run** (the build is `docker buildx build --output type=tar`, a
filesystem export). `CMD`, `ENTRYPOINT`, and `EXPOSE` are simply **ignored** — no
error, nothing irreversible; the entrypoint comes from `service.json →
init.entry_path` and ports come from `service.json → api`. Make the
entrypoint executable in the image (e.g. `RUN chmod +x /usr/local/bin/worker`).
The full `service.json` / `pack_config.json` / Dockerfile spec — including
`resources`, `api`, `envs`, `config_declaration`, `network`, and dependencies — is
in [`../PACKING.md`](./PACKING.md).

### Importing, Exporting & Distribution

```bash
# Import a local package (.celaut.bee) into the node
nodo import /path/to/service.celaut.bee

# Export an installed service. Default → <service>.celaut.bee (importable/shareable).
nodo export <service id|tag> /export/dir
# --raw → a raw .celaut for HASH VERIFICATION ONLY (NOT importable):
nodo export <service id|tag> /export/dir --raw

# Publish a local service in chunks to the configured repository (see publisher.* in config)
nodo publish <service id|tag>

# Download a published service from a manifest URL and import it locally (the service id is recomputed from content on import)
nodo download <manifest url> [-o <output dir>]
```

### Feasibility & Cost Estimation

Before launching any workload, run `nodo estimate` to check the memory guard
(`resources.at_most.mem_limit`) and gas fees. It prints an execution-feasibility
verdict (`YES/NO`) and the estimated gas costs — it does not print a resource or
hardware-availability table:

```bash
nodo estimate ./my-service.celaut.bee    # a .celaut.bee path
nodo estimate 1234567890abcdef           # an installed service id
nodo estimate my_service_tag             # or a tag
```

---

## 3. Service Execution & Runtime Management

Celaut launches instances inside isolated microVMs (`ch`). A full worked path
(pack → estimate → execute → address+token → call → observe → kill) with example
output is in [`../WALKTHROUGH.md`](./WALKTHROUGH.md).

### Execution Lifecycle

1. **Inspection & Environment Declaration:**
 Before launching, inspect the service's architecture and declared environment
 variables. **The `-e` variables accepted at execution depend strictly on what
 the service declares** (see §6, rule 4).
 ```bash
 nodo inspect <service id|tag>
 ```

2. **Launching Instances (`nodo execute`):**
 Execute by service id, tag, or a `.celaut.bee` path (the path form imports the
 package first, then executes it). Pass declared env vars with `-e <key> <value>`;
 use `--remote` to advertise the host-facing IP.
 ```bash
 nodo execute 1234567890abcdef
 nodo execute --remote -e workers 8 -e timeout 20 my_service_tag
 # signature: execute [--remote] [--name <instance-name>] [-e key value]... <service id | tag | '.celaut.bee' path>
 ```
 `execute` launches the instance; read its id (which is also its token) and API
 address from `nodo instances` — `execute` itself prints the `nodo inspect` dump
 and the available `http` endpoints, not an id, token, or address (see
 [`../CONCEPTS.md`](./CONCEPTS.md)).

3. **Observation, Monitoring & Gas Control:**
 ```bash
 # Live CPU/memory + a live per-flow network view for one instance (Ctrl-C to exit).
 # --save writes metrics.jsonl and a Wireshark-openable capture.pcap.
 nodo observe <instance id> [--save <path>]

 # List active instances (shows id, name, API address, gas, and virtualizer — the standard is `ch`).
 nodo instances
 nodo instances --grouped        # grouped by parent service

 # Adjust gas for a running workload
 nodo increase_gas <instance id> 100
 nodo decrease_gas <instance id> 50

 # Stop a running instance (requires root)
 sudo nodo kill <instance id>

 # Remove a service specification from the local registry (requires root)
 sudo nodo remove <service id|tag>
 ```

---

## 4. Unstoppable Skills (Celaut Skills) & MCP Integration

While the [agentskills.io](https://agentskills.io/) specification defines the
structure of *this* bridge skill file (`SKILL.md`), **Unstoppable Skills** (Celaut
Skills) are the decentralized, on-chain "problem store" for AI agents on the
Celaut + Ergo ecosystem.

### Philosophy: Searching for Problems, Not Servers

In traditional architectures, agents look for centralized MCP servers or specific
endpoints. In Celaut, **agents search for problems (Skills)** (e.g., `"Optimal
XAU/BTC Performance"`, `"Sat-sorter"`). Each on-chain Skill entity automatically
bundles:
* **Coverage:** Verifiable Celaut services that solve the problem (`celaut:coverage:v1`).
* **Benchmarks:** Deterministic specifications on how to measure performance (`celaut:benchmark:v1`).
* **Results:** Immutable comparative performance metrics submitted against benchmarks (`celaut:result:v1`).
* **Community Forum:** On-chain discussions and skin-in-the-game reputation validation.

### The two interface surfaces (there is no Skills CLI)

* **Read (agent-accessible):** the official **read-only MCP server**. This is the
  **only** way an agent reads the Skills registry. It does not mutate chain state,
  so it is safe to wire into any MCP client. Under the hood the server queries the
  Ergo **explorer API** (`CELAUT_EXPLORER_API`, default
  `https://api.ergoplatform.com`) — the agent never reads the chain directly.
* **Publish (not agent-facing):** creating Skill/Coverage/Benchmark/Result
  entities is done with the **`reputation-system` TypeScript library**
  (`createReputationBox({...})`), from an app with a connected wallet. There is
  **no `nodo` CLI** and no MCP tool for publishing (`createSkill` etc. are
  explicitly *not* exposed by the server).

### Registering & Running the MCP Server

Requires `node` + `npm`. Clone and start the server (stdio transport):

```bash
git clone https://github.com/celaut-project/skills.git
cd skills
npm install
npm run mcp
# equivalently, run the server binary directly over stdio:
node mcp/server.mjs
```

Register it with an MCP client. For Claude / the `claude` CLI:

```bash
claude mcp add celaut-skills -- node /absolute/path/to/skills/mcp/server.mjs
```

Or add it to any client's `mcpServers` config (set `CELAUT_EXPLORER_API` only to
override the default explorer):

```json
{
  "mcpServers": {
    "celaut-skills": {
      "command": "node",
      "args": ["/absolute/path/to/skills/mcp/server.mjs"],
      "env": { "CELAUT_EXPLORER_API": "https://api.ergoplatform.com" }
    }
  }
}
```

### Available MCP Tools (and the required call order)

**Start with `load_skills` — it is the only tool that takes no arguments.** The
other four need a `skillBoxId` (or a `benchmarkId`) that you can only obtain from
`load_skills` first. Typical flow: `load_skills` → pick a `boxId` →
`load_skill_tree` (or the individual `load_*` tools).

| Tool | Args | Returns (shape) |
|---|---|---|
| `load_skills` | *none* | `[{ boxId, profileId, name, prose, formal, tags[], domain, extendedSkillBoxIds[], sourceHash? }]` |
| `load_coverages` | `{ skillBoxId }` | `[{ boxId, profileId, serviceId? }]` (direct + indirect, deduped by serviceId) |
| `load_benchmarks` | `{ skillBoxId }` | `[{ id, profileId, skillBoxId, name, description, caseDescriptors[], performanceMetrics[], sourceHash? }]` |
| `load_results` | `{ benchmarkId }` | `[{ id, profileId, benchmarkId, serviceId, data[], notes, timestamp, sourceHash? }]` |
| `load_skill_tree` | `{ skillBoxId }` | `{ skill, coverages[], benchmarks: (Benchmark & { results: Result[] })[] }` |

> Note: the registry's Type NFT ids are placeholders until real Type NFTs are
> minted, so these queries may currently return empty arrays.

Reference: [Celaut Skills README](https://github.com/celaut-project/skills/blob/main/README.md)
and [MCP specification](https://github.com/celaut-project/skills/blob/main/MCP.md).

---

## 5. Node Administration & Diagnostics

### Daemon Management (`systemd`)
When installed with superuser privileges, Nodo runs as a background service
(`nodo.service`).
```bash
sudo nodo daemon status
sudo nodo daemon start | stop | restart

# Comprehensive diagnostics (virtualization flags, KVM access, guest kernel, CH smoke test).
# Run this FIRST when execution fails — see ../TROUBLESHOOTING.md.
sudo nodo doctor

sudo nodo update
```

### Basic Node Utilities
* `nodo services`: Lists all registered service packages on the local node.
* `nodo integrity [<service id|tag>] [--fix]`: Verifies registry/metadata integrity (optionally for one service) and repairs with `--fix`.
* `nodo tag <service id|tag> <new tag>`: Assigns/updates a human-readable tag.
* `nodo peers` / `nodo clients`: Displays connected peer nodes and clients.
* `nodo connect <ip:port>`: Manually connects to a peer node.
* `nodo config`: Opens the runtime configuration ([`../CONFIG.md`](./CONFIG.md)).
* `nodo info`: Shows runtime versions, node address, and identity.
* `nodo logs`: Streams the application daemon logs.

> **Scope note.** This skill documents the commands an agent needs to install,
> pack, distribute, execute, observe, and discover. Node-operator / maintenance
> and development commands (`serve`, `tui`, `migrate`, `storage:prune_blocks`,
> `prune_containers`, `submit_reputation`, `sync_reputation_proof`,
> `refresh_ergo_nodes`, `refresh_clients`, `tx_history`, `increase_peer_deposit`,
> `disconnect`, `envs`, `test`, `ggconf`, `pay`, `verify_reputation`,
> `local_docker_packer`, `completion`) are intentionally out of scope here. Note
> that [`../USAGE.md`](./USAGE.md) does not document these either; consult
> `nodo --help` for the development-command surface.

---

## 6. Agent Instructions & Rules

1. **Terminal-First CLI Execution:** Execute all interactions with Celaut via standard bash terminal commands.
2. **Idempotency Setup Check:** Prior to executing installation scripts, run `command -v nodo` to verify if the node binary is already available in PATH.
3. **Sudo Privileges Handling:** Automated installation, system daemon management (`daemon`, `doctor`, `update`), and instance/service teardown (`kill`, `remove`) require root elevation. Ensure non-interactive execution (`sudo -n true`) is permitted or handle prompt elevation safely.
4. **Strict Environment Variable Declaration:** When preparing `nodo execute -e <key> <value>`, **never guess environment variables**. Always run `nodo inspect <service>` first to determine the exact environment variables declared and supported by the service package.
5. **MicroVM Execution Awareness:** Understand that services execute inside isolated microVMs (`ch`). Do not attempt to use Docker commands to inspect running service instances; Docker is used only for the `nodo pack` build phase (and only locally in the opt-in `packer.local` mode) — never for execution.
6. **Pre-flight Estimation:** Always run `nodo estimate <service>` before deploying unknown workloads to verify memory guard limits (`resources.at_most.mem_limit`) and ensure sufficient gas availability.
7. **Problem-First Discovery:** When seeking AI capabilities, query Unstoppable Skills **through the read-only MCP server** (start with `load_skills`, then `load_skill_tree`) to evaluate comparative `Results` and verifiable `Coverage` before selecting a service id. There is no `nodo` CLI for Skills; publishing (if ever needed) uses the `reputation-system` library, not this agent path.
8. **Disclose Irreversibility Before Funds:** Before any operation that configures a wallet, spends ERG, pays a peer, or submits reputation, disclose to the user that Nodo is **alpha** and that Ergo payments are **final and irreversible** with self-custodied keys and no recourse (see [`../KyA.md`](./KyA.md)). Do not initiate on-chain spending without explicit user consent.

---

## 7. References & Ecosystem Links

In-repo siblings (offline-safe; pulled by imperatives above at the point of need):

* Concepts & glossary → [`../CONCEPTS.md`](./CONCEPTS.md)
* Manual install / uninstall → [`../INSTALL.md`](./INSTALL.md) · [`../UNINSTALL.md`](./UNINSTALL.md)
* Command reference → [`../USAGE.md`](./USAGE.md)
* Packing input format → [`../PACKING.md`](./PACKING.md)
* Configuration reference → [`../CONFIG.md`](./CONFIG.md)
* End-to-end walkthrough → [`../WALKTHROUGH.md`](./WALKTHROUGH.md)
* Troubleshooting → [`../TROUBLESHOOTING.md`](./TROUBLESHOOTING.md)
* Know Your Assumptions (risk) → [`../KyA.md`](./KyA.md)
* Ergo payment/reputation model → [`../ERGO.md`](./ERGO.md)

Provenance & upstream (web links = provenance only, never on the critical path):

* Nodo repository → [github.com/celaut-project/nodo](https://github.com/celaut-project/nodo)
* Celaut paradigm (conceptual source of truth) → [github.com/celaut-project/paradigm](https://github.com/celaut-project/paradigm)
* Unstoppable Skills registry & MCP → [github.com/celaut-project/skills](https://github.com/celaut-project/skills)
* Agent Skills format → [agentskills.io](https://agentskills.io/)