Kontext Encyclopedia

Kontext Gas Station

/gas-station · version 3.54 · 2026-11-19

Capabilities

Gas Station (Keep your apps running.) keeps every app you deploy fuelled from your Kontext Credits, the same credits that pay for AI and builds. It lists Your Kontext (your workspace), your agent server and each app's servers with their days of fuel left, and warns when something will run out soon.

What is Gas Station?

Gas Station is the pump. It moves hosting fuel from your wallet into the servers that run your apps (and your Main Agent). Use it when Deploy or Hosting says fuel is low, or when an app cannot serve because the server ran dry. Auto top-up and a manual fill are both optional.

Credits, fuel, and the receipt

AI credits (Pricing / your plan) pay Talk, generate, and agent turns. They are not hosting fuel. Servers, builds and AI are all paid from your Kontext Credits. Fuel is those credits moved into a server. Hosting fuel (Gas Station) keeps the app server running. When it hits zero, that server can freeze or go empty. Audit is the receipt — what ran, and what left the balance. It does not add fuel.

What Gas Station is not

Buy credits adds Kontext Credits by card. Plans are on Pricing. It does not explain a chat that spent credits. That is Audit. It is not Finance, which is a staff console, not your bookkeeping.

Route: /gas-station · Also: Deploy/Hosting surfaces link here for lane fueling

Gas Station is the fuel desk for your hosted servers — it moves fuel, paid from your Kontext Credits, into each server (your workspace is one row in the list) so deployed apps stay alive on the Internet Computer.


Gas Station (/gas-station) moves cycle fuel from your wallet balance into hosting lane canisters (frontend/backend pairs). Use it when Deploy or Hosting warns about low cycles—not for buying AI credits (see Profile / Pricing). Auto top-up and manual dispense are optional.

Days of fuel and auto-buy: Each app row shows its days of fuel left. Refuel all apps fills every app to about 7 days. When your credits run out holds the card auto-buy and its monthly cap. A workspace under 7 days of fuel asks Kontext to warn its owner (critical under 48 hours) and asks for fuel near its floor. Kontext answers under the admin's rules.

User-facing capabilities
Feature What it does
Wallet-backed pumps Refuel servers from your Kontext Credits.
Automatic top-up Heartbeat checks lanes against below/target thresholds; refills on schedule you configure
Manual dispense Push fuel to a chosen lane when you want explicit control
Stop / resume lane Exclude canisters from auto fuel (debugging, spend pause) and bring them back
Owner reserve guardrails Minimum reserve checks prevent draining your account past safety floors
Usage history Auto and manual dispenses mirrored to profile usage where enabled
Deploy UX integration Hosting/deploy surfaces link “fuel lanes for this pair”
Display-cycle basis In-product surfaces show readable cycle amounts

How it fits the platform
Surface Relationship
App Studio → Hosting / Deploy Preflight fuel checks before agent/workflow deploy
Server pairs Each pair's frontend/backend lanes can be fueled independently
Agent / workflow deploy Unified fuel policy — zero-friction provisioning checks balance first

Operator tooling (admin)

Operator tools are in the KTX Console: Platform → Cycles, Workspaces → Watchdog, Settlement, Infrastructure → Spare canisters. Old /gas-station/master links say where each one went.

Owner principle: You control spend — auto top-up is optional; manual dispense always available.

Platform cycles wallet (operators only). Kontext's own admins have a separate cycles wallet in the KTX Console (Platform → Cycles). It sends cycles to any canister the platform knows, so a frozen workspace can be rescued, and it can be refilled by card. A rescue is a gift from the platform and nothing is charged to the user. Sends are capped at 5T each and 20T a day, and every action is recorded with its reason. A keep-alive that tops up listed canisters is off until an admin turns it on. Since 18 October the platform's own backend no longer holds ICP for top-ups; every top-up the platform pays for comes out of its own cycles-ledger balance, and an empty balance fails the top-up by name. This is not a customer feature.

User journeys

G-01. Top up canister cycles at Gas Station

Path: Module switcher → Gas Station · /gas-station

