Register an agent - GMI Cloud Documentation

Register, launch, publish: three separate things

Step	What happens	Where
Register	You package your agent as a container image and register it with GMI AgentBox. GMI stores the template and makes it deployable.	Register an agent wizard
Launch	A user (or you) provisions a running instance from the registered template. Billing starts while the instance is active.	Agent detail page or API
Publish	You submit the listing for the Marketplace. Other GMI users can discover and deploy your agent.	List an agent

Who pays when a user shows up

When a user deploys your agent through AgentBox, the user pays for their own instance runtime and any model inference tokens they consume. You pay nothing for their usage. You only pay when you provision instances yourself for testing or development.

The order that saves you trouble

Register first, then test the live endpoint, then publish. Skipping registration and going straight to listing creates a listing with no deployable backend, which confuses users and hurts your credibility.

Choosing your path first

	GMI CE Deployment	Self-hosted + MaaS
Who hosts the agent	GMI Infrastructure	You
Badge	Eligible for Verified	Powered by GMI MaaS
Setup complexity	Full wizard (5 steps)	Short flow (3 steps)
Compute billing	Per-second, GMI-managed	Your infrastructure costs
Best for	Production agents that need GMI-managed scaling	Agents already running elsewhere

Before you begin

You need:

A working agent application that listens on an HTTP port
A Docker image containing your agent
The image pushed to a container registry that GMI can access

Why a Docker image

GMI AgentBox runs your agent as a container. A Docker image packages your code, runtime, and dependencies into a single deployable unit. This means your agent runs the same way on GMI as it does on your machine.

What your image must do

Your Docker image must:

Expose an HTTP server on a known port (default: 8080)
Respond to health checks on that port
Accept requests and return responses within the gateway timeout (see Handle long-running requests for longer tasks)
Read MaaS connection details from environment variables (see below)

Getting your image into a registry

Build and push your image to a registry:

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8080
CMD ["python", "main.py"]

# Build the image
docker build -t your-org/your-agent:latest .

# Tag for your registry
docker tag your-org/your-agent:latest registry.hub.docker.com/your-org/your-agent:latest

# Push to Docker Hub
docker push registry.hub.docker.com/your-org/your-agent:latest

You can use Docker Hub, GitHub Container Registry (GHCR), or any public or private registry.

Configure the GMI MaaS endpoint in your image

Before you wrap your agent into an image, read the GMI MaaS connection details from these environment variables. At runtime, GMI injects the API key for the models you select in Step 2, so you never ship a key inside your image.

Variable	Description	Example
`GMI_MAAS_BASE_URL`	OpenAI-compatible base URL for GMI MaaS.	`https://api.gmi-serving.com`
`GMI_MAAS_API_KEY`	MaaS API key. Injected by GMI at runtime — do not hardcode it.	(injected)
`GMI_MODELS`	Model ID your agent calls.	`deepseek-ai/DeepSeek-V4-Pro`

Read these variables in your code rather than hardcoding values, for example:

import os
from openai import OpenAI

