> ## Documentation Index
> Fetch the complete documentation index at: https://hexelstudio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# First Deployment

> Take an agent from a Docker image to a live, permanent endpoint.

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](/docs/compute/agents) for the full contract and manifest format.

## Step 2 — Register the agent

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    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"])
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    hexel compute agent register \
      --name support-agent \
      --image ghcr.io/your-org/support-agent:v1 \
      --capabilities "chat,streaming"
    ```
  </Tab>
</Tabs>

For images in a private registry, provide pull credentials at registration. See [Compute → Agents](/docs/compute/agents#private-registries).

## 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`.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"dark"}
    hexel compute instance deploy YOUR_AGENT_ID --env-file .env
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    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"}'
    ```
  </Tab>
</Tabs>

<ParamField path="env" type="object">
  Key-value pairs injected as environment variables into the instance. Keep secrets in a secret manager and reference them at runtime.
</ParamField>

<ParamField path="tier" type="string">
  Compute tier for the instance: `micro`, `standard`, `large`, or `gpu`. Defaults to `standard`.
</ParamField>

The response includes the permanent endpoint and the instance ID:

<ResponseField name="instance_id" type="string">Unique identifier for the deployed instance.</ResponseField>
<ResponseField name="endpoint" type="string">Permanent URL in the form `https://agent-<name>-<hash>.compute.hexelstudio.com`.</ResponseField>
<ResponseField name="state" type="string">Initial state, typically `deploying`.</ResponseField>

## Step 4 — Call your agent

```bash theme={"dark"}
# 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):

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    # 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")
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    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
    ```
  </Tab>
</Tabs>

Instances recover automatically if the underlying infrastructure fails, and the endpoint stays the same throughout. See [Compute → Instances](/docs/compute/instances) for instance states and [Compute → Scaling](/docs/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.

## Related pages

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/docs/compute/agents">
    The agent contract and registration options.
  </Card>

  <Card title="Instances" icon="server" href="/docs/compute/instances">
    Endpoints, states, and instance management.
  </Card>

  <Card title="Scaling" icon="up-right-and-down-left-from-center" href="/docs/compute/scaling">
    Adjust capacity for production load.
  </Card>

  <Card title="Orchestration" icon="sitemap" href="/docs/orchestration/overview">
    Coordinate multiple agents with fleets and tasks.
  </Card>
</CardGroup>

## Next steps

Explore [Core Concepts](/docs/concepts/overview) to understand how agents, fleets, tasks, and tools fit together, or follow the [New User learning path](/docs/learn/new-user) to production readiness.