### Start cluster runtime setup with post_system_compute_clusters_by_id_runtime

Source: https://openship.io/docs/guides/mcp-clusters-and-scaling

Starts the k3s installation and setup on the created cluster. Requires the cluster ID from the previous step and the returned revision. The setup verifies host identities and prerequisites before installing, then verifies node readiness, pod traffic, service routing, and internal DNS.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "post_system_compute_clusters_by_id_runtime",
    "arguments": {
      "organizationId": "org_example",
      "id": "cluster_from_create",
      "body": {
        "revision": 1,
        "requestId": "123e4567-e89b-42d3-a456-426614174001"
      }
    }
  }
}
```

--------------------------------

### Start Openship CLI

Source: https://openship.io/docs/cli/run

Starts the Openship CLI. On a fresh machine, it guides setup interactively; on an installed machine, it opens the control panel or resumes an interrupted setup.

```bash
openship
```

--------------------------------

### Start or resume iRedMail setup with POST /api/mail/setup

Source: https://openship.io/docs/api/mail

Kicks off the iRedMail install wizard against a server and streams progress as Server-Sent Events. The wizard is idempotent: re-POST with startStep to resume from where a previous run stopped. Only one install may run per instance at a time.

```http
POST /api/mail/setup
```

--------------------------------

### Installation commands compared

Source: https://openship.io/docs/cli/run

Installation commands compared: global CLI install, adding Ship SDK to a Node project, installing the desktop app, inspecting cached downloads, starting the local service, and removing local installation state (deployed apps remain running).

```bash
npm install -g openship
```

```bash
npm install openship
```

```bash
openship install
```

```bash
openship install cache
```

```bash
openship up
```

```bash
openship uninstall
```

--------------------------------

### POST /api/mail/setup

Source: https://openship.io/docs/api/mail

Start or resume the mail server install wizard. Returns an SSE stream.

```APIDOC
## POST /api/mail/setup

### Description
Start or resume the install wizard — returns an SSE stream.

### Method
POST

### Endpoint
/api/mail/setup

### Permissions
- `mail_server:write`
- Self-hosted only
```

--------------------------------

### Openship CLI mail setup, dns-ack, ptr-ack, status, scan, adopt commands

Source: https://openship.io/docs/guides/email-webmail

Self-hosted CLI provisioning flow for Openship webmail. Run `openship mail setup` to start the install; every other command resumes or inspects it. When setup pauses, the CLI prints the exact `--start-step` number to copy into the next `mail setup` command.

```bash
# Start the install on a server for your domain (streams live)
openship mail setup <serverId> --domain example.com

# When it pauses for DNS: publish the records, then acknowledge and resume
openship mail dns-ack <serverId>
openship mail setup <serverId> --domain example.com --start-step <n>

# When it pauses for reverse DNS: set the PTR, then acknowledge and resume
openship mail ptr-ack <serverId>
openship mail setup <serverId> --domain example.com --start-step <n>

# Check where things stand at any time
openship mail status <serverId>

# Re-adopt an existing install (after losing the dashboard's record of it)
openship mail scan <serverId>
openship mail adopt <serverId>
```

--------------------------------

### GET /api/mail/steps

Source: https://openship.io/docs/api/mail

List all setup steps and the total count.

```APIDOC
## GET /api/mail/steps

### Description
List all setup steps and the total count.

### Method
GET

### Endpoint
/api/mail/steps

### Permissions
- `mail_server:read`
- Self-hosted only
```

--------------------------------

### Add, list, check, and install a server via CLI

Source: https://openship.io/docs/guides/custom-servers

Commands to add a server (validates connection then saves), list servers to get the ID, check installed components, and install missing components while streaming logs. Requires being logged in (`openship login`) and on a self-hosted Openship.

```bash
# Add a server (this validates the connection, then saves it)
openship server add \
  --name production \
  --host 203.0.113.10 \
  --user root \
  --auth-method key \
  --key-path ~/.ssh/id_ed25519