client = OpenAI(
    base_url=f"{os.environ['GMI_MAAS_BASE_URL']}/v1",
    api_key=os.environ["GMI_MAAS_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["GMI_MODELS"],
    messages=[{"role": "user", "content": "Hello"}],
)

Leave GMI_MAAS_API_KEY unset in your image — GMI injects it at runtime when MaaS integration is enabled (Step 2). Hardcoding a key is unnecessary and will be overridden.

Wizard steps

Basics & Template
Infrastructure
Networking
Env Variables
Review & Register

Step 1: Basics & Template

Identity for the listing. This is what users see on the catalog card and detail page.

If you’re going with the self-hosted + MaaS path, the Basics & Template step looks slightly different:

Register an agent, Basics & Template (MaaS path)

Add the internal project name

Step 2: Infrastructure

Configure compute resources. GMI Infrastructure provisions containers on demand.

Docker image source

Registry URL. Pull from Docker Hub, GHCR, or any public/private registry.
Upload Image. Push a local image directly to GMI’s registry. Useful for one-off builds.

Registry URL

Format: registry.hub.docker.com/your-org/your-agent:latest

Enable Credentials

Turn on Enable Credentials if your Docker registry requires authentication to pull images. The toggle reveals two fields inline, entered here in Step 2 (not as Env Variables):

Username — your registry username.
Access Token — your registry password or personal access token.

Compute tier

Container — 2 vCPU · 4 GB RAM · Ephemeral Storage 10 GiB · Data Storage 30 GiB. Additional tiers coming soon.

Region

Currently available: IOWA IDC-1 (US-IA, US). Additional regions are being added.
Pick the region closest to your users to minimize latency.
Multi-region rollouts require a separate deploy per region.

MaaS integration

Toggle on to give your agent access to GMI’s 200+ frontier models.
GMI injects a MaaS API key into your container at startup, no key management on your end.
Select every model your agent may call. Selection is editable later.
Required for the Verified badge.

Step 3: Networking

Expose the ports your agent listens on. GMI CE routes external traffic to these container ports.

Public IP address

A public IP address is allocated automatically by the platform. No manual setup required.

Port Mapping

Change these if your app listens on a different port. Each mapping has:

Protocol — for example HTTPS/2.
Listening Port — the external port GMI exposes.
Internal Port — the port your container listens on.
Port name — a label for the mapping.

The default mapping is HTTPS/2, external port 443 → internal port 8080, named web. Use Add port mapping to expose additional ports, or the remove control to delete one.

Step 4: Env Variables

Runtime configuration injected into your container at startup.

Auto-Injected by GMI

GMI injects these MaaS connection variables automatically. They are locked and cannot be overridden:

GMI_MAAS_API_KEY — the MaaS API key, injected at runtime.
GMI_MAAS_BASE_URL — the OpenAI-compatible MaaS base URL.

Custom Variables

Add your own variables. Each row has a Type:

Type	Use for
`TEXT`	Non-sensitive config: feature flags, base URLs, log levels. Visible in the dashboard and editable anytime.
`SECRET`	API keys, third-party credentials, and any sensitive value. Write-once: values can be replaced but never read back from the UI.

Secrets are encrypted at rest with AES-256. Plaintext values are never written to logs or audit history.

Per-region overrides

Override values per region for staged rollouts or region-specific endpoints.
Only available when the agent is deployed to more than one region.

Step 5: Review & Register

Confirm settings, register, and verify before submitting the listing.

Review screen

Every setting from the previous steps is summarized on one page.
Click any section to jump back and edit.

Register

Once registered, GMI AgentBox pulls the image and builds the container on demand. Users can then call the endpoint to start or stop the instance — billing runs only for the duration the container is active.
The endpoint provided is used for container CRUD.

Test the endpoint

Hit the URL with a sample request. Confirm latency, output, and error handling.
Iterate by re-registering. URLs stay stable across updates.

Self-hosted + MaaS (Path B)

You host the agent yourself and call GMI Models-as-a-Service for inference. Lists with the Powered by GMI MaaS badge. On this path you don’t go through the full register wizard above. Instead, Connect your agent is a short 3-step flow:

Basic — project name
MaaS Key — generate or connect a GMI MaaS API key
Endpoint — provide your public-facing URL

Step 4 · Review & Submit

After entering your endpoint, review the connection details and submit. GMI validates the endpoint is reachable and the MaaS key is active. Once validated, your self-hosted agent is connected and appears in your My Agents dashboard.

Managing your deployment

Once your agent is registered and deployed, the My Agents dashboard (under My Deployments & Listings) shows every agent you’ve published. Select an agent to open its panel, which has three tabs — Monitor, Integration, and Analytics — and three actions at the top right:

Unpublish — remove the listing from the Marketplace.
Edit listing — update the public listing fields.
View public listing — open the live Marketplace page for the agent.

Monitor tab

Aggregate status — live counts for Active, Error, and Creating instances, plus the Last provisioned timestamp.
Instance Set — a searchable table of every instance with All / Running / Error / Creating filter tabs and columns for Instance ID, Status, Created, and Action (View Detail, View Log, Monitoring).

Integration tab

The Integration tab gives you the Template ID (a UUID, with a copy button) and the full instance lifecycle as a 4-step curl workflow: provision → list tasks → poll → terminate. Replace <YOUR_API_TOKEN> with a token from your GMI account settings, and <YOUR_TEMPLATE_ID> with the Template ID shown at the top of the tab.

# 1. Provision a container
curl -X POST 'https://api.gmi-serving.com/v1/agents/deployments/<slug>/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": "<YOUR_TEMPLATE_ID>"
  }'

