Nodes and Workers

Ockam Nodes and Workers decouple applications from the host environment and enable simple interfaces for stateful and asynchronous message-based protocols.

At Ockam's core is a collection of cryptographic and messaging protocols. These protocols make it possible to create private and secure by design applications that provide end-to-end application layer trusted data.

Ockam is designed to make these powerful protocols easy and safe to use in any application environment – from highly scalable cloud services to tiny battery operated microcontroller based devices.

However, many of these protocols require multiple steps and have complicated internal state that must be managed with care. It can be quite challenging to make them simple to use, secure, and platform independent.

Ockam Nodes, Workers, and Services help hide this complexity and decouple from the host environment - to provide simple interfaces for stateful and asynchronous message-based protocols.

Nodes

An Ockam Node is any program that can interact with other Ockam Nodes using various Ockam protocols like Ockam Routing and Ockam Secure Channels.

You can create a standalone node using Ockam Command or embed one directly into your application using various Ockam programming libraries. Nodes are built to leverage the strengths of their operating environment. Our Rust implementation, for example, makes it easy to adapt to various architectures and processors. It can run efficiently on tiny microcontrollers or scale horizontally in cloud environments.

A typical Ockam Node is implemented as an asynchronous execution environment that can run very lightweight, concurrent, stateful actors called Ockam Workers. Using Ockam Routing, a node can deliver messages from one worker to another local worker. Using Ockam Transports, nodes can also route messages to workers on other remote nodes.

Ockam Command makes it super easy to create and manage local or remote nodes. If you run ockam node create, it will create and start a node in the background and give it a random name:

» ockam node create
✔︎ Node sharp-falconet created successfully

Similarly, you can also create a node with a name of your choice:

» ockam node create n1
✔︎ Node n1 created successfully

You could also start a node in the foreground and optionally tell it display verbose logs:

» ockam node create n2 --foreground --verbose
2023-05-18T09:54:24.281248Z  INFO ockam_node::node: Initializing ockam node
2023-05-18T09:54:24.298089Z  INFO ockam_command::node::util: node state initialized name=n2
2023-05-18T09:54:24.298906Z  INFO ockam_node::processor_builder: Initializing ockam processor '0#c20e2e4aeb9fbae2b5be1529c83af54d' with access control in:DenyAll out:DenyAll
2023-05-18T09:54:24.299627Z  INFO ockam_api::cli_state::nodes: setup config updated name=n2
2023-05-18T09:54:24.302206Z  INFO ockam_api::nodes::service: NodeManager::create: n2
2023-05-18T09:54:24.302218Z  INFO ockam_api::nodes::service: NodeManager::create: starting default services
2023-05-18T09:54:24.302286Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#_internal.nodemanager' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.302719Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#ockam.ping.collector' with access control in:AllowAll out:DenyAll
2023-05-18T09:54:24.302728Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#identity_service' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.303179Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#authenticated' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.303364Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#uppercase' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.303527Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#forwarding_service' with access control in:AllowAll out:DenyAll
2023-05-18T09:54:24.303851Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#api' with access control in:AllowAll out:DenyAll
2023-05-18T09:54:24.304009Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#echo' with access control in:AllowAll out:AllowAll
2023-05-18T09:54:24.304056Z  INFO ockam_node::worker_builder: Initializing ockam worker '0#rpc_proxy_service' with access control in:AllowAll out:AllowAll
...

To stop the foreground node, you can press Ctrl-C. This will stop the node but won't delete its state.

You can see all running nodes with ockam node list

» ockam node list

       ┌───────────────────┐
       │       Nodes       │
       └───────────────────┘

     │ Node n1  UP
     │ Process id 42218

     │ Node sharp-falconet (default) UP
     │ Process id 42083

     │ Node n2  DOWN
     │ No process running
...

You can stop a running node with ockam node stop.

» ockam node stop n1

You can start a stopped node with ockam node start.

» ockam node start n1

You can permanently delete a node by running:

» ockam node delete n1
✔︎ The node named 'n1' has been deleted.

You can also delete all nodes with:

» ockam node delete --all

Workers

Ockam Nodes run very lightweight, concurrent, and stateful actors called Ockam Workers. They are like processes on your operating system, except that they all live inside one node and are very lightweight so a node can have hundreds of thousands of them, depending on the capabilities of the machine hosting the node.