# List your servers to grab the id you'll need below
openship server list

# See what's installed on that server
openship server check <server-id>

# Install the missing pieces, streaming the logs live
openship server install <server-id> --component docker git openresty --follow
```

--------------------------------

### GET /auth/callback/install

Source: https://openship.io/docs/api/auth

Complete the GitHub App browser handoff using installation state.

```APIDOC
## [GET] /auth/callback/install

### Description
Complete the GitHub App browser handoff using installation state.

### Method
GET

### Endpoint
/auth/callback/install
```

--------------------------------

### setupClusterRuntime

Source: https://openship.io/docs/api/servers

Starts the managed K3s runtime setup on a compute cluster. This is a separate operation that must be started after connecting servers to their private network.

```APIDOC
## setupClusterRuntime

### Description
Starts the managed K3s runtime setup on the specified compute cluster. This operation installs missing tools, pins and checksum-verifies K3s, configures private host firewall rules, joins the servers, and checks actual pod traffic, Services and DNS. It does not install software automatically; it must be explicitly started.

### Method
POST

### Endpoint
/servers/setupClusterRuntime

### Parameters
#### Request Body
- **clusterId** (string) - Required - Identifier of the compute cluster.
- **revision** (integer) - Required - Current revision of the compute cluster.
- **requestId** (string) - Required - Unique identifier for the request, used for idempotent retries.

### Request Example
{
  "clusterId": "cluster_id",
  "revision": 1,
  "requestId": "uuid"
}

### Response
#### Success Response (200)
- **status** (string) - Status of the runtime setup operation.

#### Response Example
{
  "status": "in_progress"
}
```

--------------------------------

### GET /api/system/install/stream

Source: https://openship.io/docs/api/servers

Streams installation progress. Requires server:read permission.

```APIDOC
## GET /api/system/install/stream

### Description
Streams installation progress. Requires server:read permission.

### Method
GET

### Endpoint
/api/system/install/stream

### Parameters
#### Query Parameters
- **input** (object) - Optional - The input for the stream.

### Response
#### Success Response (200)
- **stream** (stream) - The installation progress stream.

#### Response Example
{
  "stream": "data"
}

```

--------------------------------

### POST /api/mail/setup

Source: https://openship.io/docs/api/mail

Starts or resumes the iRedMail installation wizard on a server, streaming progress via Server-Sent Events.

```APIDOC
## POST /api/mail/setup

### Description
Kicks off the iRedMail install wizard against a server and streams progress as Server-Sent Events. The wizard is idempotent: re-POST with `startStep` to resume from where a previous run stopped (or was gated). Only one install may run per instance at a time.

### Method
POST

### Endpoint
/api/mail/setup

### Parameters
#### Request Body
- **serverId** (string) - Required - The Openship server to install onto.
- **domain** (string) - Required - The mail domain, e.g. example.com. Mail is served from mail.<domain>.
- **startStep** (number) - Optional - Step to start/resume from (clamped to 1..total). Default: 1.
- **config** (IRedMailConfig) - Optional - Optional install config (see below).

#### IRedMailConfig
- **adminPassword** (string) - Optional - Password for the postmaster account. Generated if absent.
- **storageBackend** ('mariadb' | 'postgresql') - Optional - iRedMail storage backend. Default: 'postgresql'.
- **prefillSecrets** (Record<string, string>) - Optional - Previously-generated secrets to reuse on a retry, keyed as iRedMail expects (e.g. VMAIL_DB_BIND_PASSWD).

### Request Example
```bash
curl -N -X POST "$OPENSHIP_URL/api/mail/setup" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123","domain":"example.com"}'
```

