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

# Instances

> Deploy agents to permanent endpoints and manage their lifecycle.

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

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/instance-lifecycle.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=6c8bffe1f028d864959a73975fd170ff" alt="Instance lifecycle" width="1777" height="885" data-path="assets/diagrams/instance-lifecycle.png" />

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

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

## Deploy an instance

Deploying is done via the REST API or CLI:

<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>

### Deploy request parameters

<ParamField path="env" type="object">
  Key-value pairs injected as environment variables. Keep secrets in a secret manager rather than hardcoding them here.
</ParamField>

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

### Deploy response

<ResponseField name="instance_id" type="string">Unique instance identifier.</ResponseField>
<ResponseField name="endpoint" type="string">Permanent URL: `https://agent-<name>-<hash>.compute.hexelstudio.com`.</ResponseField>
<ResponseField name="state" type="string">Initial state (`deploying`).</ResponseField>
<ResponseField name="agent_id" type="string">The agent this instance belongs to.</ResponseField>
<ResponseField name="tier" type="string">Compute tier assigned.</ResponseField>

## Call your agent

Once the instance reaches `running`:

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

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I deploy multiple instances of the same agent?">
    Yes. Each unique configuration (agent + env) produces its own permanent endpoint and instance.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Limits & quotas

| Limit                        | Scope            | Behavior                                 |
| ---------------------------- | ---------------- | ---------------------------------------- |
| Concurrent running instances | Per organization | Plan-enforced.                           |
| Replicas per instance        | Per instance     | Adjust with [scaling](/docs/compute/scaling). |

Numeric limits depend on your plan — see the [Console](https://console.hexelstudio.com).

## 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](/docs/observability/logs) and [metrics](/docs/observability/metrics) during and after rollouts.
* Set alerts on the `failed` state and on latency regressions.
* Keep production and development instances in separate [environments](/docs/iam/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](/docs/observability/logs) and [metrics](/docs/observability/metrics) during rollouts.
* Keep production and development instances in separate [environments](/docs/iam/environments).

## Related pages

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/docs/compute/agents">
    Register images and the agent contract.
  </Card>

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

  <Card title="Runtime Lifecycle" icon="arrows-rotate" href="/docs/compute/runtime-lifecycle">
    Recovery and runtime leases.
  </Card>

  <Card title="First Deployment" icon="rocket" href="/docs/getting-started/first-deployment">
    The full deploy walkthrough.
  </Card>
</CardGroup>

## Next steps

Continue to [Scaling](/docs/compute/scaling) to handle production load.