When a worker is started on a node, it is given one or more addresses. The node maintains a mailbox for each address and whenever a message arrives for a specific address it delivers that message to the corresponding worker. In response to a message, a worker can: make local decisions, change internal state, create more workers, or send more messages.

You can see the list of workers in a node by running:

» ockam node create n1
» ockam worker list --at n1
       ┌───────────────────────────┐
       │       Workers on n1       │
       └───────────────────────────┘

     │ Worker 0c240525017e2273fa58fc0d5497b62a

     │ Worker 31482d2647246b47667cf12428626723

     │ Worker 4248c83401c77176967715caca9d82dd

     │ Worker _internal.nodemanager
...

Note the workers in node n1 with address echo and uppercase. We'll send them some messages below as we look at services. A node can also deliver messages to workers on a different node using the Ockam Routing Protocol and its Transports. Later in this guide, when we dig into routing, we'll send some messages across nodes.

From ockam command, we don't usually create workers directly but instead start predefined services like Transports and Secure Channels that in turn start one or more workers. Using our libraries you can also develop your own workers.

Workers are stateful and can asynchronously send and receive messages. This makes them a potent abstraction that can take over the responsibility of running multistep, stateful, and asynchronous message-based protocols. This enables ockam command and Ockam Programming Libraries to expose very simple and safe interfaces for powerful protocols.

Services

One or more Ockam Workers can work as a team to offer a Service. Services can also be attached to a trust context and authorization policies to enforce attribute based access control rules.

For example, nodes that are created with Ockam Command come with some predefined services including an example service /service/uppercase that responds with an uppercased version of whatever message you send it:

» ockam message send hello --to /node/n1/service/uppercase
HELLO

Services have addresses represented by /service/{ADDRESS}. You can see a list of all services on a node by running:

» ockam service list --at n1
       ┌────────────────────────────┐
       │       Services on n1       │
       └────────────────────────────┘

     │ Service uppercase
     │ Address /service/uppercase

     │ Service echo
     │ Address /service/echo

     │ Service credentials
     │ Address /service/credentials

Later in this guide, we'll explore other commands that interact with pre-defined services. For example every node created with ockam command starts a secure channel listener at the address /service/api, which allows other nodes to create mutually authenticated secure channels with it.

Spaces

Ockam Spaces are infinitely scalable Ockam Nodes in the cloud. Ockam Orchestrator can create, manage, and scale spaces for you. Like other nodes, Spaces offer services. For example, you can create projects within a space, invite teammates to it, or attach payment subscriptions.

When you run ockam enroll for the first time, we create a space for you to host your projects.

» ockam enroll
...

» ockam space list
       ┌────────────────────┐
       │       Spaces       │
       └────────────────────┘

     │ Space f27d39e1
     │ Id 877c7a4d-b1be-4f36-8da6-be045ab64b60
     │ [e-mail]

Projects

Ockam Projects are also infinitely scalable Ockam Nodes in the cloud. Ockam Orchestrator can create, manage, and scale projects for you. Projects are created within a Space and can inherit permissions and subscriptions from their parent space. There can be many projects within one space.

When you run ockam enroll for the first time, we create a default project for you, within your default space.

» ockam enroll
...

» ockam project list
       ┌──────────────────────┐
       │       Projects       │
       └──────────────────────┘

     │ Project default
     │ Space f27d39e1

Like other nodes, Projects offer services. For example, the default project has an echo service just like the local nodes we created above. We can send messages and get replies from it. The echo service replies with the same message we send it.

» ockam message send hello --to /project/default/service/echo
hello

Recap

To clean up and delete all nodes, run: ockam node delete --all

Ockam Nodes are programs that interact with other nodes using one or more Ockam protocols like Routing and Secure Channels. Nodes run very lightweight, concurrent, and stateful actors called Workers. Nodes and Workers hide complexities of environment and state to enable simple interfaces for stateful, asynchronous, message-based protocols.

One or more Workers can work as a team to offer a Service. Services can be attached to trust contexts and authorization policies to enforce attribute based access control rules. Ockam Orchestrator can create and manage infinitely scalable nodes in the cloud called Spaces and Projects that offer managed services that are designed for scale and reliability.

If you're stuck or have questions at any point, please reach out to us.

Next, let's learn about Ockam's Application Layer Routing and how it enables protocols that provide end-to-end guarantees to messages traveling across many network connection hops and protocols boundaries.