### Response
#### Success Response (200)
The stream emits `step_start`, `log`, and `step_done` events per step, plus these control events:
- `dns_records` / `dns_pending` — the DKIM step publishes the records you must add, then **holds**. Add the records at your DNS provider and call `POST /api/mail/setup/dns-ack`, then re-POST `/setup` with the `resumeStep` from the event.
- `ptr_pending` — after DNS is acknowledged, the wizard holds again for reverse-DNS (PTR). Set the PTR record at your VPS provider, call `POST /api/mail/setup/ptr-ack`, and resume.
- `complete` — carries `domain`, `webmailUrl`, and `adminUrl`.
- `error` — carries `message` and (when resumable) `resumeStep`.

The terminal `verify_reachability` step reads the target's TCP listener table and then connects from the API host to the public-DNS address on 25, 465, 587, and 993. Listener failures and off-box failures remain distinct in the result. A measured failure blocks completion and points at both the host firewall and the provider-level firewall/security group/security list/NSG; an unavailable probe is returned as a non-blocking warning rather than being invented as an outage.
```

--------------------------------

### openship mail setup command syntax

Source: https://openship.io/docs/cli/reference/mail

Starts or resumes the mail setup wizard, which streams over SSE. Requires a serverId. Options include -d/--domain, --start-step, and --config for iRedMail overrides.

```text
openship mail setup [options] <serverId>
```

--------------------------------

### POST /api/system/onboarding

Source: https://openship.io/docs/api/system

First-run setup; persists settings and creates the first server.

```APIDOC
## [POST] /api/system/onboarding

### Description
First-run setup; persists settings and creates the first server. Returns 403 once configured.

### Method
POST

### Endpoint
/api/system/onboarding

### Response
#### Success Response (200)
No response body details provided.

#### Error Response (403)
Returned once the system is already configured.
```

--------------------------------

### POST /api/system/setup

Source: https://openship.io/docs/api/system

Pushes instance config from the desktop app.

```APIDOC
## [POST] /api/system/setup

### Description
Pushes instance config from the desktop app.

### Method
POST

### Endpoint
/api/system/setup

### Response
#### Success Response (200)
No response body details provided.
```

--------------------------------

### Start or resume iRedMail setup with curl

Source: https://openship.io/docs/api/mail

Example curl command to start or resume the iRedMail setup wizard. Sends a POST request with serverId and domain in the JSON body. Requires OPENSHIP_URL and OPENSHIP_TOKEN environment variables.

```bash
curl -N -X POST "$OPENSHIP_URL/api/mail/setup" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123","domain":"example.com"}'
```

--------------------------------

### POST /api/system/onboarding

Source: https://openship.io/docs/api/system

Performs initial setup of the instance. Only works while the instance is unconfigured; returns 403 afterward.

```APIDOC
## POST /api/system/onboarding

### Description
Runs the same logic as the internal `/setup` push but only while the instance is unconfigured. Returns **403 "Instance already configured"** afterward, so first-run flows don't need a token.

### Method
POST

### Endpoint
/api/system/onboarding

### Parameters
#### Request Body
- **sshHost** (string) - Optional - SSH host / IP of the target server. When present, a server row is created.
- **serverName** (string) - Optional - Display name for the server.
- **sshPort** (number) - Optional - SSH port. Default: `22`.
- **sshUser** (string) - Optional - SSH user. Default: `root`.
- **sshAuthMethod** (string) - Optional - Auth method: password, key, or agent.
- **sshPassword** (string) - Optional - SSH password (encrypted at rest).
- **sshKeyPath** (string) - Optional - Path to a private key on the host.
- **sshKeyPassphrase** (string) - Optional - Private-key passphrase (encrypted at rest).
- **sshJumpHost** (string) - Optional - SSH jump / bastion host.
- **sshTransport** (string) - Optional - Connection transport: direct (default) or cloudflare for a Cloudflare Access SSH application.
- **sshArgs** (string) - Optional - Allowed SSH connection tuning arguments; arbitrary local commands are rejected.
- **authMode** (string) - Optional - Instance auth mode. Default: `none`. Allowed values: `none`, `local`, `cloud`.
- **tunnelProvider** (string) - Optional - Tunnel provider.
- **tunnelToken** (string) - Optional - Tunnel token.
- **defaultBuildMode** (string) - Optional - Default build mode for new deployments. Default: `auto`.
- **defaultRollbackWindow** (number) - Optional - How many past releases to retain for rollback.

