# Nodes and Workers

At Ockam's core is a collection of cryptographic and messaging protocols. These protocols make it possible to create <mark style="color:orange;">private</mark> and <mark style="color:orange;">secure by design</mark> applications that provide end-to-end application layer trusted data.

Ockam is designed to make these powerful protocols <mark style="color:orange;">easy</mark> and <mark style="color:orange;">safe</mark> to use in <mark style="color:orange;">any application environment</mark> – 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.

<img src="/files/Yqn8Tgc2zMHe7LVMEws1" alt="" class="gitbook-drawing">

Ockam [<mark style="color:blue;">Nodes</mark>](#node), [<mark style="color:blue;">Workers</mark>](#worker), and [<mark style="color:blue;">Services</mark>](#service) 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 [<mark style="color:blue;">Routing</mark>](/documentation/command/routing.md) and Ockam [<mark style="color:blue;">Secure Channels</mark>](/documentation/command/secure-channels.md).

You can create a standalone node using Ockam [<mark style="color:blue;">Command</mark>](/documentation/command.md) or embed one directly into your application using various Ockam [<mark style="color:blue;">programming libraries</mark>](/documentation/libraries.md). Nodes are built to leverage the strengths of their operating environment. Our [<mark style="color:blue;">Rust</mark>](/documentation/libraries/rust.md) 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 [<mark style="color:blue;">Workers</mark>](#workers). Using Ockam [<mark style="color:blue;">Routing</mark>](/documentation/command/routing.md#routing), a node can deliver messages from one worker to another local worker. Using Ockam [<mark style="color:blue;">Transports</mark>](/documentation/command/routing.md#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 [<mark style="color:blue;">Nodes</mark>](#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.

<img src="/files/bs2vduwX7ghy7JKgaguL" alt="" class="gitbook-drawing">

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 [<mark style="color:blue;">Ockam Routing Protocol</mark>](/documentation/command/routing.md) and its Transports. Later in this guide, when we [<mark style="color:blue;">dig into routing</mark>](/documentation/command/routing.md), we'll send some messages across nodes.

From `ockam` command, we don't usually create workers directly but instead start predefined [<mark style="color:blue;">services</mark>](#service) like Transports and Secure Channels that in turn start one or more workers. Using our [libraries](/documentation/libraries.md) 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 [<mark style="color:blue;">Programming Libraries</mark>](/documentation/libraries.md) to expose very simple and safe interfaces for powerful protocols.

## Services

One or more Ockam [<mark style="color:blue;">Workers</mark>](#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 [<mark style="color:blue;">Nodes</mark>](#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
     │ alice@example.com
```

## Projects

Ockam Projects are also infinitely scalable Ockam [<mark style="color:blue;">Nodes</mark>](#nodes) in the cloud. Ockam Orchestrator can create, manage, and scale projects for you. Projects are created within a [<mark style="color:blue;">Space</mark>](#spaces) 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

{% hint style="info" %}
To clean up and delete all nodes, run: `ockam node delete --all`
{% endhint %}

Ockam [<mark style="color:blue;">Nodes</mark>](#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 [<mark style="color:blue;">Workers</mark>](#workers). Nodes and Workers hide complexities of environment and state to enable simple interfaces for stateful, asynchronous, message-based protocols.

One or more [<mark style="color:blue;">Workers</mark>](#workers) can work as a team to offer a [<mark style="color:blue;">Service</mark>](#services)<mark style="color:blue;">.</mark> 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 [<mark style="color:blue;">Spaces</mark>](#services) and [<mark style="color:blue;">Projects</mark>](#projects) that offer managed services that are designed for scale and reliability.

{% hint style="info" %}
If you're stuck or have questions at any point, [<mark style="color:blue;">please reach out to us</mark>](https://www.ockam.io/contact)<mark style="color:blue;">**.**</mark>
{% endhint %}

Next, let's learn about Ockam's [<mark style="color:blue;">Application Layer Routing</mark>](/documentation/command/routing.md) and how it enables protocols that provide end-to-end guarantees to messages traveling across many network connection hops and protocols boundaries.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ockam.io/documentation/command/nodes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.