Skip to main content

Deploy Hermes Agent on GMI AgentBox (GitHub)

Deploy a locally running Hermes Agent to the cloud using GMI AgentBox, straight from GitHub, fully automated. Docker is handled entirely by GitHub Actions.
Prerequisites:

Overview

StepWhat happens
1Fork the repo and push AgentBox deploy files to GitHub
2GitHub Actions builds and publishes your container image
3Make the image public on GitHub Packages
4Register and configure the agent on GMI AgentBox
5Hermes Agent responds live in Discord

Step 1: Fork the Repo and Push AgentBox Files

Navigate to your local Hermes Agent directory:
cd ~/.hermes/hermes-agent
Fork the upstream NousResearch repo (runs on GitHub servers, nothing heavy to upload):
gh repo fork NousResearch/hermes-agent --clone=false --remote-name myfork
Connect your local code to your fork and push. Run these commands in order:
git remote add myfork https://github.com/<your-username>/hermes-agent.git
git add deploy/agentbox/ .github/workflows/agentbox-publish.yml
git commit -m "Add GMI AgentBox deploy kit + publish workflow"
git pull --rebase myfork main
git push myfork main
What each command does:
  • git remote add myfork saves your fork’s address as a bookmark called myfork. Nothing uploads yet.
  • git add stages only the AgentBox deploy files and publish workflow.
  • git commit saves a snapshot of those changes locally.
  • git pull --rebase pulls any updates from your fork first so your push goes through cleanly.
  • git push myfork main sends your code to GitHub. Your code is now live on your fork.
⚠️ REQUIRED: .github/workflows/agentbox-publish.yml This workflow file must exist in your repo before pushing. If it does not exist yet, create it at .github/workflows/agentbox-publish.yml with the following content:
name: Publish AgentBox image

# Builds the GMI AgentBox image (deploy/agentbox/Dockerfile.agentbox) and
# publishes it to this repo's GitHub Container Registry (ghcr.io).
#
# After the first successful run, make the package public once in:
#   GitHub -> your profile -> Packages -> hermes-agent -> Package settings
#   -> Change visibility -> Public
# Then point GMI AgentBox at:
#   ghcr.io/<your-username>/hermes-agent:latest   (Enable Credentials: OFF)

on:
  # Run it by hand from the Actions tab (best for a demo).
  workflow_dispatch:
  # ...and automatically when you push a version tag like v1, v1.2.3
  push:
    tags:
      - 'v*'

permissions:
  contents: read
  packages: write   # required to push to ghcr.io

jobs:
  publish:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      # ghcr image names must be lowercase; usernames can contain uppercase.
      - name: Compute lowercase image name
        id: img
        run: echo "ref=ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/hermes-agentbox" >> "$GITHUB_OUTPUT"

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to ghcr.io
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      # 1/2 — Build the base Hermes image (the slow step) and push it as the
      # ':base' tag so the AgentBox build below can pull it as its FROM image.
      - name: Build & push base image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile
          platforms: linux/amd64        # AgentBox compute is x86_64 (IOWA IDC-1)
          push: true
          tags: ${{ steps.img.outputs.ref }}:base
          cache-from: type=gha,scope=agentbox-base
          cache-to: type=gha,mode=max,scope=agentbox-base

      # 2/2 — Build the thin AgentBox layer on top and push it as ':latest'.
      # This is the image you register in the AgentBox wizard.
      - name: Build & push AgentBox image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: deploy/agentbox/Dockerfile.agentbox
          platforms: linux/amd64
          push: true
          build-args: |
            BASE_IMAGE=${{ steps.img.outputs.ref }}:base
          tags: ${{ steps.img.outputs.ref }}:latest

      - name: Summary
        run: |
          {
            echo "## AgentBox image published "
            echo ""
            echo "**Register URL:** \`${{ steps.img.outputs.ref }}:latest\`"
            echo ""
            echo "Next: make the package **public** (Packages -> hermes-agent ->"
            echo "Package settings -> Change visibility), then point GMI AgentBox"
            echo "at the URL above with Enable Credentials **OFF**."
          } >> "$GITHUB_STEP_SUMMARY"
