LogoLogo
Ockam.ioOpen Source CodeContact usSign up
  • Intro to Ockam
  • Ockam's core concepts
  • Get started demo
  • Quickstarts
    • Add secure connectivity to your SaaS product
    • Snowflake federated queries to Postgres
    • Postgres to Snowflake
    • Snowflake to Postgres
    • Kafka to Snowflake
    • Snowflake to Kafka
    • Snowflake stage as SFTP server
    • Snowflake stage as WebDAV file share
    • Snowflake hosted private APIs
    • Federated queries from Snowflake
  • ENCRYPTED PORTALS TO ...
    • Databases
      • PostgreSQL
        • Docker
        • Kubernetes
        • Amazon RDS
        • Amazon Aurora
      • MongoDB
        • Docker
        • Kubernetes
        • Amazon EC2
      • InfluxDB
        • Amazon Timestream
    • APIs
      • Nodejs
      • Python
    • AI
      • Amazon Bedrock
      • Amazon EC2
      • Azure OpenAI
    • Code Repos
      • Gitlab Enterprise
    • Kafka
      • Apache Kafka
        • Docker
      • Redpanda
        • Self Hosted
      • Confluent
        • Cloud
      • Warpstream
        • Cloud
      • Instaclustr
        • Cloud
      • Aiven
        • Cloud
  • Reference
    • Command
      • Nodes and Workers
      • Routing and Transports
      • Relays and Portals
      • Identities and Vaults
      • Secure Channels
      • Verifiable Credentials
      • Guides
        • AWS Marketplace
          • Ockam Node
          • Ockam Node for Amazon MSK
          • Ockam Node for Amazon RDS Postgres
          • Ockam Node for Amazon Timestream InfluxDB
          • Ockam Node for Amazon Redshift
          • Ockam Node for Amazon Bedrock
      • Manual
    • Programming Libraries
      • Rust
        • Nodes and Workers
        • Routing and Transports
        • Identities and Vaults
        • Secure Channels
        • Credentials and Authorities
        • Implementation and Internals
          • Nodes and Workers
        • docs.rs/ockam
    • Protocols
      • Nodes and Workers
      • Routing and Transports
      • Keys and Vaults
      • Identities and Credentials
      • Secure Channels
      • Access Controls and Policies
Powered by GitBook
On this page
  • Nodes
  • Workers
  • Services
  • Spaces
  • Projects

Was this helpful?

Edit on GitHub
Export as PDF
  1. Reference
  2. Command

Nodes and Workers

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

PreviousCommandNextRouting and Transports

Last updated 1 year ago

Was this helpful?

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.

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

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
...

Services

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

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

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 , , and help hide this complexity and decouple from the host environment - to provide simple interfaces for stateful and asynchronous message-based protocols.

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

You can create a standalone node using Ockam or embed one directly into your application using various Ockam . Nodes are built to leverage the strengths of their operating environment. Our 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 . Using Ockam , a node can deliver messages from one worker to another local worker. Using Ockam , nodes can also route messages to workers on other remote nodes.

Ockam 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.

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 and its Transports. Later in this guide, when we , we'll send some messages across nodes.

From ockam command, we don't usually create workers directly but instead start predefined like Transports and Secure Channels that in turn start one or more workers. Using our 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 to expose very simple and safe interfaces for powerful protocols.

One or more Ockam 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.

Ockam Spaces are infinitely scalable Ockam 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.

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

Ockam 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 . Nodes and Workers hide complexities of environment and state to enable simple interfaces for stateful, asynchronous, message-based protocols.

One or more can work as a team to offer a . 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 and that offer managed services that are designed for scale and reliability.

If you're stuck or have questions at any point, .

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

Routing
Secure Channels
Command
programming libraries
Rust
Ockam Routing Protocol
dig into routing
Programming Libraries
please reach out to us
Application Layer Routing
Nodes
Workers
Services
Nodes
libraries
services
Workers
Nodes
Nodes
Space
Nodes
Workers
Workers
Service
Spaces
Projects
Workers
Routing
Transports
Drawing
Drawing