Komodo Client API Reference

Source: https://docs.rs/komodo_client/latest/komodo_client/all.html

komodo_client Rust crate v2.1.1 (1152 public items). Komodo Core server runs v2.2.0. For CLI usage and GitOps workflow, see komodo-cli-reference.md. Verified 2026-06-08: 14 endpoints tested against live Komodo v2.2.0 — all working.

Authentication & Base URL

Auth headers and base URL documented in komodo-cli-reference.md. Use Tailscale IP http://100.126.172.96:9120 — Cloudflare blocks POST requests.

---

## Execute API (`/execute/*`)

All execute endpoints return `Update` struct. Use `GetUpdate` to read full logs.

### Stack Operations

| Endpoint | CLI Alias | Description |
|----------|-----------|-------------|
| `DeployStack` | `deploy-stack` | `docker compose up` |
| `DeployStackIfChanged` | — | Only deploys if compose content changed |
| `DestroyStack` | `destroy-stack` | `docker compose down` |
| `PullStack` | — | `docker compose pull` (pull images) |
| `RestartStack` | `restart-stack` | `docker compose restart` |
| `StartStack` | `start-stack` | `docker compose start` |
| `StopStack` | `stop-stack` | `docker compose stop` |
| `PauseStack` | — | `docker compose pause` |
| `UnpauseStack` | — | `docker compose unpause` |
| `RunStackService` | `run-stack-service` | `docker compose run` (one-time command) |
| `BatchDeployStack` | — | Deploy multiple stacks matching pattern |
| `BatchDeployStackIfChanged` | — | Batch deploy if changed |
| `BatchDestroyStack` | — | Batch destroy |
| `BatchPullStack` | — | Batch pull |

### Container Operations (Server-level)

| Endpoint | CLI Alias | Description |
|----------|-----------|-------------|
| `DestroyContainer` | — | Stop & destroy container by ID/name on server |
| `RestartContainer` | — | Restart container on server |
| `StartContainer` | — | Start container |
| `StopContainer` | — | Stop container |
| `PauseContainer` | — | Pause container |
| `UnpauseContainer` | — | Unpause container |
| `RestartAllContainers` | — | Restart all on server |
| `StartAllContainers` | — | Start all |
| `StopAllContainers` | — | Stop all |
| `PauseAllContainers` | — | Pause all |
| `UnpauseAllContainers` | — | Unpause all |

### Deployment Operations

| Endpoint | Description |
|----------|-------------|
| `Deploy` | Deploy container/swarm service for Deployment |
| `DestroyDeployment` | Stop & destroy Deployment's container |
| `PullDeployment` | Pull image for Deployment |
| `RestartDeployment` | Restart Deployment's container |
| `StartDeployment` | Start Deployment |
| `StopDeployment` | Stop Deployment |
| `PauseDeployment` | Pause |
| `UnpauseDeployment` | Unpause |
| `BatchDeploy` | Deploy multiple matching pattern |
| `BatchDestroyDeployment` | Batch destroy |

### Repo Operations

| Endpoint | Description |
|----------|-------------|
| `CloneRepo` | Clone repo to server |
| `PullRepo` | Pull latest |
| `BuildRepo` | Build using attached builder |
| `ClearRepoCache` | **Admin.** Clear all repos from Core cache |
| `CancelRepoBuild` | Cancel ongoing repo build |

### Build Operations

| Endpoint | Description |
|----------|-------------|
| `RunBuild` | Run target build |
| `CancelBuild` | Cancel if building |

### Procedure / Action / Sync

| Endpoint | Description |
|----------|-------------|
| `RunProcedure` | Run procedure stages |
| `RunAction` | Run action script |
| `RunSync` | Run resource sync (commit) |
| `BatchRunAction` | Batch run actions |
| `BatchRunBuild` | Batch run builds |
| `BatchRunProcedure` | Batch run procedures |
| `BatchCloneRepo` | Batch clone repos |

### Docker Prune / Cleanup

| Endpoint | Description |
|----------|-------------|
| `PruneBuildx` | Prune buildx cache |
| `PruneContainers` | Prune stopped containers |
| `PruneDockerBuilders` | Prune builders |
| `PruneImages` | Prune unused images |
| `PruneNetworks` | Prune unused networks |
| `PruneSystem` | Full system prune (incl. volumes) |
| `PruneVolumes` | Prune unused volumes |
| `DeleteImage` | Delete specific image |
| `DeleteNetwork` | Delete specific network |
| `DeleteVolume` | Delete specific volume |

### Docker Resources