### Response
#### Success Response (200)
- **configured** (boolean) - `true` once at least one server exists.

#### Response Example
{
  "configured": true
}
```

--------------------------------

### POST /api/system/setup

Source: https://openship.io/docs/api/system

Performs setup for the desktop app. Requires the `internalAuth` shared token. Can target an existing server by passing `serverId`.

```APIDOC
## POST /api/system/setup

### Description
Reserved for the desktop app. Requires the `internalAuth` shared token rather than a user session. Can target an existing server by passing `serverId`.

### Method
POST

### Endpoint
/api/system/setup

### Parameters
#### Request Body
- **sshHost** (string) - Optional - SSH host / IP of the target server. When present, a server row is created.
- **serverName** (string) - Optional - Display name for the server.
- **sshPort** (number) - Optional - SSH port. Default: `22`.
- **sshUser** (string) - Optional - SSH user. Default: `root`.
- **sshAuthMethod** (string) - Optional - Auth method: password, key, or agent.
- **sshPassword** (string) - Optional - SSH password (encrypted at rest).
- **sshKeyPath** (string) - Optional - Path to a private key on the host.
- **sshKeyPassphrase** (string) - Optional - Private-key passphrase (encrypted at rest).
- **sshJumpHost** (string) - Optional - SSH jump / bastion host.
- **sshTransport** (string) - Optional - Connection transport: direct (default) or cloudflare for a Cloudflare Access SSH application.
- **sshArgs** (string) - Optional - Allowed SSH connection tuning arguments; arbitrary local commands are rejected.
- **authMode** (string) - Optional - Instance auth mode. Default: `none`. Allowed values: `none`, `local`, `cloud`.
- **tunnelProvider** (string) - Optional - Tunnel provider.
- **tunnelToken** (string) - Optional - Tunnel token.
- **defaultBuildMode** (string) - Optional - Default build mode for new deployments. Default: `auto`.
- **defaultRollbackWindow** (number) - Optional - How many past releases to retain for rollback.
- **serverId** (string) - Optional - ID of an existing server to target.

### Response
#### Success Response (200)
- **configured** (boolean) - `true` once at least one server exists.

#### Response Example
{
  "configured": true
}
```

--------------------------------

### GET /api/system/setup

Source: https://openship.io/docs/api/system

Reads instance config for the desktop app.

```APIDOC
## [GET] /api/system/setup

### Description
Reads instance config for the desktop app.

### Method
GET

### Endpoint
/api/system/setup

### Response
#### Success Response (200)
No response body details provided.
```

--------------------------------

### setupClusterStorage

Source: https://openship.io/docs/api/servers

Starts shared storage setup on the cluster. It installs required tools, checks the selected empty directories, configures shared storage and verifies a write/read across servers. It never formats disks.

```APIDOC
## setupClusterStorage

### Description
Starts shared storage setup on the cluster. It installs required tools, checks the selected empty directories, configures shared storage and verifies a write/read across servers. It never formats disks. The setup accepts the reviewed disks, copy count and a stable request ID.

### Method
POST

### Endpoint
/servers/setupClusterStorage

### Parameters
#### Request Body
- **clusterId** (string) - Required - Identifier of the compute cluster.
- **disks** (array of string) - Required - List of disk identifiers to use for shared storage.
- **copyCount** (integer) - Required - Number of copies to configure.
- **requestId** (string) - Required - Unique identifier for the request, used for idempotent retries.

### Request Example
{
  "clusterId": "cluster_id",
  "disks": ["disk_1", "disk_2"],
  "copyCount": 2,
  "requestId": "uuid"
}

### Response
#### Success Response (200)
- **status** (string) - Status of the storage setup operation.