You do:

  1. Open Gas Station when deploy, login, or Hosting hints at low cycles on your user canister.
  2. Review your Kontext Credits — fuel is paid from them.
  3. Choose a top-up amount appropriate to your lane count and expected deploy activity.
  4. Confirm payment or credit transfer per in-product checkout (display-cycle amounts shown readably).
  5. Wait for balance update on the Gas Station dashboard.
  6. Note: topping cycles alone may not restore login if WASM was removed at zero — depleted recovery may need admin reinstall (G-10).
  7. Proceed to lane fueling (G-03) or Hosting alignment (G-05) before retrying deploy.

Result: User canister cycle wallet increases; you can fund frontend/backend lanes without immediately hitting empty-canister errors on routine operations.

G-02. Configure automatic lane top-up thresholds

Path: /gas-station → Automatic top-up · lane settings

You do:

  1. Open /gas-station and locate Automatic top-up or heartbeat fuel settings.
  2. Select which server pairs or lanes participate in scheduled refills.
  3. Set below and target thresholds — when a lane drops under minimum, fuel refills toward target.
  4. Enable owner reserve guardrails so auto fuel never drains your account past safety floors (G-08).
  5. Save schedule — heartbeat checks run on the interval the UI documents.
  6. Monitor first auto dispense in Usage history (G-07).
  7. Exclude debug lanes with Stop lane if you need manual-only control (G-04).

Result: Lanes stay fueled on autopilot within guardrails you configure; spend remains under your control because auto top-up is optional.

G-03. Manually dispense fuel to a server lane

Path: /gas-station → Manual dispense · select lane

You do:

  1. Open Gas Station and identify the frontend or backend lane that needs immediate cycles.
  2. Choose Manual dispense for explicit control instead of waiting for heartbeat.
  3. Pick the target lane tied to a specific server pair from App Studio Hosting.
  4. Enter dispense amount in display-cycle units shown in-product.
  5. Confirm reserve guardrails pass — dispense blocked if it would breach minimum owner reserve.
  6. Submit and watch confirmation on the lane row balance.
  7. Retry deploy or agent runtime on that pair once fuel lands (G-09).

Result: Chosen lane receives an immediate cycle refill from your wallet without enabling full automatic top-up for every lane.

G-04. Stop and resume a lane for spend control

Path: /gas-station → lane row → Stop · Resume

You do:

  1. Open /gas-station and locate the lane you want to exclude from automatic fueling.
  2. Click Stop lane — debugging, cost pause, or migration hold.
  3. Confirm the lane shows stopped status and is skipped by heartbeat auto top-up.
  4. Continue manual dispense (G-03) only when you explicitly want to fuel that lane.
  5. When ready, click Resume lane to re-include it in automatic policies.
  6. Verify the next heartbeat or manual dispense succeeds after resume.
  7. Check App Studio Hosting for deploy warnings if a stopped lane runs out during pause.

Result: You pause automatic spend on specific canisters without tearing down the server pair — resume restores normal fuel policy.

G-05. Pair Gas Station with Hosting credits before deploy

Path: Gas Station top-up → App Studio Hosting · pre-deploy checklist

You do:

  1. After funding cycles at Gas Station (G-01), open App Studio Hosting for the target project.
  2. Confirm hosting credits cover agent and deploy server costs separately from canister cycles.
  3. Review server pair status — frontend and backend lanes both show adequate fuel or credit headroom.
  4. Align pair selection with the project you intend to deploy.
  5. Return to Deploy tab only when both cycle lanes and hosting credits look green.
  6. Run deploy preflight — unified fuel policy checks balance before provisioning.
  7. If deploy still fails, split diagnosis: cycles vs hosting credits vs WASM depletion (G-10).

Result: Canister cycles and hosting credits are both aligned so ship succeeds end-to-end — cycles alone are not always sufficient.

G-06. Fuel lanes from App Studio Deploy preflight

Path: App Studio → Deploy · Hosting link → Fuel lanes for this pair

You do:

  1. Open the project in App Studio and go to Deploy (or Hosting preflight).
  2. Read deploy or hosting warnings about low lane cycles before clicking deploy.
  3. Follow the in-product link Fuel lanes for this pair (or equivalent Gas Station deep link).
  4. Land on Gas Station scoped to the relevant frontend/backend lanes for that pair.
  5. Manual dispense (G-03) or confirm auto top-up will cover the shortfall (G-02).
  6. Return to Deploy and re-run preflight until fuel checks pass.
  7. Execute deploy and capture success confirmation plus canister ids if support needs them.

