Skip to content

Create a Computer

Create persistent Linux Computers with root access in a pool. A fresh Computer starts with a private website. A copy can inherit a public website from its source. Use copy.computer to start from an existing disk or copy.snapshot with copy.computer to use a saved disk. A request for new_pool: true can buy capacity. Read the returned operation with operation view to check whether creation is complete.

Parameters

#
namestring
New Computer name of 3 to 63 lowercase letters, digits and hyphens. Start and end with a letter or digit. Omit to generate a name.
poolstring
Destination pool name or ID. Omit if there is only one usable pool. With new_pool: true, this field names the new pool.
imagestring
Image for the Computer's starting disk. Give an available image or a container registry reference. The default is heaven-ubuntu.
templatestring
Template returned by template view. Give it in place of image.
registry_authstring
Private registry credential in USERNAME:PASSWORD form. Treated as a secret and never included in errors.
integrationsstring[]
Name of an integration to attach to the new Computer.
githubobject
Show 1 attributeHide attributes
repostringRequired
GitHub repository to clone in OWNER/REPO form. The Computer must have access through a GitHub integration.
setup_scriptstring
Shell script for first boot. Runs as the image's login user, which is heaven with passwordless sudo on heaven-ubuntu. Defaults to your saved setup script. Treated as a secret and never included in errors.
envstring[]
Environment variable for the setup script in KEY=VALUE form. Each key can be set once. The variables are removed after setup runs. Treated as a secret and never included in errors.
tagsstring[]
Tag for the new Computer.
commentstring
Computer comment, one line of at most 200 bytes.
domainstring
Full name under a domain connected to your organization, such as app.example.com. DNS must point to your organization. For several Computers, set the domain with pool defaults set.
cpustring
CPU size in whole vCPUs, up to the pool's allocation. A copy inherits the source's setting. A fresh Computer uses the pool's default or follows the pool's CPU size.
memorystring
Memory size up to the pool's allocation, such as 8GiB. G, GB and GiB mean GiB for memory. A copy inherits the source's setting. A fresh Computer follows the pool's memory size.
diskstring
Disk size up to the pool's storage allocation, such as 20GB. GB is decimal and GiB is binary. A copy inherits the source's setting. A fresh Computer uses the pool's disk default or follows the pool's storage size.
copyobject
Show 2 attributesHide attributes
computerstringRequired
Source Computer name or ID. Omit copy.snapshot to copy its current disk.
snapshotstring
Name or ID of a disk snapshot of the Computer named with copy.computer.
copy_tagsboolean
Copy the source Computer's tags. Defaults to true.
countstring
Number of Computers with identical settings. The pool's simultaneous create limit applies. Use names to choose the names.
namesstring[]
Names for new Computers with identical settings. Each name creates one Computer.
new_poolboolean
Create a pool for these Computers. Use pool to name it. Omission uses default or an available numbered variant.
unitsstring
Size with new_pool: true in units of 2 vCPUs and 8 GiB of RAM, from 1 to 64. Defaults to 1. Uses unused capacity first, then buys the remainder.
hourlyboolean
With new_pool: true, pay from your wallet by the minute, with a one-hour minimum (default).
monthlyboolean
With new_pool: true, pay for new capacity through your monthly subscription.
dry_runboolean
Preview the Computers and whether they fit. With new_pool: true, includes the pool and its cost.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.
waitboolean or string
Wait for the operation to finish. Use true for up to 10m or give a shorter duration such as 2m. Accepted work continues after the wait ends.

Returns

