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

# Scaling

> Adjust instance capacity to match production load.

Instances run always-on with CPU throttling, so they wake in milliseconds and cost little when idle. As traffic grows, you can scale capacity to handle more concurrent load.

## Tiers

Two different problems call for two different solutions. If traffic is growing and requests are queuing up, you need more replicas — that's horizontal scaling (covered below). If a single request is slow because the workload itself is heavy (large model inference, complex data transforms), you need a larger tier with more CPU or memory. The tier table below helps you pick the right baseline for each instance.

Each instance runs on a tier that sets its baseline CPU and memory:

| Tier       | CPU       | Memory  | GPU | Best for                          |
| ---------- | --------- | ------- | --- | --------------------------------- |
| `micro`    | 0.25 vCPU | 256 MiB | —   | Lightweight agents, quick tasks   |
| `standard` | 0.5 vCPU  | 512 MiB | —   | Most agents and sandboxes         |
| `large`    | 1 vCPU    | 1 GiB   | —   | Heavier processing, RAG pipelines |
| `gpu`      | 2 vCPU    | 2 GiB   | 1   | GPU-accelerated workloads         |

<Warning>
  If the requested tier has no capacity, the deploy or scale operation returns HTTP `503`. The platform does not fall back to a different tier.
</Warning>

## Scaling via the API

Scale a running instance to adjust replicas. The permanent endpoint stays the same and load is distributed across replicas.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"dark"}
    hexel compute instance scale YOUR_INSTANCE_ID --replicas 3
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    curl -X POST https://api.hexelstudio.com/compute/v1/instances/YOUR_INSTANCE_ID/scale \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"replicas": 3}'
    ```
  </Tab>
</Tabs>

### Parameters

<ParamField path="replicas" type="integer" required>
  Number of replicas to run behind the permanent endpoint.
</ParamField>

### Response

<ResponseField name="instance_id" type="string">The scaled instance.</ResponseField>
<ResponseField name="replicas" type="integer">Current replica count after scaling.</ResponseField>
<ResponseField name="state" type="string">Instance state (remains `running`).</ResponseField>

## Choosing a tier

| Scenario                                      | Recommended tier |
| --------------------------------------------- | ---------------- |
| Simple request routing, lightweight logic     | `micro`          |
| General-purpose agents, chat, tooling         | `standard`       |
| Retrieval-heavy or data-processing agents     | `large`          |
| Model inference, embeddings, image processing | `gpu`            |

If a single request is slow, a larger tier may help more than additional replicas. If throughput (concurrent requests) is the bottleneck, increase replicas.

<AccordionGroup>
  <Accordion title="Does scaling change the endpoint?">
    No. The permanent endpoint stays the same. Traffic is balanced across replicas.
  </Accordion>

  <Accordion title="Can I scale to zero?">
    Use `stop` to halt all traffic. Scaling to zero replicas is equivalent to stopping the instance.
  </Accordion>

  <Accordion title="What happens if I choose a tier that's unavailable?">
    The operation returns HTTP 503. Retry after a delay or choose a different tier.
  </Accordion>
</AccordionGroup>

## Limits & quotas

| Limit                     | Scope            | Behavior               |
| ------------------------- | ---------------- | ---------------------- |
| Replicas per instance     | Per instance     | Plan-enforced ceiling. |
| Total concurrent replicas | Per organization | Plan-enforced.         |

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

## Errors

| `error_code`         | HTTP | When                                                  |
| -------------------- | ---- | ----------------------------------------------------- |
| `invalid_request`    | 400  | Invalid replica count.                                |
| `not_found`          | 404  | The instance ID doesn't exist.                        |
| `capacity_exhausted` | 503  | No capacity to add replicas right now. Retry shortly. |

## Common mistakes

* **Scaling instead of choosing the right tier.** If a single request is slow, a larger tier helps more than more replicas.
* **Over-provisioning early.** Scale to observed load, not anticipated peaks.

## Best practices

* Watch [metrics](/docs/observability/metrics) before and after scaling.
* Scale based on concurrency and latency, not raw request counts alone.
* Keep production and development instances on separate environments.

## Related pages

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

  <Card title="Runtime Lifecycle" icon="arrows-rotate" href="/docs/compute/runtime-lifecycle">
    How instances stay healthy and recover.
  </Card>

  <Card title="Metrics" icon="chart-line" href="/docs/observability/metrics">
    Measure load and latency.
  </Card>

  <Card title="Tiers & Limits" icon="gauge" href="/docs/billing/tiers-and-limits">
    Tier capacities and account limits.
  </Card>
</CardGroup>

## Next steps

Continue to [Sessions & Filesystems](/docs/compute/sessions-and-filesystems).