Run the computer's service

curl --request POST \
  --url https://api.cool.computer/api/computers/{id}/service/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "node server.js",
  "port": 3000
}
'

import requests

url = "https://api.cool.computer/api/computers/{id}/service/run"

payload = {
    "command": "node server.js",
    "port": 3000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({command: 'node server.js', port: 3000})
};

fetch('https://api.cool.computer/api/computers/{id}/service/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cool.computer/api/computers/{id}/service/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'command' => 'node server.js',
    'port' => 3000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cool.computer/api/computers/{id}/service/run"

	payload := strings.NewReader("{\n  \"command\": \"node server.js\",\n  \"port\": 3000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cool.computer/api/computers/{id}/service/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"node server.js\",\n  \"port\": 3000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cool.computer/api/computers/{id}/service/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"command\": \"node server.js\",\n  \"port\": 3000\n}"

response = http.request(request)
puts response.read_body

{
  "configured": true,
  "status": "<string>",
  "ready": true,
  "restarts": 1,
  "url": "<string>",
  "command": "<string>",
  "cwd": "<string>",
  "port": 32768,
  "exec_id": "<string>",
  "pid": 2,
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "exit_code": 123,
  "signal": "<string>",
  "last_exit": {
    "code": 123,
    "at": "2023-11-07T05:31:56Z"
  },
  "last_output": "<string>",
  "logs": {
    "retention": "disk_ring",
    "bytes_written": 1,
    "bytes_dropped": 1,
    "dropped_frames": 1,
    "next_id": 1
  }
}

{
  "configured": true,
  "status": "<string>",
  "ready": true,
  "restarts": 1,
  "detail": "<string>",
  "url": "<string>",
  "command": "<string>",
  "cwd": "<string>",
  "port": 32768,
  "exec_id": "<string>",
  "pid": 2,
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "exit_code": 123,
  "signal": "<string>",
  "last_exit": {
    "code": 123,
    "at": "2023-11-07T05:31:56Z"
  },
  "last_output": "<string>",
  "logs": {
    "retention": "disk_ring",
    "bytes_written": 1,
    "bytes_dropped": 1,
    "dropped_frames": 1,
    "next_id": 1
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

Services

Run the computer's service

Saves and starts the computer’s one long-running program, replacing any previous one, and keeps it running. The command is a shell line, as for exec. A program that exits with a failure or is killed after it was ready starts again after 1 s, doubling up to 60 s, and restarts counts it. With port, the program is ready once the port accepts connections, and then the computer’s URL reaches it; without port (a bot or a worker), it is ready once it has stayed up 5 s, and the URL is unchanged. A program that ends before it is ready answers 409 with its exit and last stderr; one not ready after 60 seconds is kept, keeps starting in the background and answers 202. Install dependencies with a one-shot exec first: the command runs again on every restart. secrets names a secret set whose keys the program gets as environment variables when it starts, a key delivered by proxy as its stand-in; env adds plain values. On a site with no VM it gives the site its own VM first, which cannot be undone: its published files move to /home/runtime/app, and publishing to it stops. Once a port is exposed, the service answers every path but a site’s functions (/api), and a site’s files in /home/runtime/app are never served as files again, even after the port is removed. A later explicit exposure selection is independent of this process. Send an Idempotency-Key when a network failure might cause a retry.

POST

api

computers

{id}

service

run

Run the computer's service

curl --request POST \
  --url https://api.cool.computer/api/computers/{id}/service/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "node server.js",
  "port": 3000
}
'

import requests

url = "https://api.cool.computer/api/computers/{id}/service/run"

payload = {
    "command": "node server.js",
    "port": 3000
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({command: 'node server.js', port: 3000})
};

fetch('https://api.cool.computer/api/computers/{id}/service/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cool.computer/api/computers/{id}/service/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'command' => 'node server.js',
    'port' => 3000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cool.computer/api/computers/{id}/service/run"

	payload := strings.NewReader("{\n  \"command\": \"node server.js\",\n  \"port\": 3000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cool.computer/api/computers/{id}/service/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"command\": \"node server.js\",\n  \"port\": 3000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cool.computer/api/computers/{id}/service/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"command\": \"node server.js\",\n  \"port\": 3000\n}"

response = http.request(request)
puts response.read_body

{
  "configured": true,
  "status": "<string>",
  "ready": true,
  "restarts": 1,
  "url": "<string>",
  "command": "<string>",
  "cwd": "<string>",
  "port": 32768,
  "exec_id": "<string>",
  "pid": 2,
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "exit_code": 123,
  "signal": "<string>",
  "last_exit": {
    "code": 123,
    "at": "2023-11-07T05:31:56Z"
  },
  "last_output": "<string>",
  "logs": {
    "retention": "disk_ring",
    "bytes_written": 1,
    "bytes_dropped": 1,
    "dropped_frames": 1,
    "next_id": 1
  }
}

{
  "configured": true,
  "status": "<string>",
  "ready": true,
  "restarts": 1,
  "detail": "<string>",
  "url": "<string>",
  "command": "<string>",
  "cwd": "<string>",
  "port": 32768,
  "exec_id": "<string>",
  "pid": 2,
  "started_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "exit_code": 123,
  "signal": "<string>",
  "last_exit": {
    "code": 123,
    "at": "2023-11-07T05:31:56Z"
  },
  "last_output": "<string>",
  "logs": {
    "retention": "disk_ring",
    "bytes_written": 1,
    "bytes_dropped": 1,
    "dropped_frames": 1,
    "next_id": 1
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "code": "<string>",
  "detail": "<string>",
  "resolution": "<string>",
  "context": {},
  "suggestions": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

A Cool Computers API key, user access token, or claimed agent access token in the Authorization header. Follow https://www.cool.computer/auth.md for agent registration and https://www.cool.computer/authentication.md for direct user credentials.

Headers

Idempotency-Key

string

A caller-generated key for safely retrying this side effect. The server retains the key and response for 24 hours. Reusing it with the same request replays the original response, except after a failure that proves nothing happened: that is kept for one minute, and one that sets Retry-After is not kept, so a retry after it runs the request again; reusing it with different input returns 409.

Required string length: 1 - 128

Pattern: ^[!-~]+$

Example:

"req_01J6M6Y9TF9Q9QF6M1ZP8K4R2A"

Path Parameters

string

required

The computer's name, such as agent-atlas, or its id (cmp_…). Every caller may use either, the computer's own runtime token included.

Minimum string length: 1

Example:

"agent-atlas"

Body

application/json

command

string

required

Shell line that starts the long-running program. It runs again on every restart, so install dependencies with a one-shot exec first.

Minimum string length: 1

cwd

string

Absolute path to an existing directory, reached without symlinks, used to start the program; anything else answers 400 invalid_cwd. Omit it to use /home/runtime/app (created if missing) with a port, and /home/runtime without one, so a worker's files stay out of the published folder; status reports it. / and /home are refused with 400. /home/runtime is allowed: every credential file in it is under a hidden path, which the computer's URL never serves.

port

integer

Port the program listens on; it is ready once the port accepts connections, and the computer's URL then reaches it. Omit it for a program that serves no port, such as a bot or a worker. Platform ports 3129, 18080 and 18088 are reserved.

Required range: 1 <= x <= 65535

secrets

string

Secret set (PUT /api/secrets/{secret_set}) whose keys the program gets as environment variables each time the service starts; a key delivered by proxy arrives as its stand-in. A changed set reaches the program at its next restart (POST .../service/restart).

Required string length: 1 - 63

env

object

Plain environment variables for the program; names are letters, digits and , not starting with RUNTIME. Keep keys and tokens in a secret set instead.

Show child attributes

Response

The configured service and current process state.

configured

boolean

required

status

string

required

unconfigured; starting (the program runs but is not ready yet); running (ready); restarting (waiting to start the program again after a crash); stopped; exited (the program ended with code 0); failed; unknown or unavailable when the VM cannot say; or the computer's status while it is not running.

ready

boolean

required

With a port, the port accepts connections; without one, the program has stayed up 5 s.

restarts

integer

required

How often the program was started again after a crash since the service was last started.

Required range: x >= 0

url

string<uri>

command

string

cwd

string

port

integer

Absent for a program that serves no port.

Required range: 1 <= x <= 65535

exec_id

string

pid

integer

Required range: x >= 1

started_at

string<date-time>

ended_at

string<date-time>

exit_code

integer

signal

string

last_exit

object

The last crash it was restarted after.

Show child attributes

last_output

string

The program's last line of output, while it is not ready.

logs

object

Show child attributes

Start here

Your computer

Use it

Build with the API

Endpoint reference

Run the computer's service

Authorizations

Headers

Path Parameters

Body

Response