The GITHUB_TOKEN secret is auto-injected by GitHub. You do not need to create it.
⚠️ REQUIRED: deploy/agentbox/Dockerfile.agentbox Create this file in your repo before pushing. Your workflow calls it directly to build the AgentBox layer on top of your base image. Run this in your terminal to create it:
mkdir -p ~/.hermes/hermes-agent/deploy/agentbox
nano ~/.hermes/hermes-agent/deploy/agentbox/Dockerfile.agentbox
Paste this content and save:
ARG BASE_IMAGE
FROM ${BASE_IMAGE}
EXPOSE 8080
CMD ["python", "-m", "hermes.gateway"]
The BASE_IMAGE value is injected automatically by the workflow. You do not need to hardcode anything.

Step 2: GitHub Actions Builds and Publishes the Image

  1. Open your fork on GitHub and click the Actions tab
  2. If prompted, click “I understand my workflows, enable them” (forks have Actions paused by default)
  3. Select “Publish AgentBox image” in the left sidebar
  4. Click Run workflow then Run
GitHub builds the base image, layers on the AgentBox config, and pushes both to GitHub Packages with two tags: :base and :latest. Your image will be available at:
ghcr.io/<your-username>/hermes-agentbox:latesttext
Note: The first build takes 5-10 minutes. Subsequent builds are faster due to Docker layer caching.

Step 3: Make the Image Public on GitHub Packages

New packages are private by default. AgentBox pulls your image directly from this URL, so visibility must be set to public before registering.
  1. Go to your GitHub profile
  2. Click Packages and select hermes-agentbox
  3. Go to Package settings, then Change visibility, then Public
    ⚠️ If you prefer to keep the image private, skip this step and instead set Enable Credentials: ON in the AgentBox registration form, then provide a GitHub Personal Access Token (PAT) with read:packages scope.

Step 4: Register and Configure on GMI AgentBox

Go to console.gmicloud.ai, then AgentBox, then Register. Fill in the form:
FieldValue
NameHermes Agent (or any name)
Image sourceRegistry URL
Image URLghcr.io/<your-username>/hermes-agentbox:latest
Enable CredentialsOFF (image is public)
ComputeContainer, 2 vCPU / 4 GB
RegionIOWA IDC-1
MaaS integrationON, select your model (becomes $GMI_MODELS)
Port mapping443 to 8080 (default)

Environment Variables

GMI AgentBox auto-injects the following. Leave these out of the form:
  • GMI_MAAS_API_KEY
  • GMI_MAAS_BASE_URL
Add the following custom variables:
VariableTypeValue
API_SERVER_KEYSECRETDiscord API Server key
DISCORD_BOT_TOKENSECRETYour Discord bot token (reset before use)
GATEWAY_ALLOW_ALL_USERSPlaintrue
HERMES_MODELPlaindeepseek-ai/DeepSeek-V4-Pro(Or any other model)
DISCORD_HOME_CHANNELPlainYour Discord channel ID (optional)
Click Register.

Save Your AgentBox API Key

After registering, AgentBox generates a unique API key for your agent. Save this immediately. It is shown only once and is separate from your GMI Cloud inference API key.

Step 5: Run Your Instance and Test in Discord

Via dashboard:
Click your registered agent, then Create Instance, confirm settings, then Launch.
Via CLI:
# 1. Provision a container
curl -X POST 'https://api.gmi-serving.com/v1/agents/deployments/dfs/tasks' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "idc_name": "us-central-iowa1",
    "instance_type": "gmi.container.intel.x4660.large",
    "template_id": "3490ab00-9a71-4a00-9ef6-035004dd088f"
  }'

# 2. List the tasks running under this deployment
curl 'https://api.gmi-serving.com/v1/agents/deployments/dfs/tasks' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>'
# Each item's "id" is a <TASK_ID>; "total" is the current task count.

# 3. Poll until status = "running", then route the endpoint to your user
curl 'https://api.gmi-serving.com/v1/agents/tasks/<TASK_ID>' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>'

# 4. Terminate when the user session ends
curl -X DELETE 'https://api.gmi-serving.com/v1/agents/tasks/<TASK_ID>' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>'
Instance creation takes approximately 1–2 minutes. Once running, open your Discord server and send a message in the configured channel. Hermes Agent will respond in real time, powered by DeepSeek-V4-Pro via GMI Cloud.