First Deployment - Hexel Studio

This guide walks through deploying a real agent end to end: preparing a compliant image, registering it, deploying an instance, calling it, and managing its lifecycle.

Concepts

Term	Meaning
Agent	A Docker image registered in Hexel, with a name and capabilities.
Instance	A running deployment of an agent with a permanent endpoint.
Permanent endpoint	A stable URL derived from the agent identity and configuration. Same configuration always resolves to the same URL.
Agent contract	The HTTP endpoints your image must serve: `/health`, `/.well-known/agent.json`, `/stream`, `/invoke`, `/execute`.

How it works

Register image  →  Deploy instance  →  Permanent endpoint  →  Call /stream or /invoke

When you deploy, Hexel pulls your image, starts it always-on with CPU throttling (idle instances cost almost nothing and wake in milliseconds), and assigns a permanent endpoint based on a hash of the agent and its configuration.

Step 1 — Prepare your image

Your Docker image must implement the agent contract. The platform handles authentication; your code never validates tokens. Listen on the port given by the AGENT_PORT environment variable (default 8080).

Endpoint	Method	Purpose
`/health`	GET	Returns `{"status": "ok"}` for health checks.
`/.well-known/agent.json`	GET	Agent manifest describing capabilities.
`/stream`	POST	Streaming response over Server-Sent Events.
`/invoke`	POST	Single blocking response.
`/execute`	POST	Run code or a command (for sandbox-style agents).

See Compute → Agents for the full contract and manifest format.

Step 2 — Register the agent

Python
CLI

from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

agent = client.compute.agent.register(
    name="support-agent",
    image="ghcr.io/your-org/support-agent:v1",
    capabilities=["chat", "streaming"],
)
print(agent["id"])

hexel compute agent register \
  --name support-agent \
  --image ghcr.io/your-org/support-agent:v1 \
  --capabilities "chat,streaming"

For images in a private registry, provide pull credentials at registration. See Compute → Agents.

Step 3 — Deploy an instance

Deploying an instance is done via the REST API or CLI. The SDK does not have a deploy method on client.compute.instance.

CLI
curl

hexel compute instance deploy YOUR_AGENT_ID --env-file .env

curl -X POST https://api.hexelstudio.com/compute/v1/agents/YOUR_AGENT_ID/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"env": {"MODEL": "gpt-4"}, "tier": "standard"}'

object

Key-value pairs injected as environment variables into the instance. Keep secrets in a secret manager and reference them at runtime.

string

Compute tier for the instance: micro, standard, large, or gpu. Defaults to standard.

The response includes the permanent endpoint and the instance ID:

string

Unique identifier for the deployed instance.

string

Permanent URL in the form https://agent-<name>-<hash>.compute.hexelstudio.com.

string

Initial state, typically deploying.

Step 4 — Call your agent

# Streaming
curl -N https://agent-support-agent-a1b2c3.compute.hexelstudio.com/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I reset my password?"}'

# Blocking
curl https://agent-support-agent-a1b2c3.compute.hexelstudio.com/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I reset my password?"}'

Step 5 — Manage the lifecycle

Use the SDK or CLI for instance management (list, get, stop, redeploy, delete):

Python
CLI

# List your instances
instances = client.compute.instance.list()

# Check instance state
instance = client.compute.instance.get("YOUR_INSTANCE_ID")
print(instance["state"])  # deploying | running | stopped | failed

# Roll out a new revision with the same settings (endpoint stays stable)
client.compute.instance.redeploy("YOUR_INSTANCE_ID")

# Stop or remove
client.compute.instance.stop("YOUR_INSTANCE_ID")
client.compute.instance.delete("YOUR_INSTANCE_ID")

hexel compute instance list
hexel compute instance get YOUR_INSTANCE_ID
hexel compute instance stop YOUR_INSTANCE_ID
hexel compute instance delete YOUR_INSTANCE_ID

Instances recover automatically if the underlying infrastructure fails, and the endpoint stays the same throughout. See Compute → Instances for instance states and Compute → Scaling to adjust capacity.

Common mistakes

Image missing the agent contract. Health checks fail and the instance stays in deploying. Verify /health and the manifest first.
Expecting a new URL per deploy. Identical configuration returns the same endpoint by design; change configuration to get a new one.
Putting secrets in capabilities or the image. Pass runtime configuration through env and use a secret manager for sensitive values.

Best practices

Tag images with explicit versions (:v1, :v2) rather than :latest.
Keep a separate environment for staging and production deployments.
Use redeploy to roll out revisions so the endpoint stays stable for callers.

Agents

The agent contract and registration options.

Instances

Endpoints, states, and instance management.

Scaling

Adjust capacity for production load.

Orchestration

Coordinate multiple agents with fleets and tasks.

Next steps

Explore Core Concepts to understand how agents, fleets, tasks, and tools fit together, or follow the New User learning path to production readiness.

​Concepts

​How it works

​Step 1 — Prepare your image

​Step 2 — Register the agent

​Step 3 — Deploy an instance

​Step 4 — Call your agent

​Step 5 — Manage the lifecycle

​Common mistakes

​Best practices

​Related pages

Agents

Instances

Scaling

Orchestration

​Next steps

Concepts

How it works

Step 1 — Prepare your image

Step 2 — Register the agent

Step 3 — Deploy an instance

Step 4 — Call your agent

Step 5 — Manage the lifecycle

Common mistakes

Best practices

Related pages

Next steps