Skip to main content

Hosting Agent

Hosting Your Agent on Nexus

Contributing your own agent to the Nexus ecosystem is the best way to share your work and allow others to build amazing things with it. This guide provides a complete walkthrough of the process, from creating your agent's configuration file to submitting it to our public registry.

The entire process is designed to be transparent and is based on tools you already know: JSON, Docker, and GitHub.

Prerequisites​

Before you begin, please ensure you have the following:

  • A working, container-ready AI agent or application.
  • Docker Desktop installed and running.
  • A Docker Hub account to host your public Docker image.
  • A GitHub account to submit your agent to our registry.

Step 1: Create Your agent_card.json​

The agent_card.json is a manifest file. It's the "digital passport" that tells Nexus everything about your agent: what it's called, what it does, and how to use it.

This file is the single source of truth for your agent's configuration.

Pro Tip

We recommend creating this file in the root directory of your agent's source code repository.

Below is a template for the "Hello World" agent. Use it to create your own.

agent_card.json
{
  "id": "com.nexus.helloworld",
  "name": "Hello World Agent",
  "description": "A simple agent that demonstrates the basic functionality of the Nexus platform by responding to a greeting.",
  "docker_image": "ashu4u/helloworld:latest",
  "version": "1.0.0",
  "author": "Nexus Team",
  "endpoints": {
    "base_url": "http://localhost:9999",
    "skills": {
      "sendMessage": "/v1/messages"
    }
  },
  "skills": [
    {
      "id": "hello_world_greeting",
      "name": "Hello World Greeting",
      "description": "Receives a simple text message and returns a standard 'Hello World' response.",
      "endpoint_id": "sendMessage",
      "input_schema": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "A simple greeting."
          }
        },
        "required": ["message"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "response": {
            "type": "string",
            "description": "The agent's reply."
          }
        }
      }
    }
  ]
}

Key Fields Explained:

  • id: A unique, reverse-domain style identifier for your agent.
  • docker_image: The exact name of your public Docker image on Docker Hub. This is crucial.
  • endpoints: Defines the base URL and paths for your agent's API. The skills object maps a function name to a specific path.
  • skills: An array of objects describing each capability of your agent, including its input/output data shape (schema).

Step 2: Dockerize Your Agent​

Your agent must be packaged as a Docker image to ensure it can run anywhere. If you don't already have one, create a Dockerfile in your project's root directory.

Here is a sample Dockerfile for a basic Python agent using FastAPI:

Dockerfile
FROM registry.access.redhat.com/ubi8/python-312

# Set work directory
WORKDIR /opt/app-root/

# Copy Python Project Files (Container context must be the `python` directory)
COPY . /opt/app-root

USER root

# Install system build dependencies and UV package manager
# Remove Build Tools After Install
RUN dnf -y update && dnf install -y gcc gcc-c++ \
 && pip install uv \
 && dnf remove -y gcc gcc-c++ \
 && dnf clean all \
 && rm -rf /var/cache/dnf

# Set environment variables for uv:
# UV_COMPILE_BYTECODE=1: Compiles Python files to .pyc for faster startup
# UV_LINK_MODE=copy: Ensures files are copied, not symlinked, which can avoid issues
ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy

# Install dependencies using uv sync.
# --frozen: Ensures uv respects the uv.lock file
# --no-install-project: Prevents installing the project itself in this stage
# --no-dev: Excludes development dependencies
# --mount=type=cache: Leverages Docker's build cache for uv, speeding up repeated builds
RUN --mount=type=cache,target=/.cache/uv \
    uv sync --frozen --no-install-project --no-dev

# Install the project
RUN --mount=type=cache,target=/.cache/uv \
    uv sync --frozen --no-dev

# Optional: remove build tools to reduce image size
RUN dnf remove -y gcc gcc-c++ make libffi-devel bzip2-devel zlib-devel xz-devel \
 && dnf clean all \
 && rm -rf /var/cache/dnf

# Allow non-root user to access the everything in app-root
RUN chgrp -R root /opt/app-root/ && chmod -R g+rwx /opt/app-root/

# Expose default port (change if needed)
EXPOSE 9999

USER 1001

# Run the agent
CMD ["uv", "run", ".", "--host", "0.0.0.0"]

Step 3: Build and Push Your Docker Image​

Next, build your Docker image and push it to your public Docker Hub repository. Make sure the image name here exactly matches the docker_image field in your agent_card.json.

Terminal Commands
# 1. Build the Docker image
# Replace <username>/<agent-name> with your Docker Hub username and agent name
docker build -t <username>/<agent-name>:latest .

# 2. Log in to Docker Hub
# You will be prompted for your username and password
docker login

# 3. Push the image to Docker Hub
# This makes your agent publicly available for users to pull
docker push <username>/<agent-name>:latest
Visibility

Ensure your Docker Hub repository is set to Public. Private repositories cannot be pulled by users.

Step 4: Submit Your Agent to the Nexus Registry​

Once your agent is ready, you can submit it for review. We offer two convenient methods: submitting via our user-friendly Developer Portal or, for those who prefer a Git-based workflow, via a GitHub Pull Request.

This is the easiest way to add your agent to the registry. Our web form guides you through all the required information.

  1. Navigate to the Developer Page: Log in to your Nexus account and go to the Developer section.

  2. Open the Submission Form: Click the "Add Agent" button to open the new agent submission form.

  3. Complete the Form: Fill out all the fields with your agent's details.

    • Agent Name: The primary display name for your agent (e.g., "Hello World Agent").
    • Description: A short, one-sentence summary of what your agent does.
    • Long Description: A detailed explanation. This field supports Markdown for rich formatting.
    • Tags: Comma-separated keywords that help users find your agent (e.g., text, utility, example).
    • Categories: Select one or more categories that best fit your agent (e.g., "Developer Tools", "Language Processing").
    • Screenshots: Upload one or more images showing your agent in action.
    • GitHub URL: The public URL to your agent's source code repository.
    • Agent Card: Upload the agent_card.json file you created in Step 1.
    • Docker Image: Enter the name of your Docker image (e.g., ashu4u/helloworld:latest). This must match the image you pushed in Step 3.

Submit for Review: Once you've filled everything out, click the "Submit" button. Your agent will be sent to our team for review. You can track the approval status on your developer dashboard.