| Endpoint | Description |
|----------|-------------|
| `CreateSwarmConfig` | `docker config create` |
| `CreateSwarmSecret` | `docker secret create` |
| `RemoveSwarmConfigs` | `docker config rm` |
| `RemoveSwarmNodes` | `docker node rm` |
| `RemoveSwarmSecrets` | `docker secret rm` |
| `RemoveSwarmServices` | `docker service rm` |
| `RemoveSwarmStacks` | `docker stack rm` |
| `RotateSwarmConfig` | Rotate a swarm config |
| `RotateSwarmSecret` | Rotate a swarm secret |
| `UpdateSwarmNode` | `docker node update` |

### Admin Operations

| Endpoint | Alias | Description |
|----------|-------|-------------|
| `BackupCoreDatabase` | `backup-db` | Backup Core DB to jsonl |
| `GlobalAutoUpdate` | `auto-update` | Trigger global image update poll |
| `RotateAllServerKeys` | `rotate-keys` | Rotate all server keys |
| `RotateCoreKeys` | — | Rotate Core key + all server pubkeys |
| `SendAlert` | `alert` | Send custom alert to Alerters |
| `Sleep` | — | Sleep for specified time |
| `TestAlerter` | — | Test alerter endpoint connectivity |

---

## Read API (`/read/*`)

### Stack Queries

| Endpoint | Response | Description |
|----------|----------|-------------|
| `GetStack` | `Stack` | Get stack config + state |
| `ListStacks` | `Vec<StackListItem>` | List all stacks |
| `ListFullStacks` | `Vec<Stack>` | List with full config |
| `GetStackLog` | `Log` | Get stack service logs |
| `SearchStackLog` | `Log` | Search stack logs with filter |
| `GetStackActionState` | `StackActionState` | Get current action state |
| `ListStackServices` | `Vec<StackService>` | List services in stack |
| `GetStacksSummary` | `SummaryResponse` | Aggregate stack stats |
| `InspectStackContainer` | `Container` | Inspect specific stack container |
| `InspectStackSwarmInfo` | — | Swarm info for stack |
| `InspectStackSwarmService` | — | Inspect swarm service |
| `ListComposeProjects` | — | List compose projects on server |
| `ListCommonStackExtraArgs` | — | Common extra args for stacks |
| `ListCommonStackBuildExtraArgs` | — | Common build extra args |

### Deployment Queries

| Endpoint | Response | Description |
|----------|----------|-------------|
| `GetDeployment` | `Deployment` | Get deployment config + state |
| `ListDeployments` | `Vec<ListItem>` | List all deployments |
| `ListFullDeployments` | `Vec<Deployment>` | List with full config |
| `GetDeploymentLog` | `Log` | Deployment container logs |
| `SearchDeploymentLog` | `Log` | Search deployment logs |
| `GetDeploymentContainer` | `Container` | Get deployment's container |
| `GetDeploymentStats` | `Stats` | Deployment stats |
| `GetDeploymentActionState` | — | Current action state |
| `GetDeploymentsSummary` | — | Aggregate stats |
| `InspectDeploymentContainer` | — | Inspect container details |
| `InspectDeploymentSwarmService` | — | Inspect swarm service |

### Container / Docker Queries (Server-level)

| Endpoint | Description |
|----------|-------------|
| `ListAllDockerContainers` | All containers across all servers |
| `ListDockerContainers` | Containers on specific server |
| `GetContainerLog` | Container log output |
| `SearchContainerLog` | Search container logs |
| `GetResourceMatchingContainer` | Find resource owning a container |
| `GetDockerContainersSummary` | Summary of all containers |
| `InspectDockerContainer` | Full container inspect |
| `InspectDockerImage` | Image inspect |
| `InspectDockerNetwork` | Network inspect |
| `InspectDockerVolume` | Volume inspect |
| `ListDockerImages` | Images on server |
| `ListDockerNetworks` | Networks on server |
| `ListDockerVolumes` | Volumes on server |
| `ListDockerImageHistory` | Image history |
| `ListDockerRegistryAccounts` | Registry accounts |
| `ListDockerRegistriesFromConfig` | Registries from Komodo config |

### Server Queries

| Endpoint | Response | Description |
|----------|----------|-------------|
| `GetServer` | `Server` | Server config + state |
| `GetServerState` | `ServerState` | Live server state |
| `ListServers` | `Vec<ListItem>` | List all servers |
| `ListFullServers` | `Vec<Server>` | Full config |
| `GetServerActionState` | — | Current action state |
| `GetServersSummary` | — | Aggregate stats |
| `GetSystemInformation` | `SystemInformation` | OS, CPU, kernel info |
| `GetSystemStats` | `SystemStats` | CPU, mem, disk, network |
| `GetHistoricalServerStats` | — | Time-series stats |
| `GetPeripheryInformation` | — | Periphery agent info |

