---
title: "Get or create a Computer by name."
method: PUT
path: "/v1/computers/by-name/{name}"
tags: ["Computers"]
---

# Get or create a Computer by name.

`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

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.

## Path parameters

- `name` string, required

## Request body

- ComputerCreateRequest: Request body for creating a Computer.
  - `name` string, required: Lowercase DNS label, max 63 characters. Unique per account.
  - `image` string, nullable: Guest image. `ubuntu24` is the only image available today.
  - `resources` ComputerResources: Resource shape for a Computer. Fixed at create in v1 — disks do not grow.
    - `vcpus` integer, nullable: 1..16
    - `memory_mb` integer, nullable: 512..32768
    - `disk_gb` integer, nullable: 5..200. Billed per GB-month for as long as the Computer exists, running or stopped.
  - `ssh_keys` string[], 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.

## Response `200`

The existing Computer

- ComputerInfo: A Computer as returned by create/get/list.
  - `id` string, required
  - `name` string, required
  - `image` string, required
  - `status` string, required: CREATING | RUNNING | STOPPING | STOPPED | STARTING | DELETING | FAILED
  - `statusReason` string, nullable: Human-readable reason for the current status (set on FAILED).
  - `ipAddress` string, nullable: Private address inside your network. Reserved for the Computer's lifetime — the same address comes back after a stop/start.
  - `vcpus` integer, required
  - `memoryMb` integer, required
  - `diskGb` integer, required
  - `sshKeys` string[]: 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.
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `201`: Computer created
- `400`: Invalid name or resource shape
- `503`: No host has capacity for the requested resources

---

[API](https://skmtc.dev/scalix/apis/scalix-cloud-api.md) · [All operations](https://skmtc.dev/scalix/apis/scalix-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalix/apis/scalix-cloud-api/revisions/2c04ca0a90bb?raw)