#
dataobjectAlways present
An operation for one Computer, or individual creation results and any new pool.
Show 2 attributesHide attributes
alternative-1object
An operation and its request ID.
Show 8 attributesHide attributes
namestring
Computer's name after creation, copying or reset. May be omitted.
notesstring[]
Other effects, including settings or integrations excluded from a copy. May be omitted.
operationobjectAlways present
Current operation state.
Show 9 attributesHide attributes
bystring
Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
completed_atstring (date-time)
When the operation reached its final state. Absent while unfinished. May be omitted.
computer_idstringAlways present
Computer's stable ID.
created_atstring (date-time)
When Heaven accepted the change. May be omitted.
error_codestring
Recorded failure code. May be omitted.
idstringAlways present
Operation ID for operation view.
kindstringAlways present
Change being tracked.
messagestring
An explanation of the recorded failure and any next action. May be omitted.
statestringAlways present
accepted means saved and unfinished. complete means the change finished. failed means it could not finish. superseded means a newer change replaced it before completion. Values: "accepted", "complete", "failed", "superseded".
pool_notestring
How stopping this Computer affects its pool. May be omitted.
renamedobject
Addresses affected by a rename. May be omitted.
Show 6 attributesHide attributes
httpsstringAlways present
Website URL using the new name.
mailstringAlways present
Domain under which the Computer receives mail.
namesobject[]
Custom names created with the Computer and whether they followed its rename. May be omitted.
Show 1 attributeHide attributes
itemsobject
A custom name affected by a Computer rename.
Show 3 attributesHide attributes
fromstringAlways present
Previous custom name.
movedbooleanAlways present
Whether the name moved. False means the destination was occupied and the old custom name was retained.
tostringAlways present
Name corresponding to the Computer's new name.
notestringAlways present
What happened to old addresses and when the guest hostname changes.
portsstring[]
Published port addresses that use the new name. May be omitted.
sshstringAlways present
SSH command using the new name.
request_idstringAlways present
Request ID identifying this change across retries.
ssh_deststring
SSH destination in NAME@DOMAIN form. May be omitted.
urlstring
Computer's website address. May be omitted.
alternative-2object
The result or preview of creating Computers and any new pool.
Show 7 attributesHide attributes
computersobject[] | nullAlways present
Computers in request order, each with its operation or error. Previews and pending payments can have neither.
Show 1 attributeHide attributes
itemsobject
One Computer in a create request.
Show 5 attributesHide attributes
errorobject
Reason this Computer could not be created. May be omitted.
Show 7 attributesHide attributes
actionobject
A suggested command addressing the problem. May be omitted.
Show 2 attributesHide attributes
commandstringAlways present
Command's catalog name.
linestringAlways present
Complete suggested command line.
kindstringAlways present
Error category. unknown means the effect is uncertain; reconcile before retrying.
messagestringAlways present
What happened and any action needed from you.
operation_idstring
Operation to read before repeating uncertain work. May be omitted.
request_idstring
Request ID identifying the change during reconciliation. May be omitted.
retry_afterinteger
Seconds before retrying a rate-limited request or a refused wait. May be omitted.
urlstring
Payment page for a payment-required response. May be omitted.
namestring
Chosen Computer name. A count-only preview has no name yet. May be omitted.
operationobject
Create operation. May be omitted.
Show 9 attributesHide attributes
bystring
Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
completed_atstring (date-time)
When the operation reached its final state. Absent while unfinished. May be omitted.
computer_idstringAlways present
Computer's stable ID.
created_atstring (date-time)
When Heaven accepted the change. May be omitted.
error_codestring
Recorded failure code. May be omitted.
idstringAlways present
Operation ID for operation view.
kindstringAlways present
Change being tracked.
messagestring
An explanation of the recorded failure and any next action. May be omitted.
statestringAlways present
accepted means saved and unfinished. complete means the change finished. failed means it could not finish. superseded means a newer change replaced it before completion. Values: "accepted", "complete", "failed", "superseded".
ssh_deststring
SSH destination in NAME@DOMAIN form. May be omitted.
urlstring
Website URL. May be omitted.
dry_runboolean
Whether this is a preview and no Computers were created. May be omitted.
errorobject
Creation refusal found by a dry run. May be omitted.
Show 7 attributesHide attributes
actionobject
A suggested command addressing the problem. May be omitted.
Show 2 attributesHide attributes
commandstringAlways present
Command's catalog name.
linestringAlways present
Complete suggested command line.
kindstringAlways present
Error category. unknown means the effect is uncertain; reconcile before retrying.
messagestringAlways present
What happened and any action needed from you.
operation_idstring
Operation to read before repeating uncertain work. May be omitted.
request_idstring
Request ID identifying the change during reconciliation. May be omitted.
retry_afterinteger
Seconds before retrying a rate-limited request or a refused wait. May be omitted.
urlstring
Payment page for a payment-required response. May be omitted.
poolobject
New pool, or the pool a dry run would create. May be omitted.
Show 13 attributesHide attributes
boughtobjectAlways present
Capacity purchased for the remaining size.
Show 4 attributesHide attributes
memory_bytesintegerAlways present
RAM allocation in bytes.
storage_bytesintegerAlways present
Included storage in bytes.
unitsintegerAlways present
Number of units.
vcpusintegerAlways present
vCPU allocation.
charged_centsinteger
Charge now, or its dry-run estimate, in cents. May be omitted.
from_unusedobjectAlways present
Existing purchased capacity assigned to the pool.
Show 4 attributesHide attributes
memory_bytesintegerAlways present
RAM allocation in bytes.
storage_bytesintegerAlways present
Included storage in bytes.
unitsintegerAlways present
Number of units.
vcpusintegerAlways present
vCPU allocation.
idstring
Created pool's ID. Absent for a preview or while payment is pending. May be omitted.
kindstring
Billing model for new purchases. May be omitted.
memory_bytesintegerAlways present
Pool's RAM allocation, in bytes.
namestringAlways present
New pool's name.
plansobject[]
Plans bought and any payment steps still required. May be omitted.
Show 1 attributeHide attributes
itemsobject
A plan purchased or proposed for a pool.
Show 8 attributesHide attributes
charged_centsinteger
Amount charged now, or its preview, in cents. May be omitted.
checkout_urlstring
Checkout page when payment is required. May be omitted.
invoice_urlstring
Invoice page when payment needs your action. May be omitted.
planintegerAlways present
Plan number.
price_microsintegerAlways present
Price per billing period, in millionths of a dollar. The enclosing result specifies the billing model.
purchasestring
Capacity purchase ID. May be omitted.
unitsintegerAlways present
Capacity units supplied by the plan.
unknownboolean
Whether the payment outcome is uncertain. Read capacity before buying again. May be omitted.
price_microsintegerAlways present
Combined price of new purchases per billing period, in millionths of a dollar.
regionstring
Pool's region. May be omitted.
storage_bytesintegerAlways present
Pool's included storage, in bytes.
unitsintegerAlways present
Pool's capacity in units.
vcpusintegerAlways present
Pool's vCPU allocation.
request_idstringAlways present
Request ID for this creation.
roomobject
Request's capacity check, when available. May be omitted.
Show 7 attributesHide attributes
computersintegerAlways present
Number of Computers requested.
fitsbooleanAlways present
Whether the request fits the pool's available storage and creation limits.
needs_bytesintegerAlways present
Estimated additional storage needed by the request, in bytes.
poolstringAlways present
Pool checked.
storage_bytesintegerAlways present
Pool's included storage, in bytes.
stored_bytesintegerAlways present
Storage already occupied in the pool, in bytes.
waiting_for_memoryintegerAlways present
Of the Computers the pool is creating, how many are waiting for memory in the pool.
waitingboolean
Whether purchases await payment. Heaven creates the pool and Computers once payment is confirmed. May be omitted.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • CLI: heaven login with HEAVEN_API_KEY unset. MCP: Heaven sign-in. cURL: HEAVEN_SIGN_IN_KEY from approved device sign-in (POST /v1/auth/create). Some inputs require sign-in.
  • API key permission: create.
  • For retries, reuse the original Idempotency-Key and inputs.
  • One: Create one Computer from an image or template. Optional: name, domain, image, template, registry_auth, integrations, github, setup_script, env, tags, comment, pool, cpu, memory, disk, new_pool, units, hourly, monthly, dry_run, organization, wait.
  • By count: Create the requested number of Computers with generated names. Required: count. Optional: image, template, registry_auth, integrations, github, setup_script, env, tags, comment, pool, cpu, memory, disk, new_pool, units, hourly, monthly, dry_run, organization, wait.
  • By name: Create a Computer for each supplied name. Required: names. Optional: image, template, registry_auth, integrations, github, setup_script, env, tags, comment, pool, cpu, memory, disk, new_pool, units, hourly, monthly, dry_run, organization, wait.
  • Copy: Copy a Computer from its current disk or a snapshot. Required: copy. Optional: name, copy_tags, pool, cpu, memory, disk, new_pool, units, hourly, monthly, dry_run, organization, wait.
  • Copies by count: Create the requested number of copies with generated names. Required: copy, count. Optional: copy_tags, pool, cpu, memory, disk, new_pool, units, hourly, monthly, dry_run, organization, wait.
  • Copies by name: Create a copy for each supplied name. Required: copy, names. Optional: copy_tags, pool, cpu, memory, disk, new_pool, units, hourly, monthly, dry_run, organization, wait.