IVY NODE
A capability you can read in one file
The contract, the code and the tests travel together, and the gate reads the contract.
An ivy-node is a small Python program wrapped in a declaration: what it takes, what it returns, what it touches and how risky that is. IVYX registers it as a capability, so a person, an agent and an MCP client all call it the same way, by id, through the same policy gate.
{
"apiVersion": "ivy.node/v0.2",
"kind": "IvyNode",
"capability": {
"id": "ivy.node.email-send",
"title": "Email Send",
"version": "0.1.0",
"inputs": {
"schema": {
"type": "object",
"required": ["smtp_host", "from_addr", "to", "subject", "body"],
"properties": { … }
}
},
"outputs": {
"schema": { "required": ["sent", "recipients", "subject"], … }
},
"policy": { "risk": "medium", "approval": "none" },
"sideEffects": ["network-request"]
},
"program": { "format": "cells", "language": "python", "cells": [ … ] },
"execution": { "timeoutMs": 120000 },
"tests": {
"requires": ["python:3.9"],
"cases": [{ "id": "relay" }, { "id": "no-recipient" }, { "id": "closed-port" }]
}
}The contract of ivy.node.email-send, as published. The Python and the tests follow it in the same file. See the whole node
Four parts, one file
The contract
The id, the version, an input and an output schema, a risk level, whether it asks for a person, and the side effects it declares. The input is checked against the schema before any code runs.
The program
Python, split into cells that run in order in one kernel session. The source is in the file and stays open in your workspace. The contract does not hide it.
The deadline
A timeout the node sets for itself, which the gateway applies to every call.
The tests
Cases with inputs and assertions, kept inline. A passing run writes a verification record next to the file, and publishing asks for that record.
Write it, or describe it
The same file, whichever way it starts, and the same steps after that.
01
Create or generate
Start from a skeleton, or describe the node in a sentence and let a model write the file. Generating calls a model and writes to disk, so it is a capability that policy can hold for a person.
02
Run
Run goes through the gateway under the node's own id, on your workspace's Python kernel. The result and the audit record arrive together.
03
Test
The inline cases run through the same gateway. A passing run records how many cases, when, and on which kernel.
04
Publish
Publishing sends the file and its record to the registry. It asks for a person every time, a version can be published once, and it cannot be withdrawn.
05
Reuse
In the Ivy Marketplace inside the app, Try copies a published node into your workspace as a file. From there it is yours to read and change.
06
Compose
A node is a step. An ivy-agent wires nodes together with model turns and branches, and your workspace's MCP server can offer a node to an outside client as a tool.
What the gate sees
Every node reaches the gate as process.exec, and each side effect it declares adds an action. So a rule your operator wrote about writes or about network calls reaches a node nobody had seen when the rule was written.
| The node declares | The gate sees |
|---|---|
| any node | process.exec |
| file-read | file.read |
| file-write | file.write |
| network-request | net.request |
| llm-invocation | model.invoke |
What it does not do
Python only
The runner executes Python cells. There is no other language today.
Declared, not detected
The side effects are what the author wrote down. Code that writes a file without declaring it reaches the gate as process.exec alone, so read the source of a node you did not write. It is in the file.
Not a sandbox
A node runs on your workspace's ordinary Python kernel, with that kernel's access. The gate decides whether a call may run. It does not contain the code once it runs.
Debugging steps outside the gate
A run with breakpoints executes the cell directly in a kernel session so you can step through it, and leaves no gateway record.
Verified means its own tests
A verified node is one whose own test cases passed on its publisher's machine. The registry checks that record and does not run the cases again.
A copy does not update
A node you tried is a file in your workspace. It does not follow new versions on the registry, and trying and publishing need the desktop app.