Kisten

Create, read, change and delete Kisten. In the API a Kiste is an instance, addressed by its name.

List Kisten

GET /v1/instances

Every Kiste of your account, newest first, in the list shape {object, data, first_id, last_id, has_more}.

curl -sS "https://kiste.run/v1/instances" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 OK. Body: list of InstanceResponse

Errors use the error envelope.

Creates a Kiste and starts it. The answer arrives once the machine accepts SSH and commands; the desktop keeps starting in the background for a few more seconds. ssh_public_key is the key the Kiste trusts besides your account's device keys. Without ttl_seconds the Kiste runs until it is stopped. Plan and account limits are checked first: L02 (number of Kisten), L03 (running at once), L04 (disk), L13 (no free capacity right now, retry later).

curl -sS -X POST "https://kiste.run/v1/instances" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"review-42","profile":"desktop","vcpu":4,"memory_mib":8192,"disk_mib":81920,"ssh_public_key":"ssh-ed25519 AAAA... you@laptop","ttl_seconds":3600}'

Request body: CreateInstanceRequest

Field	Type	Required	Description
`auto_snapshot_seconds`	integer (int32) or null	no	How often a changed disk is checkpointed, 60–86400 seconds (default 300). Automatic checkpoints are always on; only the interval is configurable.
`disk_mib`	integer (int32)	yes	Disk size in MiB (default shape: 81920).
`environment`	string or null	no	An environment by name; its current version is applied.
`image`	string or null	no	A custom image by ID, slug or name; the universal image when omitted.
`memory_mib`	integer (int32)	yes	Memory in MiB (default shape: 8192).
`name`	string or null	no	Name of the new Kiste; generated when omitted.
`profile`	InstanceProfile	yes	Machine profile; `desktop`.
`ssh_public_key`	string	yes	An SSH public key the Kiste trusts, in addition to your account's device keys.
`ttl_seconds`	integer (int32) or null	no	Lifetime in seconds; when it ends the Kiste stops cleanly (its disk stays). Without it the Kiste runs until it is stopped.
`vcpu`	integer (int32)	yes	Number of vCPUs, within your account's limits (default shape: 4).

Responses:

200 OK. Body: InstanceResponse

Errors use the error envelope.

Get a Kiste

GET /v1/instances/{name}

One Kiste by name: its state, size, image version, lifetime, checkpoint times and whether a saved session is waiting.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS "https://kiste.run/v1/instances/review-42" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 OK. Body: InstanceResponse

Errors use the error envelope.

Delete a Kiste

DELETE /v1/instances/{name}

Permanently deletes the Kiste and its disk. Its named snapshots stay until you delete them. Answers 202 when the deletion is still running after 20 seconds; the instance.deleted event marks its end.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X DELETE "https://kiste.run/v1/instances/review-42" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 Finished. Body: MessageResponse
202 Still running; the body is the state as it is now, the end is an event. Body: MessageResponse

Errors use the error envelope.

Stop a Kiste

POST /v1/instances/{name}/stop

Shuts the Kiste down; its disk stays and a stopped Kiste uses no compute. With {"snapshot": true} the memory is saved as well, so the next start resumes the session in about a second. Long stops answer 202 with the current state; instance.stopped marks the end.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X POST "https://kiste.run/v1/instances/review-42/stop" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Request body (optional): StopInstanceRequest

Field	Type	Required	Description
`snapshot`	boolean	no	Preserve the running session: writes the memory snapshot so the next start resumes in about a second. Slower to stop. Without it the stop is a clean shutdown and the next start is a fresh boot.

Responses:

200 Finished. Body: InstanceResponse
202 Still running; the body is the state as it is now, the end is an event. Body: InstanceResponse

Errors use the error envelope.

Restart a Kiste

POST /v1/instances/{name}/restart

Reboots the Kiste from its own disk: files stay, processes start fresh, and a pending image update is applied. A stopped Kiste boots fresh too, and a saved session is dropped; use resume to keep it.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X POST "https://kiste.run/v1/instances/review-42/restart" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 Finished. Body: InstanceResponse
202 Still running; the body is the state as it is now, the end is an event. Body: InstanceResponse

