Instances - Hexel Studio

An instance is a running deployment of a registered agent. Each instance receives a permanent endpoint that stays the same across redeployments, so callers never need to update a URL. When you deploy an agent, the platform creates a running instance at a stable URL. That URL stays fixed even when you roll out new code, so downstream callers and integrations never need to update their configuration.

Permanent endpoints

Each unique configuration produces a unique, stable URL:

https://agent-<name>-<hash>.compute.hexelstudio.com

The endpoint is derived deterministically from the agent identity and its configuration. Same agent + same configuration always produces the same endpoint; different configuration produces a different endpoint. Redeploying with identical settings returns the same endpoint.

Instance states

State	Meaning
`deploying`	The instance is starting up, pulling the image and running health checks.
`running`	Healthy and serving traffic.
`stopped`	Manually stopped via `stop`.
`failed`	Could not start, or became unhealthy after running.

If the underlying infrastructure fails, the platform recovers the instance automatically. The endpoint stays the same throughout.

SDK methods

Method	Description
`client.compute.instance.list()`	List all instances.
`client.compute.instance.get(id)`	Get instance details and state.
`client.compute.instance.stop(id)`	Stop a running instance.
`client.compute.instance.redeploy(id)`	Roll out a new revision (endpoint stays stable).
`client.compute.instance.delete(id)`	Delete a stopped instance.

There is no client.compute.instance.deploy() in the SDK. Deploy via the REST API or CLI as shown below.

Deploy an instance

Deploying is done via the REST API or CLI:

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"
  }'

Deploy request parameters

object

Key-value pairs injected as environment variables. Keep secrets in a secret manager rather than hardcoding them here.

string

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

Deploy response

string

Unique instance identifier.

string

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

string

Initial state (deploying).

string

The agent this instance belongs to.

string

Compute tier assigned.

Call your agent

Once the instance reaches running:

# Streaming response (Server-Sent Events)
curl -N https://agent-my-agent-abc123.compute.hexelstudio.com/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello"}'

# Blocking response
curl https://agent-my-agent-abc123.compute.hexelstudio.com/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello"}'

Manage instances

Python
CLI

from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

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

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

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

# Stop a running instance
client.compute.instance.stop("YOUR_INSTANCE_ID")

# Delete a stopped instance
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

What happens on redeploy?

The platform pulls the latest version of the registered image, restarts the instance, and runs health checks. The permanent endpoint stays the same. Traffic is routed to the new revision once health checks pass.

Can I deploy multiple instances of the same agent?

Yes. Each unique configuration (agent + env) produces its own permanent endpoint and instance.

What if my instance stays in deploying?

The image likely doesn’t implement /health correctly. Check that your server starts on AGENT_PORT (default 8080) and returns HTTP 200 from GET /health.

What if the tier is unavailable?

Deployment returns HTTP 503. The platform does not fall back to a different tier. Retry later or choose a different tier.

Limits & quotas

Limit	Scope	Behavior
Concurrent running instances	Per organization	Plan-enforced.
Replicas per instance	Per instance	Adjust with scaling.

Numeric limits depend on your plan — see the Console.

Errors

`error_code`	HTTP	When
`invalid_request`	400	Invalid `env` or deploy configuration.
`not_found`	404	The agent or instance ID doesn’t exist.
`forbidden`	403	Credentials lack permission for this workspace.
`capacity_exhausted`	503	No capacity for the requested tier. Retry shortly.
`internal_error`	500	Transient platform error. Retry or contact support.

Security

Concern	Detail
Authentication	The platform authenticates all traffic to an instance’s endpoint. Your agent code never validates tokens.
Secrets	Pass runtime secrets through `env` sourced from a secret manager. Do not bake credentials into the image.
Scoping	Instances are scoped to your organization, workspace, and environment.

Production recommendations

Roll out new revisions with redeploy so the permanent endpoint stays stable for callers.
Watch instance logs and metrics during and after rollouts.
Set alerts on the failed state and on latency regressions.
Keep production and development instances in separate environments.

Common mistakes

Expecting a new endpoint on every deploy. Identical configuration returns the same endpoint by design.
Treating failed as permanent. Fix the image or configuration and redeploy.
Baking secrets into configuration. Use a secret manager and reference values at runtime.

Best practices

Use redeploy for new revisions so callers keep the same endpoint.
Watch logs and metrics during rollouts.
Keep production and development instances in separate environments.

Agents

Scaling

Adjust capacity under load.

Runtime Lifecycle

Recovery and runtime leases.

First Deployment

The full deploy walkthrough.

Next steps

Continue to Scaling to handle production load.

​Permanent endpoints

​Instance states

​SDK methods

​Deploy an instance

​Deploy request parameters

​Deploy response

​Call your agent

​Manage instances

​Limits & quotas

​Errors

​Security

​Production recommendations

​Common mistakes

​Best practices

​Related pages

Agents

Scaling

Runtime Lifecycle

First Deployment

​Next steps

Permanent endpoints

Instance states

SDK methods

Deploy an instance

Deploy request parameters

Deploy response

Call your agent

Manage instances

Limits & quotas

Errors

Security

Production recommendations

Common mistakes

Best practices

Related pages

Next steps