### Update / Log Queries

| Endpoint | Response | Description |
|----------|----------|-------------|
| `GetUpdate` | `Update` | Full deployment log (stages, stdout, stderr) |
| `ListUpdates` | `Vec<UpdateListItem>` | Recent updates |
| `GetVersion` | `VersionResponse` | Komodo version |
| `GetCoreInfo` | `CoreInfoResponse` | Core system info |

### Resource Queries

All resource types support: `GetX`, `ListX` (lightweight), `ListFullX` (with config), `GetXActionState`.

| Resource | Endpoints |
|----------|-----------|
| Repo | `GetRepo` / `ListRepos` / `ListFullRepos` |
| Build | `GetBuild` / `ListBuilds` / `ListFullBuilds` |
| Builder | `GetBuilder` / `ListBuilders` / `ListFullBuilders` |
| Action | `GetAction` / `ListActions` / `ListFullActions` |
| Procedure | `GetProcedure` / `ListProcedures` / `ListFullProcedures` |
| Alerter | `GetAlerter` / `ListAlerters` / `ListFullAlerters` |
| ResourceSync | `GetResourceSync` / `ListResourceSyncs` / `ListFullResourceSyncs` |
| Swarm | `GetSwarm` / `ListSwarms` / `ListFullSwarms` — see [Swarm Queries](#swarm-queries) |
| Tag | `GetTag` / `ListTags` |
| Variable | `GetVariable` / `ListVariables` |
| Alert | `GetAlert` / `ListAlerts` |
| Permission | `GetPermission` / `ListPermissions` |
| UserGroup | `GetUserGroup` / `ListUserGroups` |
| User | `FindUser` / `ListUsers` |
| Other | `ListSchedules` / `ListSecrets` / `ListTerminals` |

### Swarm Queries

| Endpoint | Description |
|----------|-------------|
| `InspectSwarm` | Full swarm inspect |
| `ListSwarmNodes` / `InspectSwarmNode` | Node management |
| `ListSwarmServices` / `InspectSwarmService` | Service management |
| `ListSwarmTasks` / `InspectSwarmTask` | Task inspection |
| `ListSwarmConfigs` / `InspectSwarmConfig` | Config management |
| `ListSwarmSecrets` / `InspectSwarmSecret` | Secret management |
| `ListSwarmStacks` / `InspectSwarmStack` | Stack management |
| `GetSwarmServiceLog` / `SearchSwarmServiceLog` | Service logs |

### TOML Export

| Endpoint | Response | Description |
|----------|----------|-------------|
| `ExportAllResourcesToToml` | `TomlResponse` | Export all resources as TOML |
| `ExportResourcesToToml` | `TomlResponse` | Export specific resources as TOML |

### Stats / Summary

| Endpoint | Description |
|----------|-------------|
| `GetBuildMonthlyStats` | Monthly build statistics |
| `GetBuildsSummary` / `GetActionsSummary` | Aggregate stats |
| `GetAlertersSummary` / `GetBuildersSummary` | Aggregate stats |
| `GetDeploymentsSummary` / `GetProceduresSummary` | Aggregate stats |
| `GetReposSummary` / `GetResourceSyncsSummary` | Aggregate stats |
| `GetServersSummary` / `GetStacksSummary` | Aggregate stats |
| `GetSwarmsSummary` | Aggregate stats |
| `GetBuildStatsDay` | Per-day build stats |
| `BuildVersionResponseItem` | Build version info |
| `ListBuildVersions` | List build versions |
| `ListSystemProcesses` | System process list |

### Git Provider / Registry

| Endpoint | Description |
|----------|-------------|
| `GetGitProviderAccount` | Get specific git provider |
| `ListGitProviderAccounts` | List git providers |
| `ListGitProvidersFromConfig` | Git providers from config |
| `GetDockerRegistryAccount` | Get specific registry |
| `ListDockerRegistryAccounts` | List registries |
| `ListDockerRegistriesFromConfig` | Registries from config |

---

## Write API (`/write/*`)

### Resource CRUD (Create / Update / Delete / Rename / Copy)

Applies to: Stack, Deployment, Server, Repo, Build, Builder, Procedure, Action, Alerter, ResourceSync, Swarm, Tag

For each resource type `X`:
- `CreateX` — Create new resource
- `UpdateX` — Update config
- `DeleteX` — Delete resource
- `RenameX` — Rename resource
- `CopyX` — Copy/duplicate resource

### Stack-specific Write

| Endpoint | Description |
|----------|-------------|
| `CreateStack` | Create new stack |
| `UpdateStack` | Update stack config |
| `DeleteStack` | Delete stack |
| `RenameStack` | Rename stack |
| `CopyStack` | Duplicate stack |
| `WriteStackFileContents` | Write compose file contents |
| `RefreshStackCache` | Refresh cached compose contents |
| `CommitSync` | Commit sync changes |
| `WriteSyncFileContents` | Write sync file contents |
| `RefreshResourceSyncPending` | Refresh pending sync changes |
| `CheckStackForUpdate` | Check if stack has image updates |
| `BatchCheckStackForUpdate` | Batch check |
| `CheckDeploymentForUpdate` | Check if deployment has image updates |
| `BatchCheckDeploymentForUpdate` | Batch check |
| `StackWebhookAction` | Stack webhook trigger |

### Variable Management

| Endpoint | Description |
|----------|-------------|
| `CreateVariable` | Create variable |
| `DeleteVariable` | Delete variable |
| `UpdateVariableValue` | Update variable value |
| `UpdateVariableDescription` | Update description |
| `UpdateVariableIsSecret` | Toggle secret flag |

### User Management

| Endpoint | Description |
|----------|-------------|
| `CreateLocalUser` | Create local user |
| `CreateServiceUser` | Create service user |
| `DeleteUser` | Delete user |
| `UpdateUserAdmin` | Set admin status |
| `UpdateUserBasePermissions` | Set base permissions |
| `CreateApiKeyForServiceUser` | Create API key for service user |
| `DeleteApiKeyForServiceUser` | Delete service user API key |
| `CreateUserGroup` / `DeleteUserGroup` | Manage user groups |
| `AddUserToUserGroup` | Add user to group |
| `RemoveUserFromUserGroup` | Remove user from group |
| `SetUsersInUserGroup` | Set all users in group |
| `SetEveryoneUserGroup` | Set everyone group |
| `RenameUserGroup` | Rename group |
| `UpdatePermissionOnTarget` | Set permission on target |
| `UpdatePermissionOnResourceType` | Set permission on resource type |
| `ListUserTargetPermissions` | List user permissions |

### Provider Accounts

| Endpoint | Description |
|----------|-------------|
| `CreateGitProviderAccount` | Add git provider |
| `UpdateGitProviderAccount` | Update git provider |
| `DeleteGitProviderAccount` | Remove git provider |
| `CreateDockerRegistryAccount` | Add registry |
| `UpdateDockerRegistryAccount` | Update registry |
| `DeleteDockerRegistryAccount` | Remove registry |

### Other Write Operations

| Endpoint | Description |
|----------|-------------|
| `UpdateResourceMeta` | Update resource metadata |
| `RotateServerKeys` | Rotate single server keys |
| `UpdateServerPublicKey` | Update server public key |
| `UpdateOnboardingKey` | Update onboarding key |
| `DeleteOnboardingKey` | Delete onboarding key |
| `CreateOnboardingKey` | Create onboarding key |
| `CreateNetwork` | Create Docker network |
| `CreateTerminal` | Create terminal session |
| `DeleteTerminal` / `DeleteAllTerminals` | Terminal management |
| `RefreshBuildCache` | Refresh build cache |
| `RefreshRepoCache` | Refresh repo cache |
| `CloseAlert` | Close an alert |
| `PushRecentlyViewed` | Track recently viewed |
| `SetLastSeenUpdate` | Mark update as seen |
| `RepoWebhookAction` | Repo webhook trigger |
| `SyncWebhookAction` | Sync webhook trigger |
| `WriteBuildFileContents` | Write build file |

---

## Key Entity Types

### Update (from `entities::update`)

```rust
struct Update {
    id: String,           // Update ID (used in GetUpdate)
    status: UpdateStatus, // Queued / Running / Complete / Failed
    logs: Vec<Log>,       // Per-stage logs
    // ... timestamps, version info
}

enum UpdateStatus {
    Queued,
    InProgress,
    Complete,
    Failed,
}

Stack Config (from entities::stack)

struct StackConfig {
    name: String,
    server_id: String,
    file_paths: Vec<String>,       // Compose file paths
    repo: Option<String>,          // Git repo
    branch: Option<String>,        // Git branch
    run_directory: Option<String>, // Working directory
    environment: Vec<EnvironmentVar>,
    // ... build, deploy, destroy commands
}

enum StackState {
    Ok,
    Failed,
    Unknown,
    // ...
}

Container (from entities::docker::container)

struct Container {
    id: String,
    name: String,
    state: ContainerState,    // Running, Exited, etc.
    image: String,
    labels: HashMap<String, String>,
    network_settings: NetworkSettings,
    // ... ports, mounts, created, etc.
}

System Stats (from entities::stats)

struct SystemStats {
    cpu_percent: f64,
    mem_total_gb: f64,
    mem_used_gb: f64,
    disks: Vec<SingleDiskUsage>,
    networks: Vec<SingleNetworkInterfaceUsage>,
    load_average: SystemLoadAverage,
}

---

Key Enums

Enum	Values	Used By
UpdateStatus	Queued, InProgress, Complete, Failed	Update
StackState	Ok, Failed, Unknown	Stack
DeploymentState	Running, Stopped, NotDeployed, Unknown	Deployment
BuildState	Ok, Building, Failed, Unknown	Build
PermissionLevel	None, Read, Execute, Write, Admin	Permissions
ResourceTarget	System, Stack, Deployment, Build, ...	All resources
Operation	Create, Update, Delete, Execute, ...	Write API
LogLevel	Trace, Debug, Info, Warn, Error	Logs
TerminationSignal	SIGTERM, SIGKILL, etc.	Deployment
RestartMode	Always, OnFailure, No	Deployment

---

KomodoClient Core Methods

impl KomodoClient {
    // Constructor
    fn new(url: &str, key: &str, secret: &str) -> Self;
    fn new_from_env() -> Self;  // Reads KOMODO_ADDRESS, KOMODO_API_KEY, KOMODO_API_SECRET

    // Generic API calls
    async fn read<T: KomodoReadRequest>(&self, request: T) -> Result<T::Response>;
    async fn write<T: KomodoWriteRequest>(&self, request: T) -> Result<T::Response>;
    async fn execute<T: KomodoExecuteRequest>(&self, request: T) -> Result<Update>;

    // WebSocket
    async fn subscribe_to_updates(&self) -> impl Stream<Item = UpdateWsMessage>;
    async fn connect_terminal(&self, query: &ConnectTerminalQuery) -> Result<TerminalWebsocket>;
    async fn connect_server_terminal(&self, ...) -> Result<TerminalWebsocket>;
    async fn connect_container_terminal(&self, ...) -> Result<TerminalWebsocket>;
    async fn connect_stack_service_terminal(&self, ...) -> Result<TerminalWebsocket>;
    async fn connect_deployment_terminal(&self, ...) -> Result<TerminalWebsocket>;

    // Utility
    async fn health_check(&self) -> Result<()>;
    async fn core_version(&self) -> Result<Version>;
    async fn poll_update_until_complete(&self, update_id: &str) -> Result<Update>;
}

---

REST API Path Convention & CLI Mapping

For curl examples and CLI ↔ endpoint mapping, see komodo-cli-reference.md.

Execute Endpoint — Two Formats

The km Python script uses POST /execute/{TypeName} (variant in path):

curl -X POST http://100.126.172.96:9120/execute/DeployStack \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \
  -d '{"stack":"<name>"}'

The km Rust CLI uses POST /execute with type wrapper:

curl -X POST http://100.126.172.96:9120/execute \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \
  -d '{"type":"DeployStack","params":{"stack":"<name>"}}'

Both map to the same DeployStack execution — the Rust client serializes the type wrapper internally.

CLI Alias Note

km x run-sync and km x commit are aliases for the same POST /execute/RunSync endpoint.

km x deploy-stack <name>  → DeployStack
km x destroy-stack <name> → DestroyStack
km x restart-stack <name> → RestartStack
km x run-sync <name>      → RunSync (alias: km x commit)
km list stacks            → ListStacks
km-logs -S <name>      → GetStackLog
km server-stats <name>    → GetSystemStats

---

Alerter Endpoints

Supported alerter types (from entities::alerter): - NtfyAlerterEndpoint — ntfy.sh - SlackAlerterEndpoint — Slack webhook - DiscordAlerterEndpoint — Discord webhook - PushoverAlerterEndpoint — Pushover - CustomAlerterEndpoint — Custom HTTP endpoint

TOML Entity Types

struct ResourcesToml {
    resource: BTreeMap<String, ResourceToml>,
    user_group: BTreeMap<String, UserGroupToml>,
    permission: BTreeMap<String, PermissionToml>,
}

Used by ExportAllResourcesToToml and ExportResourcesToToml for Komodo-as-code workflows.