Result: Deploy UX bridges directly into Gas Station so you fix lane fuel in context without hunting the module blindly.

G-07. Review Gas Station usage history

Path: /gas-station → Usage history · profile usage mirror

You do:

  1. Open /gas-station after auto or manual dispenses.
  2. Expand Usage history — auto heartbeat refills and manual dispense rows.
  3. Filter or scan by date, lane, and dispense type if the UI supports it.
  4. Compare spend spikes to deploy or agent activity in App Studio logs.
  5. Cross-check profile usage surfaces where Gas Station mirrors history when enabled.
  6. Adjust auto thresholds (G-02) if heartbeat over-fuels or under-fuels relative to traffic.
  7. Export or screenshot for finance review if you track infra spend externally.

Result: Clear audit trail of who fueled which lane, when, and how much — auto vs manual — for operator accountability.

G-08. Respect owner reserve guardrails when fueling

Path: /gas-station → reserve settings · dispense confirmation

You do:

  1. Open Gas Station settings for owner reserve or minimum balance guardrails.
  2. Set a floor that leaves enough cycles on your user canister for login and platform ops.
  3. Attempt a manual dispense (G-03) that would breach the floor — confirm UI blocks or warns.
  4. Lower dispense amount or top up wallet (G-01) before retrying.
  5. Enable auto top-up only with reserve checks active — never drain account to zero unintentionally.
  6. Read blocked dispense copy carefully; it explains reserve math in display cycles.
  7. After successful fueling, confirm user canister balance stays above your configured minimum.

Result: Fuel operations cannot silently drain your account past safety floors — protecting login and owner canister health.

G-09. Recover a deploy after low-cycle failure

Path: Failed deploy → Gas Station → retry Deploy

You do:

  1. Note deploy failure symptoms: lane out of cycles, frozen frontend, or preflight fuel error.
  2. Open App Studio Hosting to identify which lane failed — frontend vs backend pair.
  3. Jump to Gas Station via deploy integration link (G-06) or /gas-station directly.
  4. Manual dispense or wait for auto top-up to bring the lane above threshold (G-02, G-03).
  5. Confirm hosting credits still cover server billing (G-05).
  6. Return to Deploy and re-run build — watch log through success.
  7. Validate Live Preview matches post-deploy if your workflow includes preview tab.

Result: Deploy succeeds after aligning lane fuel and hosting credits — routine low-cycle recovery without admin intervention.

G-10. Distinguish frozen vs depleted canister recovery

Path: Login/deploy failure → Gas Station · admin reinstall playbook

You do:

  1. Read the error carefully: frozen with cycles > 0 differs from depleted / no Wasm module (IC0537).
  2. For frozen: top up cycles via Gas Station (G-01) and ask Kontext support if the server stays frozen (operators rescue it from the KTX Console).
  3. For depleted at zero: topping cycles alone does not restore WASM — data on that canister may be gone. A workspace that Kontext put to sleep before it ran dry is a third case: its data is in an archive and comes back with Restore my workspace (G-13).
  4. Do not use browser Deploy WASM for user canister — ingress limit causes 413 failures.
  5. Prefer platform reinstall on the same canister id so @handle registry stays valid (admin scripts).
  6. After WASM returns, run account bootstrap if Credits shows Account not initialized.
  7. Resume normal Gas Station lane fueling only once login and Hosting pair provisioning succeed again.

Result: You apply the right recovery path — fuel for frozen lanes vs reinstall/bootstrap for depleted WASM — instead of repeating doomed top-ups alone.

G-11. Rescue a frozen workspace (platform operators)

Path: KTX Console → Platform → Cycles → Platform cycles wallet

You do:

  1. Find the person by @handle, or the canister, and choose the workspace or one of its agent runtimes.
  2. Enter an amount and a reason, then Preview: it shows what the canister holds, whether it is frozen, the fee and the wallet after.
  3. Type the amount back to confirm.

Result: The cycles are sent once; a retry cannot apply twice. Unknown canisters are refused. The wallet's key file is never replaced, because a new key orphans the old balance.

G-12. Refresh your workspace's memory when Kontext offers it

Path: /profile/settings → Software upgrade → the memory refresh card → Refresh my workspace

