1

Create an account

Sign up for an account with Ockam AI to create your new Cluster.

2

Install

Install ockam command by running the following in your terminal.

curl -sSfL install.command.ockam.io | bash && source "$HOME/.ockam/env"
3

Deploy your first agent

Ensure you have Docker installed and running on your workstation before running the ockam command.

After that, create an empty directory and run ockam command to enroll your workstation as an administrator of your newly created Cluster in Ockam AI.

mkdir hello && cd hello && ockam

This will generate an Ockam Identity for your workstation and store its secret keys in a file system based Ockam Vault. It will then ask you to authenticate with Ockam Orchestrator to make your workstation’s new Ockam Identity an administrator of your Cluster.

Finally, the above command will download the code for a template hello app and create a production-ready deployment Zone in your Cluster on our serverless Runtime. Withing seconds, it will put your first AI Agent into production and you can immediately start interacting with it.

4

Chat with your agent

The hello app includes an interactive REPL for interacting with your agent:

Welcome to Ockam 👋

You are connected to your agent - 25df35de/66a48b60
Ask it a question or give it a task.

Type ':help' or ':h' to see this message again.
Type ':quit' or ':q' to disconnect.

>

This agent is running on Ockam’s serverless runtime.

The REPL you access on your local machine runs in the cloud, and you connect to it over a secure & private connection using Ockam’s messaging protocols.

5

Ask the agent something

Type your instructions and press [ENTER] to interact with the agent:

> Who are you?

​
The generated code

Within the hello directory, ockam has created the following three files:

Generated Files
» tree

├── ockam.yaml
└── images
    └── main
        ├── Dockerfile
        └── main.py
  • The ockam.yaml configuration file defines how to deploy a Zone in your Cluster in Ockam AI.
  • The images directory contains the source code of docker images that will be used to run containers in your Zone.
    • Inside images, there is a directory for the main image.
      • Dockerfile describe how the main image will be compiled.
      • main.py is the Python program that is run by the main image.

Let’s examine each file:

ockam.yaml
name: hello
pods:
  - name: main-pod
    containers:
      - name: main
        image: main
        args: [localhost:9000]
    portals:
      outlets:
        - to: localhost:9000

The ockam.yaml configuration file defines how to deploy your Zone:

  • Create a Zone named 01 .
  • Create a Pod named main-podinside the 01 Zone.
  • Make the HTTP server, in the main container in this pod, public.
  • Run a main container using the main image.
  • Set up a portal outlet that will allow you to reach localhost:9000 in this pod.
images/main/Dockerfile
FROM ghcr.io/build-trust/ockam-python:latest
COPY . .
ENTRYPOINT ["python", "main.py"]

The Dockerfile bases the main image on the ockam-python image which already contains the ockam python package. The Dockerfile then copies the contents of the images/main directory into the image and sets main.py as the program to run when the container is started.

images/main/main.py
from ockam import Agent, Node, Repl
from sys import argv


async def main(node):
    agent = await Agent.start(node, "You are Jack Sparrow.")
    await Repl.start(agent, argv[1])


Node.start(main)

The main.py file:

  1. Turns your Python app into an Ockam Node. An Ockam Node in your Cluster can connect with and deliver messages to any other Ockam Node in your Cluster that is running in Ockam AI.
  2. After the Node is initialized, it invokes the main function defined in your main.py file. The main function starts an agent with specific instructions (“You are Jack Sparrow”).
  3. It then starts a REPL (interactive shell) server for that agent.
Output
.   Deploying zone hello in cluster 25df35de87aa441b88f22a6c2a830a17...

  ✔ Created a repository for the image main
  ✔ Built image main
  ✔ Pushed image main

  ✔ Deployed zone hello in cluster 25df35de87aa441b88f22a6c2a830a17

  ✔ Opened a portal to the outlet main-pod on main-pod from tcp://localhost:9000
  ✔ Opened a portal to the outlet http on main-pod from tcp://localhost:8000
  ✔ Opened a portal to the outlet logs on logs-pod from tcp://localhost:3000

When you run ockam:

  1. It builds the code in images/main into a container image and pushes that image to a container registry available to your Zone. It then deploys the Zone into your Cluster, in Ockam AI, based on configuration that is specified above in ockam.yaml.
  2. Next, it opens a portal inlet on your workstation that connects to the outlet in the main-pod . This creates a portal to the REPL server in your main container and makes that server available on a local port on your workstation.
  3. Finally, it connects a REPL client to the REPL server through this secure portal.