Services are persistent processes managed by systemd inside a computer. Use them for web servers, background workers, databases, or any daemon that should survive across exec calls and restart automatically on failure.

Base path: /api/v1/computers/{id}/services

Quick Start

import { Miosa } from '@miosa/sdk';

const client = new Miosa();

// Register and start a web server
const svc = await client.services.create(computerId, {
  name: 'webserver',
  command: 'python3 -m http.server 8080',
  cwd: '/home/user/app',
  restart: 'always',
});

console.log(svc.status); // "starting"

// Check status later
const updated = await client.services.get(computerId, svc.id);
console.log(updated.status); // "running"

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/services 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "webserver",
    "command": "python3 -m http.server 8080",
    "cwd": "/home/user/app",
    "restart": "always"
  }'

Endpoints

Create a Service

POST /api/v1/computers/{id}/services

Writes the systemd unit file and starts the service.

Request Body

Response — 201 Created

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "computer_id": "...",
    "tenant_id": "...",
    "name": "webserver",
    "command": "python3 -m http.server 8080",
    "env": {},
    "cwd": "/home/user/app",
    "restart": "always",
    "status": "starting",
    "pid": null,
    "exit_code": null,
    "last_started_at": null,
    "last_exited_at": null,
    "created_at": "2026-04-11T00:00:00Z",
    "updated_at": "2026-04-11T00:00:00Z"
  }
}

Status Values

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/services 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "api-server",
    "command": "/home/user/app/server",
    "env": {"PORT": "3000", "NODE_ENV": "production"},
    "cwd": "/home/user/app",
    "restart": "on-failure"
  }'

List Services

GET /api/v1/computers/{id}/services

Response — 200 OK

{
  "data": [
    {
      "id": "...",
      "name": "webserver",
      "status": "running",
      "pid": 12345,
      "restart": "always",
      "created_at": "2026-04-11T00:00:00Z"
    }
  ],
  "total": 1
}

curl https://api.miosa.ai/api/v1/computers/{id}/services 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Get a Service

GET /api/v1/computers/{id}/services/{name}

Path Parameters

Response — 200 OK

Full service object (same as create response).

Errors

Start, Stop, Restart

POST /api/v1/computers/{id}/services/{name}/start POST /api/v1/computers/{id}/services/{name}/stop POST /api/v1/computers/{id}/services/{name}/restart

All return a 200 OK with the updated service object.

Errors

# Stop a service
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/services/webserver/stop 
  -H "Authorization: Bearer $MIOSA_API_KEY"

# Restart it
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/services/webserver/restart 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Remove a Service

DELETE /api/v1/computers/{id}/services/{name}

Stops the service and removes the systemd unit file. The database record transitions to "removed" status.

Response — 200 OK

{
  "data": { "name": "webserver", "status": "removed" }
}

curl -X DELETE https://api.miosa.ai/api/v1/computers/{id}/services/webserver 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Common Recipes

Deploy a Node.js app as a service

// Upload app files first
await client.files.write(computerId, {
  path: '/home/user/app/server.js',
  content: serverJsContent,
});

// Register and start
const svc = await client.services.create(computerId, {
  name: 'node-app',
  command: 'node /home/user/app/server.js',
  env: { PORT: '3000' },
  restart: 'on-failure',
});

Wait until a service is running

import time

svc = client.services.create(computer_id, name="worker", command="/usr/bin/worker")
while svc.status == "starting":
    time.sleep(1)
    svc = client.services.get(computer_id, svc.name)

if svc.status != "running":
    raise RuntimeError(f"Service failed to start: {svc.status}")

Check for failed services in a fleet

const computers = await client.computers.list();
for (const computer of computers.data) {
  if (computer.status !== 'running') continue;
  const services = await client.services.list(computer.id);
  const failed = services.data.filter(s => s.status === 'failed');
  if (failed.length > 0) {
    console.log(`${computer.name}: ${failed.length} failed services`);
  }
}