# 2. List tasks running under this deployment
curl 'https://api.gmi-serving.com/v1/agents/deployments/<slug>/tasks' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>'

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

# 4. Terminate when the session ends
curl -X DELETE 'https://api.gmi-serving.com/v1/agents/tasks/<TASK_ID>' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>'

Analytics tab

Usage By Model — a usage chart with a 1D / 7D / 30D / 90D time-range switcher.
API Key Management — a table of keys showing key name, masked value, scope, and owner ID.
View billing — a link through to your billing details.

Launching an instance

From the Monitor tab, click Launch to provision a new instance of your agent. The instance spins up in the region you selected during registration and gets its own public URL. Billing starts when the instance reaches Running status and stops when you terminate it.

Authentication-key matrix

Key type	Who manages it	Where it lives	What it authenticates
GMI MaaS API key	GMI	Injected into your container at runtime	Model inference calls from your agent
Your GMI API token	You	GMI account settings	AgentBox management API (provision, list, terminate)
Third-party API keys	You	Step 4 Env Variables (SECRET type)	External services your agent calls

Publishing state

State	Meaning
Draft	Registered but not listed on the Marketplace. Only you can deploy it.
Published	Live on the Marketplace. Any GMI user can discover and deploy it.
Unpublished	Removed from the Marketplace. Existing instances keep running but no new users can find it.

When the endpoint is ready, continue to List an agent to submit it for review.

​Register, launch, publish: three separate things

​Who pays when a user shows up

​The order that saves you trouble

​Choosing your path first

​Before you begin

​Why a Docker image

​What your image must do

​Getting your image into a registry

​Configure the GMI MaaS endpoint in your image

​Wizard steps

​Step 1: Basics & Template

​Step 2: Infrastructure

​Docker image source

​Registry URL

​Enable Credentials

​Compute tier

​Region

​MaaS integration

​Step 3: Networking

​Public IP address

​Port Mapping

​Step 4: Env Variables

​Auto-Injected by GMI

​Custom Variables

​Per-region overrides

​Step 5: Review & Register

​Review screen

​Register

​Self-hosted + MaaS (Path B)

​Step 4 · Review & Submit

​Managing your deployment

​Monitor tab

​Integration tab

​Analytics tab

​Launching an instance

​Authentication-key matrix

​Publishing state

Register, launch, publish: three separate things

Who pays when a user shows up

The order that saves you trouble

Choosing your path first

Before you begin

Why a Docker image

What your image must do

Getting your image into a registry

Configure the GMI MaaS endpoint in your image

Wizard steps

Step 1: Basics & Template

Step 2: Infrastructure

Docker image source

Registry URL

Enable Credentials

Compute tier

Region

MaaS integration

Step 3: Networking

Public IP address

Port Mapping

Step 4: Env Variables

Auto-Injected by GMI

Custom Variables

Per-region overrides

Step 5: Review & Register

Review screen

Register

Self-hosted + MaaS (Path B)

Step 4 · Review & Submit

Managing your deployment

Monitor tab

Integration tab

Analytics tab

Launching an instance

Authentication-key matrix

Publishing state