Errors use the error envelope.

Resume a Kiste

POST /v1/instances/{name}/resume

Starts a stopped Kiste. When a session was saved with stop --snapshot (or by a lifetime ending), it continues exactly where it was; otherwise the Kiste boots from its disk.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X POST "https://kiste.run/v1/instances/review-42/resume" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 Finished. Body: InstanceResponse
202 Still running; the body is the state as it is now, the end is an event. Body: InstanceResponse

Errors use the error envelope.

Rename a Kiste

POST /v1/instances/{name}/rename

Gives the Kiste a new name, with the same rules as at creation. The host name inside the Kiste follows at its next update or cold boot. The instance.renamed event carries the old name in data.previous_name.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X POST "https://kiste.run/v1/instances/review-42/rename" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"review-43"}'

Request body: RenameInstanceRequest

Field	Type	Required	Description
`name`	string	yes	The new Kiste name; same rules as at creation.

Responses:

200 OK. Body: InstanceResponse

Errors use the error envelope.

Update a Kiste to the newest image

POST /v1/instances/{name}/upgrade

Brings the Kiste onto the image version the platform currently serves, without changing whether it runs. A running Kiste reboots and its session ends; files and installed packages stay. A stopped Kiste stays stopped, its saved session is discarded, and its next start is the update. GET /v1/runtime/image has the release notes.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X POST "https://kiste.run/v1/instances/review-42/upgrade" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 Finished. Body: InstanceResponse
202 Still running; the body is the state as it is now, the end is an event. Body: InstanceResponse

Errors use the error envelope.

Extend a Kiste's lifetime

POST /v1/instances/{name}/extend

Adds ttl_seconds to the Kiste's automatic stop, or sets one that far from now when it has none. When the lifetime ends the Kiste stops and keeps its disk; its session is saved when the guest answers.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X POST "https://kiste.run/v1/instances/review-42/extend" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds":3600}'

Request body: ExtendInstanceRequest

Field	Type	Required	Description
`ttl_seconds`	integer (int32)	yes	Seconds added to the Kiste's deadline (or from now when it has none); at the deadline it stops cleanly.

Responses:

200 OK. Body: InstanceResponse

Errors use the error envelope.

Fork a Kiste

POST /v1/instances/{name}/fork

Copies the disk of a running Kiste into a new, independent Kiste, which boots fresh with its own processes. The copy keeps the source's environment and checkpoint interval but never its automatic stop: give it one with ttl_seconds.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS -X POST "https://kiste.run/v1/instances/review-42/fork" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"review-42-try","ttl_seconds":14400}'

Request body: ForkInstanceRequest

Field	Type	Required	Description
`name`	string	yes
`ttl_seconds`	integer (int32) or null	no	The copy's lifetime in seconds (60 to 2592000); without it the copy has no automatic stop (it never inherits the source's deadline).

Responses:

200 OK. Body: InstanceResponse

Errors use the error envelope.

Read the console log

GET /v1/instances/{name}/logs

The boot and console log of the Kiste. tail selects the last lines, at most 2000.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

Query parameters:

Name	Type	Required	Description
`tail`	integer	no	Number of trailing lines, at most 2000.

curl -sS "https://kiste.run/v1/instances/review-42/logs" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 OK. Body: LogsResponse

Errors use the error envelope.

Sample live usage

GET /v1/instances/{name}/metrics

One short sample from inside a running Kiste: CPU, memory, disk, load, uptime and the busiest processes. Answers 409 while the Kiste is not running and 429 past 40 samples a minute per account.

Path parameters:

Name	Type	Required	Description
`name`	string	yes	The Kiste's name.

curl -sS "https://kiste.run/v1/instances/review-42/metrics" \
  -H "Authorization: Bearer $KISTE_TOKEN"

Responses:

200 OK. Body: InstanceMetricsResponse

Errors use the error envelope.

List Kisten

Create a Kiste

Get a Kiste

Delete a Kiste

Stop a Kiste

Restart a Kiste

Resume a Kiste

Rename a Kiste

Update a Kiste to the newest image

Extend a Kiste's lifetime

Fork a Kiste

Read the console log

Sample live usage

On this page