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

# Runtime Lifecycle

> How instances start, stay healthy, recover, and use runtime leases.

Understanding the runtime lifecycle helps you build agents that stay healthy in production and recover automatically when things go wrong. Knowing what happens at each stage — startup, health checking, failure, recovery — lets you design containers that cooperate with the platform instead of fighting it.

This page explains how a Compute instance behaves over its lifetime — from deployment through healthy operation, automatic recovery, and the runtime leases that grant time-bounded execution.

## Instance states

| State       | Meaning                                                                           |
| ----------- | --------------------------------------------------------------------------------- |
| `deploying` | Image is being pulled and the instance is starting up. Health checks are pending. |
| `running`   | Healthy and serving traffic.                                                      |
| `stopped`   | Manually stopped via `stop`.                                                      |
| `failed`    | Could not start, or became unhealthy after reaching `running`.                    |

<Note>
  There is no `restarting` state. Automatic recovery transitions an instance from `failed` back to `deploying`, then to `running` once health checks pass again.
</Note>

## State transitions

```mermaid theme={"dark"}
stateDiagram-v2
    [*] --> deploying: deploy
    deploying --> running: health checks pass
    deploying --> failed: startup error
    running --> stopped: stop
    running --> failed: unhealthy
    stopped --> deploying: redeploy
    failed --> deploying: redeploy / auto-recover
    stopped --> [*]: delete
```

## How deployment works

<Steps>
  <Step title="Image pull">
    The platform pulls the registered Docker image.
  </Step>

  <Step title="Start container">
    The container starts on the assigned tier. `AGENT_PORT` (default 8080) is injected.
  </Step>

  <Step title="Health checks">
    The platform polls `GET /health`. Once it returns HTTP 200, the instance transitions to `running`.
  </Step>

  <Step title="Serve traffic">
    The permanent endpoint begins routing requests to the instance.
  </Step>
</Steps>

## Automatic recovery

If the underlying infrastructure fails or the instance becomes unhealthy, the platform:

1. Detects the failure via health checks.
2. Transitions the instance to `failed`.
3. Automatically attempts recovery (re-pulls image, restarts container).
4. Once health checks pass again, the instance returns to `running`.

The permanent endpoint stays the same throughout. Callers don't need to change anything.

## Runtime leases

For orchestrated execution, the platform allocates resources on your behalf when you submit a task. These resources are time-bounded — if the work completes or times out, they are released automatically.

You don't manage leases directly; the orchestration layer handles them when you submit tasks.

## Check instance state

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    from hexel import Hexel

    client = Hexel(api_key="YOUR_API_KEY")

    instance = client.compute.instance.get("YOUR_INSTANCE_ID")
    print(instance["state"])  # deploying | running | stopped | failed
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    hexel compute instance get YOUR_INSTANCE_ID
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="How long do health checks wait before marking an instance failed?">
    The platform runs health checks with a startup grace period. If `/health` doesn't return 200 within the grace period, the instance transitions to `failed`. Exact timeout depends on the tier.
  </Accordion>

  <Accordion title="Does automatic recovery have a retry limit?">
    Yes. If recovery fails repeatedly, the instance stays in `failed` and requires manual intervention (fix the image, then `redeploy`).
  </Accordion>

  <Accordion title="What if my /health endpoint is slow?">
    Keep `/health` cheap and fast (under 100ms). A slow health check can cause false-positive failures during recovery.
  </Accordion>
</AccordionGroup>

## Errors

| `error_code`         | HTTP | When                           |
| -------------------- | ---- | ------------------------------ |
| `instance_not_found` | 404  | The instance ID doesn't exist. |

## Common mistakes

* **Treating `failed` as permanent.** Check that the image implements the agent contract and passes `/health`, then redeploy.
* **Polling for readiness too aggressively.** Health checks take a moment after `deploying`; back off between checks.
* **Heavy work in `/health`.** Health checks run frequently; keep them lightweight.

## Best practices

* Make `/health` return quickly with no side effects.
* Use `redeploy` for new revisions so the endpoint stays stable.
* Monitor instance state and logs during rollouts.

## Related pages

<CardGroup cols={2}>
  <Card title="Instances" icon="server" href="/docs/compute/instances">
    Deploy and manage instances.
  </Card>

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

  <Card title="Logs" icon="file-lines" href="/docs/observability/logs">
    Inspect what an instance is doing.
  </Card>

  <Card title="Orchestration" icon="sitemap" href="/docs/orchestration/overview">
    How leases back orchestrated execution.
  </Card>
</CardGroup>

## Next steps

Explore the [Data Platform](/docs/data-platform/overview) to give your agents knowledge and memory.