Skip to main content
By default a computer runs until you stop or delete it. Give it an end and it is deleted when its time is up, running or stopped, with everything on it. To keep a computer, leave out the end. An end is a whole number of hours, from 1 to 720 (30 days).
A computer deleted at its end can’t be brought back. Its disk and everything on it are gone, as when you delete it yourself.
Only Linux and Windows computers, on your plan or billed by the hour, can have an end. Mac, iPhone, Android and device computers can’t.

Pick an end in the dashboard

In the New computer sheet, the Ends row says Never. Press Change next to it and pick one. Under the choices the sheet says When its time is up it is deleted. The price line under it says what the end costs, as described in What an end costs.

When time is up

  1. It is deleted, running or stopped, the same as when you delete it yourself. It is never stopped first.
  2. Its billing ends. An hourly computer stops being billed at the delete, and what its prepay did not use comes back to your credit.
A computer you stop yourself before its end keeps that end, and is still deleted when it comes. To keep it, take the end off first, as described in Keep it, or change the end.

An end set before ends deleted computers

A computer whose end was set before every end deleted the computer has on_end "stop". At its end it stops, and its page and its tile say Its time ran out. Deleted on the date unless you start it. It is deleted 7 days later, unless you start it. Starting it brings it back as an ordinary computer with its end cleared. Any new end you give it deletes it.

Keep it, or change the end

While a computer has an end ahead, its page and its tile say how long it has left, for example Deleted in 3h 12m, or Ends in 3h 12m for an end set before ends deleted computers. Press Keep it beside it to take the end off. The computer then runs until you stop or delete it. Anyone who can change the workspace’s computers can keep one. Switch to always on on an hourly computer takes the end off too, so the computer stays, and what its prepay has not used comes back. A computer Orgo moves onto your plan by itself, once your plan has room, keeps its end. To add time or move the end, use the API, as described in Add time and Move or clear the end.

From the API

Every call below uses an API key: replace $WORKSPACE_ID with your workspace and $COMPUTER_ID with the computer’s UUID.

Create a computer with an end

Send ends_in_hours, 1 to 720. Leave it out, or send null, and the computer never ends. There is nothing to choose about what happens at the end: on_end "delete" is accepted and changes nothing, and any other value, "stop" included, answers 400 with code INVALID_ENDS: A computer with an end is deleted when its time is up. To keep a computer, leave out the end.
The 201 carries ends_at, when it is deleted, and on_end "delete". An hourly computer also carries prepaid_until and prepaid_cents, as described in By the hour, the run is prepaid. If the computer was made but can’t have an end, or its end could not be saved, ends_at is null and ends_warning says why, for example This computer can’t have an end, so it keeps running until you stop it. See Create computer.

Add time

POST /computers/{id}/extend adds hours to the end the computer has, so it only ever lengthens. The new end can be up to 2160 hours (90 days) from now.
Idempotency-Key is required, so a retry can’t add the time twice. The computer is still deleted at its new end. Extend computer has the rules.

Move or clear the end

PATCH /computers/{id} takes one of:
  • ends_in_hours: 1 to 720, counted from now, so a small number can shorten the end.
  • ends_at: an ISO 8601 time in the future, at most 720 hours away.
  • "ends_at": null: no end. The computer runs until you stop or delete it.
Send one of the two fields, not both. Every end set or moved this way deletes the computer when it comes. The answer carries the computer’s id, name, ends_at, on_end, ended_at and deletes_at. An hourly computer’s answer also carries prepaid_until and prepaid_cents, and prepay_returned_cents when some of its prepay came back. Any change clears a stopped computer’s ended mark, so "ends_at": null also keeps a computer that an end set before ends deleted computers has stopped, without starting it. Sending back the ends_at the computer already has changes nothing, so you can PATCH the object Get computer gave you. See Update computer.

Start or resume with an end

Start computer and Resume computer (for a sleeping computer) take ends_in_hours or ends_at in the body, checked the same way as on PATCH. The hours count from when the computer is running, not from the request, because a start can take minutes. When the end comes, the computer is deleted.
A bad end is refused before anything starts. The end is set once the computer is running. If it can’t be set then, the start still succeeds and the answer carries end_not_set with an error and a code. With async, the 202 says end_pending. A resume that is still under way answers 202 with end_not_set and code STILL_RESUMING: set the end with PATCH once it is running.

Read the end

Get computer returns:

What an end costs

How a computer is paid for decides what its end costs. See How a computer is paid for.

On your plan, nothing extra

A computer on your plan costs nothing more with an end. The sheet says Included in your plan. The end only decides when it is deleted. A plan computer given an end later stays on the plan.

By the hour, the run is prepaid

An hourly computer with an end pays for its whole run up front, from your credit: its running rate times the hours. For a Medium Linux computer with a 4 hour end, the sheet says Prepay $0.22 from your credit: $0.055/hr for 4 hours. Unused time comes back. The prepay is the run and nothing after it. On the computer, the line beside its end says Prepaid $0.22 until and the time.
  • It never runs out of credit before its end. The prepay covers the whole run.
  • Unused time comes back to your credit, once: when it stops before its end, is deleted, is kept, moves onto your plan, or its end moves earlier. Keep it says how much came back.
  • A later end prepays the extra. Without enough credit, the change answers 402 and nothing changes.
  • It leaves an hour for your other hourly computers. A prepay never takes the credit your other hourly computers need for their next hour. When that applies, the sheet adds Needs an amount more for an hour of your other computers.
  • At its end it is deleted, and nothing more is billed.
  • A start without an end is billed by the hour with no prepay, as any hourly computer is. A start with an end prepays once the computer is running.
Usage counts a prepay on the day it was made, less what came back. To launch an hourly computer with an end from the API, send "billing_mode": "hourly" with ends_in_hours. Only the workspace owner can launch by the hour, and on a paid account only signed in or with a key that has Billing write (an MCP sign-in, or a key without Billing write, gets 403 with code HOURLY_NEEDS_BILLING). Send an Idempotency-Key with a UUID, so a retry launches it once.
The 201 says what was prepaid:
On a paid plan, a launch by the hour is only for a computer your plan can’t take, or one past your 50 computers, described in Computers per account. One that fits answers 409 with code FITS_PLAN: This computer fits your plan. Launch it on the plan. Leave out billing_mode and it launches on the plan.

Who can prepay

Only the workspace owner can prepay. On a paid account, or one set to pay for every computer from credit, that means signed in or with a key that has Billing write, not through an MCP sign-in. Anyone else who can change the workspace’s computers can still set or move an end: nothing more is held, the time past what is prepaid is billed by the hour, and the answer carries prepay_warning: The new time is billed by the hour. Only the account owner can prepay it, signed in or with a key that has Billing write. A first end on a running hourly computer is never refused for credit. When your credit can’t prepay it, the end is still set and the answer carries prepay_warning: The new end is set, and the time to it is billed by the hour: your credit does not cover prepaying all of it.

Errors