You do:

  1. A workspace keeps every piece of memory it ever claimed, even after the data in it is gone, and you pay fuel for all of it. When yours has grown well past what it uses, Kontext sends a bell notice and a card appears on Software upgrade: Plan a memory refresh for your workspace (or Your workspace needs a memory refresh). The card is only there when your workspace needs it.
  2. Read the card: your workspace is copied, its memory is rebuilt, and it is checked against the copy. It takes about 30 seconds, during which your workspace does not answer.
  3. Press Refresh my workspace and confirm. The card says Your refresh is queued, then The refresh is running. You can leave the page.
  4. When it finishes the card says Your workspace's memory was refreshed with the memory before and after, and you get a bell notice. If it did not go through, the card says why (not enough fuel for the safety copy, or the workspace needs its software update first) and the button comes back.

Result: Your workspace holds only the memory it uses, so its fuel lasts longer. Your data is unchanged; if anything had gone wrong, the copy taken right before would have been put back by itself. That copy stays on your workspace for a week and is then removed.

G-13. Bring back a workspace that was put to sleep

Path: Sign in → Your workspace is asleep → Restore my workspace (or Pay and restore)

You do:

  1. When your workspace is close to running out of fuel, Kontext warns you by bell and email, with the date it will be put to sleep. Refuel it (G-02) and nothing else happens.
  2. If it is not refuelled, Kontext saves everything in it (projects, files, settings, wallet) to a private, encrypted archive and switches it off. Signing in then shows one screen in place of the app: what happened, what the restore costs in credits, what your wallet held, and the date until which the archive is kept.
  3. If your plan is active, or your wallet held enough, press Restore my workspace. The screen says your request is in the queue, then that the workspace is being restored, and lets you in when it is running. The price is taken from the wallet that comes back; on an active plan anything it cannot cover comes out of the next credits you receive.
  4. If your plan is not active and your wallet is short, press Pay $… and restore and pay the one-time amount by card. The restore starts by itself when the payment goes through.
  5. If the archive's date has passed, the screen says the archive was deleted and offers Start a new workspace: your sign-in still works, and you begin with an empty workspace.

Result: Your workspace is back as it was on the day it went to sleep, at the same address, with its wallet. Apps on their own servers are separate: each still needs its own fuel (G-02).

Kontext's team switches this protection on for the platform. Until it is on, a workspace left without fuel freezes and can be lost (G-10), so keep Refuel automatically on (G-03).

G-14. Platform operators: memory, sleeping workspaces and one-workspace updates are in the Console

Path: KTX Console → Systems → Memory refresh · Dormant workspaces · Workspaces → a workspace

You do:

  1. Memory refresh shows how much memory the platform canister and every workspace claim against what they use, takes a snapshot and rebuilds on an admin's press, and offers owners the refresh in G-12.
  2. Dormant workspaces shows each workspace's days of fuel, what the hourly pass would do, and the policy (when to warn, when to put to sleep, how long an archive is kept, the restore price). It is off until an admin switches it on. Sleeping rows carry Restore now, Approve, Payment link, +30 days and Delete.
  3. On a workspace's own page, Update to the release installs the published workspace version on that one workspace, after checking its stored data fits.

Result: Operators keep workspaces small, save the data of one nobody fuels, and update a single workspace, each with a typed confirmation and a record. The console's Handbook has a chapter for each page.

How it works

Route /gas-station. Refuels each server from your Kontext Credits (newer workspaces via the platform reserve). Auto-refuel runs on the workspace's own check (default 30 s, even with the page closed). Each app row shows days left. Card auto-buy is optional.

Memory and sleep. A workspace keeps all the memory it ever claimed and pays fuel for it. Kontext's console reads every workspace hourly; when one has grown well past what it uses, its owner is offered a refresh (a safety copy, a rebuild, a check against the copy, and the copy put back by itself on any failure). The same reading gives each workspace's days of fuel. With sleep protection on, a workspace at one day left is saved to an encrypted archive outside the Internet Computer and its server is emptied but kept; the owner restores it for the cost of loading it back (from the archived wallet, against an active plan, or by a one-time card payment). Apps' own servers are not part of the archive.

Benefits

Who it's for

Primary: anyone hosting apps or agent runtimes on IC. Also: platform operators (fleet tooling). Not: guests with no canisters to fuel.