Computers

Get or create a Computer by name.

Idempotent: the first call creates the machine (201), every identical repeat returns the existing one (200). Resource changes on a repeat are ignored — the existing machine wins. Use this instead of create when an agent may retry.

put/v1/computers/by-name/{name}

Request

  • Base URL: https://api.scalix.world
  • URL: https://api.scalix.world/v1/computers/by-name/{name}
  • Auth: HTTP bearer

Path parameters

namestring required

Lowercase DNS label, max 63 characters

Request body

namestring required

Lowercase DNS label, max 63 characters. Unique per account.

imagestring nullable

Guest image. ubuntu24 is the only image available today.

ssh_keysstring[] nullable

OpenSSH public keys authorised for root, one per array entry, max 32. Optional — exec and the browser terminal work without one. Send the public half only (the .pub file); a private key is rejected.

Example request

{
  "name": "build-box",
  "image": "ubuntu24",
  "resources": {
    "vcpus": 2,
    "memory_mb": 2048,
    "disk_gb": 20
  },
  "ssh_keys": [
    "ssh-ed25519 AAAAC3Nz… you@laptop"
  ]
}

Response

The existing Computer

idstring required
namestring required
imagestring required
statusstring required

CREATING | RUNNING | STOPPING | STOPPED | STARTING | DELETING | FAILED

statusReasonstring nullable

Human-readable reason for the current status (set on FAILED).

ipAddressstring nullable

Private address inside your network. Reserved for the Computer's lifetime — the same address comes back after a stop/start.

vcpusinteger required
memoryMbinteger required
diskGbinteger required
sshKeysstring[]

The OpenSSH public keys currently authorised for root. Public halves only — there is nothing secret to withhold here, and being able to read back what is installed is how you confirm a revocation took.

createdAtstring required
updatedAtstring required

Example response

{
  "status": "RUNNING"
}

Changes

No recorded changes to this operation across all 1 revision of this API.