> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# techstack api servers

> techstack api servers 命令的生成参考

<Note>由 Techstack v0.39.0 版本生成（源码 `49677b729cb9`）。对于已安装的版本，请以 `techstack api <command> --help` 为准。</Note>

## techstack api servers detach

吊销并分离一台确切的、由客户自行运营的 BYO 服务器。

保留终态的规范服务器回执，且不执行任何提供商 API 调用。

```bash theme={null}
techstack api servers detach <server-id> [flags]
```

<Warning>需要确认：此操作会吊销该服务器的凭据并将其移出管理，而不会触碰该机器。传入 `--yes` 或回答提示；未使用 `--yes` 的非交互式运行会在发出任何请求之前以退出码 9 停止。</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/servers/{serverId}/detach` |
| 更改状态 | 是 |
| MCP 工具 | `detach_self_owned_server` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范的服务器运行时 ID。 |
| `--confirm-server-id` | string | **必填。** 必须与 serverId 路径参数完全相同。 |
| `--body` | json | JSON 请求正文（`application/json`），可以是字面量、`@path`，或用 `-` 表示 stdin。 |

## techstack api servers get

获取规范的服务器生命周期、连接、健康状况和通道。

```bash theme={null}
techstack api servers get <server-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/{serverId}` |
| 更改状态 | 否 |
| MCP 工具 | `get_server_runtime` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范的服务器运行时 ID。 |

## techstack api servers list

列出规范的 Node 运行时状态。

返回按所有者限定的 Node，带有规范的 `node_id` 和 `kit_deployment_id` 身份。

```bash theme={null}
techstack api servers list [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers` |
| 更改状态 | 否 |
| MCP 工具 | `list_server_runtimes` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `--kit-deployment-id` | string | — |

## techstack api servers maintenance get

读取某台自有服务器的一个维护任务。

范围与 POST 相同：由 Edge 签名的 `techstack.servers.maintenance` 权益、租户、服务器的所有权，以及属于此服务器且由调用方请求的任务。其他任何情况均返回 404。维护任务有自己的账本，不通过 `/api/v1/jobs/&#123;id&#125;` 提供。没有日志端点：任务本身携带其结果，失败时携带稳定的代码和用户指引。

```bash theme={null}
techstack api servers maintenance get <server-id> <job-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/{serverId}/actions/{jobId}` |
| 更改状态 | 否 |
| MCP 工具 | `get_server_maintenance_job` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范的服务器运行时 ID。 |
| `<job-id>` | string | **必填。** |

## techstack api servers maintenance run

为拥有的服务器排队执行操作系统更新计划、操作系统更新或重启。

需要 Edge 签名的 `techstack.servers.maintenance` 权益、租户内的服务器所有权，以及委托原生 MCP 调用所需的当前服务器绑定常设权限。这三种常规操作不需要新的 MFA 登录或单独的 owner\_approved 声明。请求体严格解码：键名必须精确且小写，不允许重复键或未知字段。相同 Idempotency-Key 的重放会在目标验证前返回已存储回执。每台服务器可同时有一项重启或操作系统更新，以及单独一项更新计划；任务未在期限内完成时以 `deadline_exceeded` 失败并释放槽位。仅当服务器代理声明 `stackkit.host-maintenance.v1` 时才在 `allowed_actions` 中提供该操作；重启还要求服务器报告 `host_boot_id`。拒绝响应为 client-error-envelope/v1；409 的 `reason_code` 可为 control\_plane\_host、substrate\_node、protected\_demo\_server、service\_locked、maintenance\_active、node\_operation\_active、plan\_stale、agent\_capability\_missing、boot\_id\_unknown、agent\_not\_connected、heartbeat\_stale、inventory\_revision\_stale 或 idempotency\_key\_reused；403 携带 entitlement\_required 或 maintenance\_origin\_authority\_denied。

```bash theme={null}
techstack api servers maintenance run <server-id> [flags]
```

| | |
| - | - |
| HTTP | `POST /api/v1/servers/{serverId}/actions` |
| 更改状态 | 是 |
| MCP 工具 | `run_server_maintenance_action` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范的服务器运行时 ID。 |
| `--action` | string | **必填。** 可选值：`os_update_plan`、`os_update`、`reboot`。 |
| `--expected-inventory-revision` | integer | **必填。** |
| `--expected-plan-digest` | string | 仅适用于 os\_update：此服务器已完成、且不超过 15 分钟的 os\_update\_plan 的 plan\_digest。 |
| `--owner-approved` | boolean | 可选的旧字段；不会授予维护权限。 |
| `--body` | json | JSON 请求正文（`application/json`），可以是字面量、`@path`，或用 `-` 表示 stdin。 |

## techstack api servers network get

读取服务器的网络事实和已记录的家庭网络迁移。

包括服务器的 kombify Guard 最近观测到的网络（地址、网关、子网、接口和 WiFi 网络）、服务器出现在另一网络时 kombify 写入的 `network_move` 记录，以及随后重新绑定的状态。迁移后的服务器会自动重新绑定；`can_rebind` 表示所有者现在是否可以启动重新绑定。

```bash theme={null}
techstack api servers network get <server-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/{serverId}/network` |
| 更改状态 | 否 |
| MCP 工具 | `get_server_network` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |

## techstack api servers network rebind

将已迁移的服务器重新绑定到当前网络。

通过服务器的 kombify Guard 运行 `stackkit network rebind`：节点重新检测 LAN 地址，重新签发已签名的 LAN DNS 保管记录，并重新生成和应用工作区。请求没有请求体。需要所有者、Inventory 的 operate 授权、`techstack.servers.maintenance` 权益和已连接的 Guard，否则返回 409 `server_network_not_ready`。已有排队或运行中的重新绑定时返回该任务，不会再次排队。

```bash theme={null}
techstack api servers network rebind <server-id> [flags]
```

<Warning>需要确认：此操作重新检测服务器当前网络地址，重新签发已签名的本地 DNS 记录，并重新应用其工作区。传入 `--yes` 或回答提示；非交互式运行未提供 `--yes` 时，会在发出任何请求前以退出码 9 停止。</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/servers/{serverId}/network/rebind` |
| 更改状态 | 是 |
| MCP 工具 | `rebind_server_network` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |

## techstack api servers ports

获取经过认证的所有者在某台规范服务器上的端口清单。

服务器详情 UI 投影，基于与 Inventory/MCP 接口相同的中央端口授权，并通过规范的、按所有者限定的服务器读取边界进行授权。

```bash theme={null}
techstack api servers ports <server-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/{serverId}/ports` |
| 更改状态 | 否 |
| MCP 工具 | `get_server_runtime_ports` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范的服务器运行时 ID。 |

## techstack api servers reach set

将服务器发布到 kombify.me 地址，或停止发布。

默认不发布任何内容：已配对服务器没有公开路由，中继也不承载流量。所有者为每台服务器指定 `service` 名称和 `target_port` 后启用，并可随时撤销；源站始终是 Guard 主机的回环地址，绝不是其他机器。中继验证 Guard，而非访客，因此该端口上的服务必须自行保护。启用需要所有者、`techstack.servers.maintenance` 权益及新的多因素登录（原因 `server_reach_step_up_required`）；撤销不会受此门槛限制。响应返回服务器读取模型中的 reach 部分；随后由协调器创建或撤销路由。

```bash theme={null}
techstack api servers reach set <server-id> [flags]
```

<Warning>需要确认：此操作将服务器服务发布到公开的 kombify.me 地址，互联网上任何人都可以打开。传入 `--yes` 或回答提示；非交互式运行未提供 `--yes` 时，会在发出任何请求前以退出码 9 停止。</Warning>

| | |
| - | - |
| HTTP | `PUT /api/v1/servers/{serverId}/reach` |
| 更改状态 | 是 |
| MCP 工具 | 无 |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |
| `--enabled` | boolean | **必填。** |
| `--service` | string | 启用时必填。路由标签；kombify.me 路由为 \<base>-\<service>-\<server suffix>。 |
| `--target-port` | integer | 启用时必填。服务监听的端口，位于固定 Guard 主机的回环地址上。 |
| `--target-scheme` | string | 可选值：`http`, `https`. 默认值 `"http"`. |
| `--body` | json | JSON 请求体（`application/json`），可以是字面值、`@path`，或使用 `-` 从 stdin 读取。 |

## techstack api servers security auto-repair get

读取所有者对自动安全修复的批准。

未获得批准或批准已过期的服务器仅进行观测。

```bash theme={null}
techstack api servers security auto-repair get <server-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/{serverId}/security/auto-repair` |
| 更改状态 | 否 |
| MCP 工具 | `get_server_security_auto_repair` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |

## techstack api servers security auto-repair set

批准或撤销对一小组安全控制项的自动修复。

默认关闭。批准从安全集合中指定控制项（`allowed_controls`：暴力破解防护、防火墙策略、内核参数和自动安全更新；绝不包括 ssh 控制项），有效期最多 90 天，且不会自动续期。批准有效时，控制平面在与操作员修复相同的边界内，修复新鲜证据显示发生偏离的指定控制项。需要所有者、`techstack.servers.maintenance` 权益及新的多因素登录。`enabled: false` 撤销批准。

```bash theme={null}
techstack api servers security auto-repair set <server-id> [flags]
```

<Warning>需要确认：此操作允许 kombify Guard 在批准到期前修复指定的主机安全控制项，无需每次询问。传入 `--yes` 或回答提示；非交互式运行未提供 `--yes` 时，会在发出任何请求前以退出码 9 停止。</Warning>

| | |
| - | - |
| HTTP | `PUT /api/v1/servers/{serverId}/security/auto-repair` |
| 更改状态 | 是 |
| MCP 工具 | 无 |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |
| `--controls` | string\[] | — |
| `--enabled` | boolean | **必填。** |
| `--expires-at` | string | — |
| `--body` | json | JSON 请求体（`application/json`），可以是字面值、`@path`，或使用 `-` 从 stdin 读取。 |

## techstack api servers security findings

列出一台服务器的未解决发现和近期发现历史。

这是服务器 `security`、`recovery` 和 Guard 告警背后的发现账本。每条发现对应一次事件：首次观测到事实不正确时打开，恢复正确时解决，最多各记录一次告警（`alerted_at`）和一次解决。历史保留 90 天。

```bash theme={null}
techstack api servers security findings <server-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/{serverId}/security/findings` |
| 更改状态 | 否 |
| MCP 工具 | `list_server_security_findings` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |

## techstack api servers security repairs list

列出一台服务器最近的安全修复。

```bash theme={null}
techstack api servers security repairs list <server-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/{serverId}/security/repairs` |
| 更改状态 | 否 |
| MCP 工具 | `list_server_security_repairs` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |

## techstack api servers security repairs request

修复指定的、发生偏离的主机安全控制项。

请求在限定范围内修复新鲜主机安全证据显示发生偏离且可自动修复的控制项。需要服务器所有者、Edge 签名的 `techstack.servers.maintenance` 权益及新的多因素登录（最多 300 秒前）。修复作为带类型、记入日志的 Guard 命令，针对指定控制项运行 `stackkit host security repair --apply`；StackKits 会在变更前拒绝可能切断管理路径或将所有者锁在系统外的变更。限制包括：每台服务器同时仅一次修复（409 `repair_in_progress`）、每个控制项的冷却期（429 `repair_cooldown`）、每日尝试预算（429 `repair_attempts_exhausted`）及连续失败后的熔断（429 `repair_circuit_open`）；429 响应携带 `retry_after`。已合规（409 `control_not_drifted`）、有批准例外（`control_has_exception`）、需要手工修复（`control_not_repairable`）、缺少授权 SSH 密钥（`needs_authorized_key`）或未被观测的控制项均被拒绝。请求体严格解码。

```bash theme={null}
techstack api servers security repairs request <server-id> [flags]
```

<Warning>需要确认：此操作通过服务器的 kombify Guard 恢复指定的主机安全控制项（防火墙、ssh、暴力破解防护和自动更新）。传入 `--yes` 或回答提示；非交互式运行未提供 `--yes` 时，会在发出任何请求前以退出码 9 停止。</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/servers/{serverId}/security/repairs` |
| 更改状态 | 是 |
| MCP 工具 | 无 |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |
| `--controls` | string\[] | **必填。** |
| `--body` | json | JSON 请求体（`application/json`），可以是字面值、`@path`，或使用 `-` 从 stdin 读取。 |

## techstack api servers security verify

请求 kombify Guard 进行一次新的主机安全观测。

记录需要重新观测主机基线。Guard 在下一次签到时（约一分钟内）返回新报告；不会改变主机上的任何内容。服务器的 `security` 读取模型只由该报告更新，绝不由此请求更新。其他租户或所有者的服务器返回 404；没有 Guard 的服务器返回 409 `guard_not_connected`。

```bash theme={null}
techstack api servers security verify <server-id> [flags]
```

| | |
| - | - |
| HTTP | `POST /api/v1/servers/{serverId}/security/verify` |
| 更改状态 | 是 |
| MCP 工具 | 无 |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范服务器运行时 ID。 |

## techstack api servers summary

读取经过认证的所有者的服务器存在情况摘要。

只返回一个计数和存在标志，其租户和所有者策略范围与规范清单列表相同。可选的 tenant 查询参数是为了兼容 Gateway 而存在，必须与已认证身份中的租户完全一致；不一致时会在读取任何存储之前被拒绝。不返回任何服务器、租户或主体标识符。

```bash theme={null}
techstack api servers summary [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/summary` |
| 更改状态 | 否 |
| MCP 工具 | 无 |

| 参数 | 类型 | 说明 |
| - | - | - |
| `--tenant` | string | — |

## techstack api servers transitions

列出已持久化的服务器状态时间线。

```bash theme={null}
techstack api servers transitions <server-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/servers/{serverId}/transitions` |
| 更改状态 | 否 |
| MCP 工具 | `list_server_runtime_transitions` |

| 参数 | 类型 | 说明 |
| - | - | - |
| `<server-id>` | string | **必填。** 规范的服务器运行时 ID。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.