# How free servers work

> What a free server includes, how it sleeps when empty and wakes when someone joins, and what it leaves out.

Source: https://docs.coritan.com/managed-containers/free-servers/

A *free server* is a server on the free plan. It runs only while someone uses it: it goes to sleep when nobody is playing and starts again when a player joins or when you wake it. Coritan does not sell the free plan on coritan.com, and an order for it answers `This plan is not sold here.` This page explains how a free server you already have behaves.

## Sleeping and waking

A free server stops after a set number of minutes without players. The default is 10 minutes, and it can be shorter while the machine is busy; the line under **This server is asleep** on the **Console** tab gives the current figure. A server you have just woken stays up for at least 10 minutes, so you have time to join. Stopping frees the memory for other servers, and your files stay where they are.

To start it again, open the server's **Console** tab and select **Wake server**, or join it from the game. **Start** does not work on a free server that is down: it answers `Free servers must be started via the wake endpoint, not a direct power start/restart`. **Restart** works while the server runs.

A wake goes through a start queue, so the machine is never asked to start more servers than it has room for:

- **Waiting for a free slot** means the start is queued. The banner shows your position, such as `Position 2 of 5 in the start queue.`, and the page updates by itself.
- **Starting your server** means your turn has come and the server is booting.
- When the machine is full, the banner says so, and the start waits in the queue until there is room.

If your account has hit a start limit, the banner asks you to complete a verification check before **Wake server** works.

## Joining a free server

A free server has no IP address or port of its own. Players join at its *join address*, a hostname that works for Java and Bedrock with no port to type. The dashboard does not show this address yet; the API returns it (see [With the API](#with-the-api)).

## What the free plan leaves out

| Feature | On a free server |
| --- | --- |
| Backups | Not included. Download your world from the file manager instead. |
| Databases | Not included. |
| Schedules | Not included. |
| Snapshots | Included, with room for one snapshot. |
| Snapshot download | Not included. Restore the snapshot onto any of your servers, or download files from the file manager. |
| Unused chunks | Always removed while the world sleeps: we delete chunks no player has ever visited, and the ground regenerates the same way if anyone goes there. A paid plan lets you turn this off. |

An action the plan leaves out answers `403` with `upgrade_required` set to `true` and a `message` that names the feature, such as `Databases are not included on the free plan. Upgrade to a paid plan to run plugins that need one.` The **Port slots** figure on the [Settings tab](/managed-containers/settings/) shows how many ports the plan allows.

## Free servers nobody uses

By default, we reclaim a free server that nobody joins or starts for three weeks:

- After 14 days without activity, we take a snapshot of the server and suspend it. A suspended server cannot be started from the dashboard.
- After 21 days without activity, we delete it.

Joining the server or starting it resets the count. To bring back a suspended free server before it is deleted, [contact support](https://www.coritan.com/dashboard/support). After deletion, the snapshot is your way back: [restore it onto another server](/snapshots/restore-a-snapshot/).

## With the API

`GET /api/v1/client/servers/{uuid}/sleep` returns the sleep state in `sleep` and the plan's features in `entitlements`. For a paid server, `sleep` is `{"policy": "none", "phase": "awake"}`.

```bash
curl https://api.coritan.com/api/v1/client/servers/$SERVER/sleep \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

In `sleep`, the fields you need are:

`phase`
: `awake`, `asleep`, `queued` or `starting`, or the server's status (`installing`, `transferring`, `install_failed` or `suspended`) when that stops it from running.

`idle_timeout_seconds`
: How long the server waits without players before it sleeps.

`sleeps_at`
: When the server will sleep if nobody joins, once that is certain; otherwise `null`.

`queue`
: While a wake is queued or starting, the `position`, the `total` in the queue and the `status`; otherwise `null`.

`capacity_available`
: Whether a start would be admitted right now. When it is `false`, `capacity_reason` says why.

`challenge_required`
: Whether a wake needs a verification token.

Each item in `entitlements` has a `feature`, `allowed`, `limit`, `reason`, `summary` and `detail`. For a free server, the item whose `feature` is `direct_endpoint` names the join address in its `summary` and `detail`.

`POST /api/v1/client/servers/{uuid}/wake` asks for a sleeping free server to start. Send an empty body, or `{"turnstile_token": "..."}` when `challenge_required` is `true`. The response is the new `sleep` state.

```bash
curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/wake \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

A paid server answers `409` with `This server does not sleep; use the power action to start it.` A server that is installing, moving, suspended or whose install failed answers `409` with its status. Wakes are limited to 48 per server in 60 seconds.

## API

- `GET /api/v1/client/servers/{uuid}/sleep`: Sleep and start-queue state for a free server (https://docs.coritan.com/api/reference/client/container-apps/servers/#op-get-api-v1-client-servers-uuid-sleep)
- `POST /api/v1/client/servers/{uuid}/wake`: Ask for a sleeping free server to be started (https://docs.coritan.com/api/reference/client/container-apps/servers/#op-post-api-v1-client-servers-uuid-wake)