> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Hermes Agent on AgentBox
## 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:**
* Hermes Agent running locally ([see setup guide →](/agents/set-up-hermes-agent-with-gmi-cloud))
* GitHub account with `gh` CLI authenticated (`gh auth login`)
* GMI Cloud account → [console.gmicloud.ai](https://console.gmicloud.ai/)
* A Discord bot token ([create one →](https://discord.com/developers/applications))
## Overview
| Step | What happens |
| :--- | :------------------------------------------------------- |
| 1 | Fork the repo and push AgentBox deploy files to GitHub |
| 2 | GitHub Actions builds and publishes your container image |
| 3 | Make the image public on GitHub Packages |
| 4 | Register and configure the agent on GMI AgentBox |
| 5 | Hermes Agent responds live in Discord |
## Step 1: Fork the Repo and Push AgentBox Files
Navigate to your local Hermes Agent directory:
```text theme={null}
cd ~/.hermes/hermes-agent
```
Fork the upstream NousResearch repo (runs on GitHub servers, nothing heavy to upload):
```text theme={null}
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:
```text theme={null}
git remote add myfork https://github.com//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:
>
> ```yaml expandable theme={null}
> 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//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:
>
> ```javascript theme={null}
> mkdir -p ~/.hermes/hermes-agent/deploy/agentbox
> nano ~/.hermes/hermes-agent/deploy/agentbox/Dockerfile.agentbox
> ```
>
> Paste this content and save:
>
> ```text theme={null}
> 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:
```text theme={null}
ghcr.io//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](https://console.gmicloud.ai/), then AgentBox, then **Register**.
Fill in the form:
| Field | Value |
| :----------------- | :----------------------------------------------- |
| Name | `Hermes Agent` (or any name) |
| Image source | Registry URL |
| Image URL | `ghcr.io//hermes-agentbox:latest` |
| Enable Credentials | OFF (image is public) |
| Compute | Container, 2 vCPU / 4 GB |
| Region | IOWA IDC-1 |
| MaaS integration | ON, select your model (becomes `$GMI_MODELS`) |
| Port mapping | 443 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:
| Variable | Type | Value |
| :------------------------ | :----- | :------------------------------------------------ |
| `API_SERVER_KEY` | SECRET | Discord API Server key |
| `DISCORD_BOT_TOKEN` | SECRET | Your Discord bot token (reset before use) |
| `GATEWAY_ALLOW_ALL_USERS` | Plain | `true` |
| `HERMES_MODEL` | Plain | `deepseek-ai/DeepSeek-V4-Pro`(Or any other model) |
| `DISCORD_HOME_CHANNEL` | Plain | Your 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:**
```yaml theme={null}
# 1. Provision a container
curl -X POST 'https://api.gmi-serving.com/v1/agents/deployments/dfs/tasks' \
-H 'Authorization: Bearer ' \
-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 '
# Each item's "id" is a ; "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/' \
-H 'Authorization: Bearer '
# 4. Terminate when the user session ends
curl -X DELETE 'https://api.gmi-serving.com/v1/agents/tasks/' \
-H 'Authorization: Bearer '
```
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.