#### Response Example
{
  "status": "in_progress"
}
```

--------------------------------

### openship app settings get command

Source: https://openship.io/docs/cli/reference/app

Gets settings for an installed app project. The project argument is the installed app project ID.

```text
openship app settings get [options] <project>
```

--------------------------------

### POST /api/system/onboarding

Source: https://openship.io/docs/api/system

Runs the same logic as the internal /setup push but only while the instance is unconfigured. Returns 403 "Instance already configured" afterward, so first-run flows don't need a token.

```http
POST /api/system/onboarding
```

--------------------------------

### Get a guided prompt with curl

Source: https://openship.io/docs/api/mcp

Fetches a prompt from the MCP prompts catalog using JSON-RPC prompts/get. The example requests the deploy-from-git prompt with a repo argument. Prompts are ordered playbooks that reference exact tool names and are surfaced as slash-commands by MCP clients.

```bash
curl -s "$OPENSHIP_URL/api/mcp" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"prompts/get",
       "params":{"name":"deploy-from-git","arguments":{"repo":"acme/widgets"}}}'
```

--------------------------------

### Run first-run setup with openship system onboarding

Source: https://openship.io/docs/cli/reference/system

First-run instance setup command. The apply subcommand configures a fresh instance and fails once already configured.

```text
openship system onboarding [options] [command]
```

--------------------------------

### Install openship with the install script

Source: https://openship.io/docs/getting-started/installation

One-line installer for the openship CLI on macOS/Linux. Requires no Node or npm setup; installs a self-contained, checksum-verified bundle that runs under Node.

```bash
curl -fsSL https://get.openship.io | sh
```

--------------------------------

### POST /api/system/install/stream

Source: https://openship.io/docs/api/servers

Starts an installation session and returns a Server-Sent Events stream with `progress`, `log`, `complete`, and `end` events. Returns `409 install_in_progress` if a session is already running.

```APIDOC
## [POST] /api/system/install/stream

### Description
Starts an installation session and returns a Server-Sent Events stream with `progress`, `log`, `complete`, and `end` events. Returns `409 install_in_progress` if a session is already running.

### Method
POST

### Endpoint
/api/system/install/stream

### Parameters
#### Request Body
- **serverId** (string) - Required - The saved server to install onto.
- **components** (string[]) - Required - List of component names to install.
- **config** (object) - Optional - Optional installer-specific configuration.

### Request Example
{
  "serverId": "srv_123",
  "components": ["docker"],
  "config": {}
}

### Response
#### Success Response (200)
- **progress** (event) - Progress event.
- **log** (event) - Log event.
- **complete** (event) - Completion event.
- **end** (event) - End event.

#### Error Response (409)
- **install_in_progress** (string) - Error code indicating a session is already running.
```

--------------------------------

### Run the Linux AppImage

Source: https://openship.io/docs/getting-started/installation

On Linux, make the AppImage runnable and start it without an installer or root. Most distros ship FUSE; if it won't start, install FUSE or run with --appimage-extract-and-run.

```bash
chmod +x Openship.AppImage
./Openship.AppImage
```

--------------------------------

### getClusterRuntime

Source: https://openship.io/docs/api/servers

Reads saved progress of the cluster runtime setup. Returns null before setup is started.

```APIDOC
## getClusterRuntime

### Description
Reads the saved progress of the cluster runtime setup for the specified compute cluster. Returns `null` before setup is started.

### Method
GET

### Endpoint
/servers/getClusterRuntime/{clusterId}

### Parameters
#### Path Parameters
- **clusterId** (string) - Required - Identifier of the compute cluster.

### Response
#### Success Response (200)
- **status** (string) - Current status of the runtime setup.
- **sequence** (integer) - Current sequence number of the setup operation.

#### Response Example
{
  "status": "in_progress",
  "sequence": 1
}
```

--------------------------------

### GET /api/system/onboarding

Source: https://openship.io/docs/api/system

First-run check — is any server configured yet?

```APIDOC
## [GET] /api/system/onboarding

