> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinematic.run/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the customer docs for kinematic, a name written in lowercase except at the start of a sentence. Kinematic provides provably fair casino games, served to a casino's site by a game server: a Cloudflare Worker that the kinematic dashboard deploys into the casino's own Cloudflare account.
> Never put SESSION_SECRET or WALLET_SECRET in code, prompts, logs, commits or chat. Read them from environment variables and ask the person you work with to set them. The dashboard's Integration page shows each secret once.
> Values such as lucky-star, luckystar.example, og-rgs-lucky-star.luckystar.workers.dev, games.luckystar.example and player_48213 are examples. Use the casino's own casino ID, game server origin, element tag, session issuer and currencies: the Instructions for your coding agent on the dashboard's Integration page hold them, or ask the person you work with.
> To debug, start at https://docs.kinematic.run/troubleshooting and https://docs.kinematic.run/reference/errors. The wallet contract is at https://docs.kinematic.run/api/wallet.openapi.yaml.
> Sandbox bets are recorded on Solana devnet. Live game servers record nothing on Solana until the audited mainnet program is deployed.

# Game server

> Connect Cloudflare, deploy your game server on workers.dev or your own hostname, and run it: its card, deploys and updates, new bets and the Solana record.

Your game server is a Cloudflare Worker that the dashboard deploys into your own Cloudflare account. You deploy and run it on the **Game server** page. [Your game server](https://docs.kinematic.run/concepts/game-server.md) explains what runs in your account.

The page has two states:

* **Before your first game server**, it shows two steps: **Connect Cloudflare** and **Choose where it runs**.
* **Once a game server exists**, it shows a card for each game server, then the sections **New bets** and **Solana record** (once a game server has deployed) and **Cloudflare**.

Owners and admins connect Cloudflare, deploy, update, remove a game server, check it with **Check now** and **Check Solana**, stop new bets and register keys. Members see the game servers, their newest errors and their Solana record, with `Only the casino's owners and admins can deploy, check and change the game server.` Until you finish setting up your casino, the page shows `Finish setting up your casino before you deploy your game server.` with **Continue setup**.

## Connect Cloudflare

**1. Select Connect Cloudflare**

In the step **Connect Cloudflare**, select **Connect Cloudflare**. The page says `You approve the access on Cloudflare's own page.` and lists the permissions under **What you approve**.

**2. Approve on Cloudflare**

Sign in to Cloudflare if it asks, choose the accounts the dashboard may use, and approve. If you decline, the page says `You declined in Cloudflare. Nothing changed.`

**3. Check the connection**

Back on **Game server**, the page says `Cloudflare is connected.` The step becomes **Cloudflare is connected** and shows `Connected as <your Cloudflare email>`, with the accounts the connection reaches, the date and who connected it.

The dashboard asks for six permissions:

| Permission | What the page says |
| - | - |
| `account-settings.read` | Read your accounts, so you choose the one to deploy to. |
| `user-details.read` | Read your Cloudflare email, shown on this page. |
| `workers-scripts.admin` | Create and update your game server's Worker: its code, secrets and workers.dev address. |
| `workers-routes.write` | Put your game server on a hostname of yours, when you choose one. |
| `zone.read` | Read your zones, to put your game server on a hostname of yours. |
| `offline_access` | Keep access between your visits, so new releases reach your game server while you are away. |

Under the list, the page says `The game servers you deploy belong to your account. Disconnecting stops new deploys from this dashboard and leaves them running.` Once you have a game server, the section **Cloudflare** shows the connection and the same list under **What you authorized**.

### Reconnect and disconnect

The dashboard keeps its access between your visits. If Cloudflare refuses to renew it, the page shows `Cloudflare refused to renew access. Reconnect to deploy and update your game servers.` with **Reconnect**, the connection shows **Reconnect needed**, and **Game server** in the sidebar shows **Reconnect**. Your game servers keep running; you cannot deploy or update them until you reconnect.

The connection's menu has three items:

* **Check connection** asks Cloudflare and answers, for example, `The connection works. It reaches 1 account.`
* **Reconnect** opens Cloudflare's page again, so you approve again.
* **Disconnect** asks `Disconnect Cloudflare?` first. Your game servers keep running and serving players. Until you connect again, you cannot deploy them, and automatic updates wait. Disconnecting revokes the dashboard's access to your account. Select **Disconnect** to confirm, or **Keep it connected**.

## Create a game server

Once Cloudflare is connected, the step **Choose where it runs** shows the form. To add another game server later, select **Add a game server** at the top of the page: `It runs from the same settings as your other game servers, in another account or on another address.`

**1. Choose the account**

In **Cloudflare account**, pick the account the game server runs in. The list holds the accounts you approved.

**2. Name the Worker**

**Worker name** is the Worker's name in your Cloudflare account. It starts as `og-rgs-<casino ID>`, for example `og-rgs-lucky-star`, with `-2`, `-3` and so on added when one of your game servers already has that name. A name has 1 to 63 lowercase letters, digits and hyphens, and does not start or end with a hyphen. The form refuses:

* a name that breaks these rules: `Use 1–63 lowercase letters, digits and inner hyphens.`
* a Worker that already exists in the account: `Your account already has a Worker named <name>. Choose another name.`
* a name another game server of yours uses in the account: `A game server with this name exists in this account. Choose another name.`

**3. Choose the address**

Under **Address**, choose **workers.dev** or **Your own hostname**. For your own hostname, type it in **Hostname**, such as `games.luckystar.example`. See [Choose an address](#choose-an-address).

**4. Keep automatic updates**

Leave **Update automatically** on: `New releases reach this game server within five minutes. You can turn this off later.`

**5. Deploy**

Select **Deploy**. The caption names the release and the account. The page shows `Deploying <Worker name>` with a running clock: it takes about a minute, so keep the page open until it finishes. When it succeeds, the page says `Deployed. Your game server runs release <release>.` and shows the game server's card, first with **Waiting for its first report**, then **Reporting**.

Copy the game server's address from its card with **Copy the address**: it goes into your [embed](https://docs.kinematic.run/integrate/embed.md) and your [CSP](https://docs.kinematic.run/integrate/csp.md).

A game server that never deployed can be removed with **Remove**, in its card's menu or under its note. The dialog `Remove <Worker name>?` says `It never deployed, so nothing runs from it. If an attempt left a Worker of this name in your Cloudflare account, delete it there too.` A game server that has deployed stays on the page.

## Choose an address

Your game server is a Worker in your Cloudflare account, so its address belongs to that account too.

### workers.dev

The address is `https://<Worker name>.<your subdomain>.workers.dev`, for example `https://og-rgs-lucky-star.luckystar.workers.dev`. The form previews it as you type the Worker name. Nothing else is needed, as long as the account has a workers.dev subdomain.

An account gets its workers.dev subdomain the first time someone opens **Workers & Pages** in its Cloudflare dashboard. If it has none, the form says `This account has no workers.dev subdomain yet. Open Workers & Pages once in its Cloudflare dashboard to create one, or use your own hostname.` with the link **How to create the subdomain**. See [There is no workers.dev subdomain](https://docs.kinematic.run/troubleshooting.md#there-is-no-workers-dev-subdomain).

### Your own hostname

Use a hostname such as `games.luckystar.example` when you want players' browsers to see your domain. Under **Hostname**, the form says:

`This hostname's domain must use Cloudflare DNS in the account above, with no record for the hostname yet, because Cloudflare creates that record for your game server. If your DNS is elsewhere, start on workers.dev and add a game server on your hostname later.`

The dashboard attaches the hostname to the Worker as a Cloudflare Workers custom domain, and Cloudflare creates the hostname's DNS record and its certificate. The hostname must meet four conditions:

1. **Its domain is a zone in the same Cloudflare account** as the game server. A domain in another Cloudflare account, or at another DNS provider, does not work.
2. **The zone is active.** Cloudflare marks a zone active once the domain uses Cloudflare's nameservers.
3. **The hostname has no DNS record yet.** Delete an existing record for that exact hostname first, or choose another hostname.
4. **No other game server of your casino serves the hostname.**

The form checks conditions 1, 2 and 4 before it deploys; Cloudflare checks condition 3 during the deploy. [The deploy fails on your own hostname](https://docs.kinematic.run/troubleshooting.md#the-deploy-fails-on-your-own-hostname) lists every message and its fix.

If your domain's DNS is not on Cloudflare yet:

**1. Add the domain to the account**

In the Cloudflare dashboard of the account the game server runs in, add your domain, for example `luckystar.example`. Cloudflare imports the DNS records it finds; check that every record your domain needs is there before the next step.

**2. Point the domain at Cloudflare**

At your domain's registrar, replace its nameservers with the two that Cloudflare shows. Wait until Cloudflare marks the zone **Active**.

**3. Deploy on the hostname**

Create the game server with your hostname. Cloudflare creates the DNS record for `games.luckystar.example` and its certificate.

If you cannot move your domain's DNS to Cloudflare, use the workers.dev address. You can add a game server on your hostname later.

## The game server's card

Each game server has a card. Its heading is the game server's address, which opens in a new tab, with **Copy the address** beside it. Under the address, the card shows the game server's state, `Last report <time ago>` and a badge with the mode it runs: **Live** or **Sandbox**.

| State | Means |
| - | - |
| **Reporting** | The game server reported within the last 5 minutes. |
| **Not reporting** | It has not reported for more than 5 minutes. |
| **Waiting for its first report** | It deployed and has not reported yet. After 5 minutes without a report, the card shows **No report yet**. |
| **Deploying** | A deploy is running. |
| **Deploy failed** | Its first deploy failed, so it does not run. |
| **Not deployed** | It was created and never deployed. |

The card also lists **Release** (marked **Latest** or **Update available**), **Last deploy**, **Account** and **Worker**. Owners and admins turn **Update automatically** on or off at the bottom of the card.

**Check now** asks the game server at once and shows its answer in **Live status**: whether it accepts **New bets**, the **Settings** it holds, its **Release**, its **Mode**, how often it sends **Reports**, and its **Solana record**. When the game server refuses its settings, a line starts with `Settings:` and gives the reason, for example `Settings: The settings are for the other mode. A mode switch takes effect when you redeploy the game server.` [Game server settings](https://docs.kinematic.run/reference/errors.md#game-server-settings) lists every reason. When the game server does not answer, the card says why, for example `Your game server could not be reached.`

The card's menu holds:

* **Redeploy**: deploys the same release again, in your casino's mode. It is hidden while the game server waits for a mode switch.
* **Deploy history**: every deploy, update, mode switch and change of secrets, newest first, with who started it (`Auto-update` for automatic updates), the release and the result. A failed row shows Cloudflare's error.
* **Open in Cloudflare**: the Worker in your Cloudflare dashboard.
* **Remove**: only for a game server that never deployed.

When something needs your attention, the card shows a note. The notes that ask you to act are below. Others say that a game server has gone quiet, for example `It sent its last report <time ago>. Check now asks it at once.`, or that it refused its settings: `Your game server fetched its settings and did not apply them, so it refuses new bets. Check now names the setting it refused.`

### Newest errors

When a game server has reported errors, its card lists them under **Newest errors**, the most recent first. Each code shows once, with its sentence, such as `wallet_timeout` with `Your wallet did not answer in time.` It also shows the detail of its newest report, such as `debit job 7, attempt 3` for a wallet call or the field the game server refused in its settings, how many came in the last 24 hours and when the last one came.

**Read the fix** opens [Bets stay open](https://docs.kinematic.run/troubleshooting.md#bets-stay-open) for a wallet that fails or answers late. **About this code** opens the part of [Errors](https://docs.kinematic.run/reference/errors.md) that explains the code: [Your wallet's calls](https://docs.kinematic.run/reference/errors.md#your-wallets-calls), [Game server settings](https://docs.kinematic.run/reference/errors.md#game-server-settings) or [Rounds, reveals and proofs](https://docs.kinematic.run/reference/errors.md#rounds-reveals-and-proofs). A code these docs do not explain shows without a link.

The card shows no list when the game server reported no errors. [Live](https://docs.kinematic.run/dashboard/live-monitor.md#wallet-round-trip-and-errors) counts every game server's errors together and links here.

## Deploys and updates

* **Automatic updates.** The dashboard checks for a new release every 5 minutes and deploys it to each deployed game server that has **Update automatically** on, in the mode the game server already runs. An automatic update never switches modes. A failed automatic update to the same release is retried after an hour. While Cloudflare is not connected, or needs reconnecting, automatic updates wait.
* **Update now.** When a newer release exists, the card says `Release <release> is out, published <date>.`, names the Durable Object migrations the update applies, and adds `It updates automatically within five minutes.` when automatic updates are on. Select **Update to** followed by the release, for example **Update to 3f9a1c2e**. Your game server keeps serving players on its current release until Cloudflare switches it over. If the release renames or deletes Durable Object classes your game server holds, the card says it does not deploy from here; write to [hello@kinematic.run](mailto:hello@kinematic.run).
* **A failed deploy.** The card shows a sentence that says what went wrong and how to fix it, followed by `Your game server keeps running.` when it was already running. **What Cloudflare said** shows the exact error, and **Read the fix** opens the fix in these docs for hostname and workers.dev problems. Fix the cause, then select **Deploy again**, or **Update again** for a failed update. [Errors](https://docs.kinematic.run/reference/errors.md#deploys) lists every sentence.
* **Switching modes.** After you switch your casino's mode in [Settings](https://docs.kinematic.run/dashboard/settings.md#mode), each game server keeps its mode until you redeploy it. Its card says, for example, `This game server runs in sandbox mode and your casino is set to live. Redeploy it to switch.` Select **Redeploy in live mode**: the game server switches to live mode when the deploy finishes. See [Go live](https://docs.kinematic.run/dashboard/go-live.md).

Deploy buttons are off while a deploy runs, while Cloudflare is not connected or needs reconnecting, and until your casino is set up.

## Stop new bets

The section **New bets** stops every new bet on all your game servers at once. Only owners and admins can stop or accept new bets.

**1. Stop new bets**

Select **Stop new bets**. The dialog `Stop new bets?` says `Bets already placed still settle. Reveals, actions on rounds in play, credits to your wallet and the Solana record all go on, and your game server takes the change within a minute.` Select **Stop new bets** to confirm.

**2. Check that it took**

The section lists each game server with `took the change just now.` or `has not taken the change yet.` The page shows `New bets are stopped on your game server. Bets already placed still settle.`, and **Game server** in the sidebar shows **Stopped**.

While new bets are stopped, your game servers refuse every new bet with `bets_disabled`. Blackjack rounds in play go on, but take no new extra stakes: the game server refuses a double, split or insurance with `bets_disabled` too.

To reverse it, select **Accept new bets again**, in the section or in the banner, then **Accept new bets** in the dialog. Players can bet again as soon as your game server takes the change, within a minute.

## Solana record

Sandbox game servers record each bet's proof on Solana devnet. Live game servers record nothing on Solana until the audited mainnet program is deployed; their section says so. Bets keep settling while recording is paused.

For each game server that records, the section shows:

| Row | Shows |
| - | - |
| **Recording** | **Recording**, or **Paused** with the reason. |
| **Address** | The game server's own Solana address, with **Copy the Solana address** and its network, such as `Solana Devnet`. |
| **Waiting** | How many bets are queued, sent and refused, or `Nothing waits to be recorded`, and how long the oldest has waited. |
| **Last recorded** | When the last transaction was confirmed and how many bets it recorded, with **View the transaction**. |

Recording pauses for three reasons:

| Reason | What the page says |
| - | - |
| The address cannot pay a fee | `Its address cannot pay the next transaction's fee. Recording resumes within a minute after the address is funded.` |
| A new VRF key is not registered yet | `Bets wait for a new VRF key to be registered on Solana. It is registered automatically within 10 minutes, or you can register it now.` |
| The Solana RPC failed | `The Solana RPC failed. Your game server tries again every few seconds.` |

Bets keep settling and paying while recording is paused. They wait in the game server's queue and are recorded when it resumes.

Owners and admins select **Check Solana** to ask the game server at once whether it records and which of its VRF keys are registered on Solana. To register a waiting key yourself, select **Plan key registration**: the page shows the keys it would register, what that costs in SOL, paid by your game server's own address, and `Nothing has been sent yet.` Then select **Register key** (or **Register keys**) to send exactly that plan.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.