# Grow the root filesystem into a bigger disk

Source: https://docs.imprezahost.com/filesystem-grow.html

When a resize gives your VPS a bigger disk, the new space is not used until
the root partition and its filesystem grow into it. This operation does
that **online**, as a host plan: the agent on your server prepares an exact
plan, a person approves it, and it is applied once.

**What it does:** it grows the root partition and its ext4 filesystem into
space **the disk already has**. Nothing shrinks, formats or reboots, and the
growth **cannot be rolled back**.

**What it does not do:**

- It does not make the disk bigger. That is the VPS resize of your plan; do
  it first.
- It does not work outside the validated combination below.

**Take a backup or snapshot of the server first.** An application backup
does not restore partitions or the system.

## Before you start

- An **Impreza VPS**. On a server outside Impreza, ownership of the disk is
  unproven and the plan is refused.
- **Impreza agent 0.6.39 or later.** Earlier agents do not offer this
  operation. [Update the agent](agent-updates.html) first.
- **Ubuntu 24.04 (amd64)**, with the root on a plain **ext4** partition that
  is the **last** partition on a virtio disk. LVM, encryption and any
  other layout are refused before anything changes.
- **Free space on the disk** after the root partition, from a resize that
  already finished.
- The tools `growpart`, `resize2fs`, `dumpe2fs` and `sfdisk` at their standard
  paths. Ubuntu 24.04 cloud images include them.
- **The local opt-in on the server.** As root, create
  `/var/lib/impreza-agent/filesystem-grow-policy.json` with mode `0600`:

  ```json
  {"enabled":true,"agent_id":"<your agent ID>"}
  ```

  The agent ID is the `agent_id` in `/etc/impreza-agent/config.toml`. Without
  this file the agent does not offer the operation, and the opt-in is never
  accepted from the API or the portal.
- **The owner's grant.** In the portal, open **Human approvals**, section
  **Plan-bound host permissions**, and grant **Root filesystem growth** for
  the credential and the server. Only the account owner can grant it.
- **An API key with the `manage` scope.** The steps below use the REST API;
  the MCP host-plan tools do not offer this operation.

## Grow the filesystem

1. **Prepare the plan:**

   ```http
   POST /v1/host/plans
   {"service_id": <your service ID>, "operation": "managed_host.filesystem_grow"}
   ```

   `ttl_seconds` is optional, from 300 to 3600 (default 900). The answer
   starts in `planning`: nothing changes on the server yet, the agent only
   reads the disk.
2. **Read the plan** with `GET /v1/host/plans/{plan_id}` until it is
   `prepared`. It then shows:
   - the `plan_digest`;
   - the `approval_id` of the human approval;
   - a summary: the `mode`, the partition, and the disk, partition,
     filesystem and available sizes, in bytes.

   The `mode` is `partition_and_filesystem`, or `filesystem_only` when the
   partition is already the full size and only the ext4 still has to grow.
3. **A person approves** that exact plan in the portal, in **Human
   approvals**. Check that the digest shown matches the `plan_digest`. The
   API cannot approve.
4. **Apply the approved plan, once:**

   ```http
   POST /v1/host/plans/{plan_id}/apply
   {"plan_id": "<plan_id>", "plan_digest": "<plan_digest>", "approval_id": "<approval_id>"}
   ```

   Sending the same apply again returns the plan as it is, without a second
   effect.

5. **Read the plan** until it settles. While the agent works it is
   `submitted`; a successful apply ends in `completed`.

## Results

| `status` | Meaning |
| --- | --- |
| `completed` | The partition and the ext4 grew into the free space. |
| `refused` | Nothing changed: the agent refused before any effect. |
| `partial` | The growth stopped halfway, or its outcome is uncertain. **Do not repeat this plan.** The server stays reserved for this operation while the reservation holds, but you can recover it yourself: prepare a new plan for the same server (below), which grows only what is missing. |
| `recovered` | This plan had stopped halfway, and a later recovery plan finished the growth. The plan is closed; nothing else is pending on it. |
| `uncertain` | The apply was sent, but the agent did not report a result before the plan's expiry. The server stays reserved. **Do not repeat the plan.** Contact support with the `plan_id`. |
| `expired` | The agent did not return the plan in time. Nothing changed. A prepared plan that is not applied before its expiry can no longer be applied; prepare a new one. |

When the agent refuses while preparing the plan, the plan's `refusal`
field names the reason. The agent refuses before any effect when, for
example:

- the root is not the last partition (`root_not_last_partition`);
- the ext4 is not clean (`filesystem_not_clean`);
- the kernel's view of the disk is stale (`kernel_view_stale`);
- there is nothing to grow (`nothing_to_grow`).

## Recover a partial growth

A growth that stopped halfway (`partial`) is recovered in self-service —
by the same steps as a normal growth:

1. **Prepare a new plan** for the same `service_id`
   (`POST /v1/host/plans`). A `partial` growth does not block the new plan:
   the agent reads what the interrupted growth left on the server and
   plans only what is missing, with the `mode` `filesystem_only` — when
   the partition already grew, only the ext4 still has to grow. Do not
   repeat the old plan; the recovery is this new one.
2. **A person approves** it and you **apply it once**, exactly as above.
3. When the recovery completes, the old `partial` plan closes as
   `recovered` — the plan you read shows it, so you can tell the two
   apart.

A growth that is still `submitted` (or `uncertain`) keeps the server
reserved for this operation, and a new plan is refused with
`HOST_OPERATION_IN_PROGRESS` until it settles. A `partial` of another
host operation on the same server also keeps its reservation. Partial
growths count toward the grant's pending limit while they wait for their
recovery.

## Limits

- One filesystem growth at a time per server. Plans count against the
  grant's limits per credential and day.
- The growth is not reversible. A smaller disk is not supported.
- The plan only grows the root partition and its ext4. It does not touch
  other partitions, other disks or any application data.