### Description
First-run check — is any server configured yet?

### Method
GET

### Endpoint
/api/system/onboarding

### Response
#### Success Response (200)
No response body details provided.
```

--------------------------------

### GET /api/mail/status

Source: https://openship.io/docs/api/mail

Get the current setup progress for a server, rendered from its on-server state file.

```APIDOC
## GET /api/mail/status

### Description
Current setup progress for a server (rendered from its on-server state file).

### Method
GET

### Endpoint
/api/mail/status

### Permissions
- `mail_server:read`
- Self-hosted only
```

--------------------------------

### POST /api/auth/sign-up/*

Source: https://openship.io/docs/api/auth

Handle sign-up with the installation's account-creation policy.

```APIDOC
## [POST] /api/auth/sign-up/*

### Description
Handle sign-up with the installation's account-creation policy.

### Method
POST

### Endpoint
/api/auth/sign-up/*
```

--------------------------------

### Start OpenResty service with systemctl

Source: https://openship.io/docs/troubleshooting/servers-ssh

Use this command to start the OpenResty service when it is installed but not running. After starting, use the Re-check action to verify health.

```bash
systemctl start openresty
```

--------------------------------

### GET /api/system/compute-clusters/:id/runtime

Source: https://openship.io/docs/api/servers

Reads saved K3s setup, verification and cleanup progress; null before setup.

```APIDOC
## GET /api/system/compute-clusters/:id/runtime

### Description
Reads saved K3s setup, verification and cleanup progress; null before setup.

### Method
GET

### Endpoint
/api/system/compute-clusters/:id/runtime

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the compute cluster.

### Response
#### Success Response (200)
- **runtime** (object|null) - The runtime progress or null if not started.

#### Response Example
{
  "runtime": null
}
```

--------------------------------

### POST /api/system/install/respond

Source: https://openship.io/docs/api/servers

Answers a pending installation prompt. Requires server:admin permission.

```APIDOC
## POST /api/system/install/respond

### Description
Answers a pending installation prompt. Requires server:admin permission.

### Method
POST

### Endpoint
/api/system/install/respond

### Parameters
#### Request Body
- **input** (object) - Required - The response input.

### Request Example
{
  "input": {}
}

### Response
#### Success Response (200)
- **status** (string) - Operation status.

#### Response Example
{
  "status": "ok"
}

```

--------------------------------

### Start Docker service with systemctl

Source: https://openship.io/docs/troubleshooting/servers-ssh

Use this command to start the Docker daemon if it is installed but not running. Combine with 'systemctl enable docker' to ensure it starts on boot.

```bash
systemctl start docker
```

--------------------------------

### Install app with REST API (curl)

Source: https://openship.io/docs/api/apps

Installs a template app using the Openship REST API. The example sends a POST request to /api/apps with the same payload as the SDK example. Requires OPENSHIP_URL and OPENSHIP_TOKEN environment variables.

```bash
curl -X POST "$OPENSHIP_URL/api/apps" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "ghost",
    "name": "my-blog",
    "routes": [
      { "service": "ghost", "port": 2368, "mode": "custom", "customDomain": "blog.acme.com" }
    ]
  }'
```

--------------------------------

### Connect and deploy with Openship CLI

Source: https://openship.io/docs/cli

Connects to an existing installation or starts a local one, then lists projects, links the current directory to a project, and deploys with progress tracking. login opens the token settings page and asks for a personal access token; init links the current directory; deploy --watch submits a deployment and follows its progress.

```bash
openship login \
  --api-url https://ship.example.com \
  --dashboard-url https://ship.example.com \
  --context production

openship project list
openship init --project proj_123
openship deploy --watch
```

--------------------------------

### GET /api/system/health

Source: https://openship.io/docs/api/system

Reads installation health.

```APIDOC
## [GET] /api/system/health

### Description
Reads installation health.

### Method
GET

### Endpoint
/api/system/health

### Response
#### Success Response (200)
No response body details provided.
```

--------------------------------

### POST /api/system/install/stream

Source: https://openship.io/docs/api/servers

Submits installation of selected components. Requires server:admin permission.

```APIDOC
## POST /api/system/install/stream

### Description
Submits installation of selected components. Requires server:admin permission.

### Method
POST

### Endpoint
/api/system/install/stream

### Parameters
#### Path Parameters
- **id** (string) - Required - The server identifier.

#### Request Body
- **input** (object) - Required - The installation input.

### Request Example
{
  "input": {}
}

### Response
#### Success Response (200)
- **stream** (stream) - The installation progress stream.

#### Response Example
{
  "stream": "data"
}

```

--------------------------------

### Install openship package

Source: https://openship.io/docs/api/sdk/installation

Installs the openship package from npm, which includes the Ship SDK and CLI starting with version 0.8.0.

```bash
npm install openship
```

--------------------------------

### GET /api/system/self-register/stream

Source: https://openship.io/docs/api/system

Streams installation registration progress.

```APIDOC
## [GET] /api/system/self-register/stream

### Description
Streams installation registration progress.

### Method
GET

### Endpoint
/api/system/self-register/stream

### Response
#### Success Response (200)
No response body details provided.
```

--------------------------------

### POST /api/system/install

Source: https://openship.io/docs/api/servers

Installs a single component onto a saved server. The component name is validated against an allowlist.

```APIDOC
## [POST] /api/system/install

### Description
Installs a single component onto a saved server. The component name is validated against an allowlist.

### Method
POST

### Endpoint
/api/system/install

### Parameters
#### Request Body
- **serverId** (string) - Required - The saved server to install onto.
- **component** (string) - Required - A single installable component name (e.g. docker, openresty, certbot). Validated against an allowlist.
- **config** (object) - Optional - Optional installer-specific configuration. Default: `{}`.

### Request Example
{
  "serverId": "srv_123",
  "component": "docker",
  "config": {}
}

### Response
#### Success Response (200)
- **components** (array) - The components checked.
- **ready** (boolean) - Whether the server is ready.
- **missing** (array) - Components that are missing.

#### Response Example
{
  "components": ["docker"],
  "ready": true,
  "missing": []
}
```

--------------------------------

### GET /api/system/diagnostics

Source: https://openship.io/docs/api/system

Reads database and installation health.

```APIDOC
## [GET] /api/system/diagnostics

### Description
Reads database and installation health.

### Method
GET

### Endpoint
/api/system/diagnostics

### Response
#### Success Response (200)
No response body details provided.
```

--------------------------------

### openship init command syntax

Source: https://openship.io/docs/cli/reference/init

Links the current directory to an Openship project by creating a .openship/project.json file. Options include --project to skip the picker, --environment to set the default deploy environment (default: "production"), --dir to specify the directory (default: "."), --force to overwrite an existing link, and -y/--yes for non-interactive mode that fails instead of prompting.

```text
openship init [options]
```

--------------------------------

### SDK deployment info example

Source: https://openship.io/docs/api/health

Uses the SDK to read deployment information. The result is logged to the console. This route is static and cache-friendly, and falls back to safe defaults if the database is unavailable mid-migration.

```ts
const result = await ship.system.info();
console.log(result);
```

--------------------------------

### Create native installation and deploy with createShip()

Source: https://openship.io/docs/api/sdk/native

Creates a native Openship installation with createShip(), sets up a demo session map for identity resolution, and deploys a static file app. Requires OPENSHIP_ENCRYPTION_KEY (at least 32 bytes) and the SDK installed. The example uses bare runtime with routing: "none" and allowHostExecution: true; it prints the project ID and deployment status on success.

```ts
import { randomUUID } from "node:crypto";
import { resolve } from "node:path";
import { createShip, type VerifiedIdentity } from "openship/native";

const encryptionKey = process.env.OPENSHIP_ENCRYPTION_KEY;
if (!encryptionKey) throw new Error("Set OPENSHIP_ENCRYPTION_KEY");
const sessions = new Map<string, VerifiedIdentity>();
const stateDirectory = resolve("./ship-state");
const ship = await createShip({
  instanceId: "my-product",
  stateDirectory,
  storage: { driver: "pglite", dataDir: resolve(stateDirectory, "database") },
  encryptionKey,
  runtime: "bare",
  routing: "none",
  policy: { allowHostExecution: true },
  administration: true,
  identity: { resolve: async (assertion: string) => sessions.get(assertion) ?? null },
});

try {
  if (!ship.operator) throw new Error("Host administration is required for this example");
  const person = await ship.operator.ensureIdentity({
    issuer: "my-product",
    subject: "customer-123",
    email: "customer@example.com",
  });
  const assertion = randomUUID();
  sessions.set(assertion, { user: person.user, sessionId: assertion });
  await ship.start();
  const customer = await ship.scope({
    identity: assertion,
    organizationId: person.personalOrganizationId,
  });
  const submitted = await customer.deploy({
    name: "generated-app",
    source: { type: "files", files: { "index.html": "<h1>Hello</h1>" } },
  });
  const outcome = await customer
    .deployment(submitted.deployment_id)
    .wait({ timeoutMs: 60_000 });
  if (!outcome.success) throw new Error(outcome.message ?? outcome.status);
  console.log(submitted.project_id, outcome.status);
} finally {
  await ship.close({ mode: "drain" });
}
```

--------------------------------

### GET /api/notices/all

Source: https://openship.io/docs/api/notices

Lists all installation notices, including inactive ones, using operator authority. Requires the installation's internal operator token.

```APIDOC
## GET /api/notices/all

### Description
Lists all installation notices, including inactive ones, using operator authority. Requires the installation's internal operator token.

### Method
GET

### Endpoint
/api/notices/all

### Headers
- **X-Internal-Token** (string) - Required - Internal operator token for authentication.

### Response
#### Success Response (200)
- **notices** (array) - List of all notices, including inactive ones.
```

--------------------------------

### Set up managed K3s runtime with ship.servers.setupClusterRuntime

Source: https://openship.io/docs/api/servers

Starts the separate runtime operation after connecting the selected servers to their private network. Setup installs missing tools, pins and checksum-verifies K3s, configures private host firewall rules, joins the servers, and checks actual pod traffic, Services and DNS. One control server is used for one/two-member pools; larger pools use three controls and additional workers. Initial support requires Linux amd64/arm64, systemd, root or passwordless sudo, disabled swap, and unfiltered or raw iptables host firewalls. Provider private-network ACLs remain the operator's responsibility; the dashboard lists exact private peer ports. These ports should not be exposed publicly.

```ts
const runtime = await ship.servers.setupClusterRuntime({
  clusterId: "cluster_id",
  revision: 1,
  requestId: crypto.randomUUID(),
});
console.log(runtime.status);

const abort = new AbortController();
for await (const event of ship.servers.clusterRuntimeEvents("cluster_id", { signal: abort.signal })) {
  console.log(event.data);
  abort.abort(); // Close the subscription when leaving the setup view.
  break;
}
```

--------------------------------

### Get current session - curl example

Source: https://openship.io/docs/api/auth

Example curl command to retrieve the current session using the session cookie. The cookie name is openship.session_token.

```bash
curl "$OPENSHIP_URL/api/auth/get-session" \
  -H "Cookie: openship.session_token=<session>"
```

--------------------------------

### GET /api/system/cloud-status

Source: https://openship.io/docs/api/system

Reads the installation's Cloud connection status.

```APIDOC
## [GET] /api/system/cloud-status

### Description
Reads the installation's Cloud connection status.

### Method
GET

### Endpoint
/api/system/cloud-status

### Response
#### Success Response (200)
No response body details provided.
```