github-starred/komodo
2
0
Fork 1
mirror of https://github.com/moghtech/komodo.git synced 2026-05-07 02:16:06 -05:00
Code Issues 3.5k Packages Projects Releases 103 Wiki Activity

[PR #889] [MERGED] 2.0.0 #8022

New Issue
Closed
opened 2026-04-27 22:08:47 -05:00 by GiteaMirror · 0 comments
GiteaMirror commented 2026-04-27 22:08:47 -05:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/moghtech/komodo/pull/889
Author: @mbecker20
Created: 9/28/2025
Status: ✅ Merged
Merged: 3/24/2026
Merged by: @mbecker20

Base: main ← Head: 2.0.0

📝 Commits (10+)

📊 Changes

1078 files changed (+99299 additions, -62559 deletions)

View changed files

📝 .devcontainer/dev.compose.yaml (+9 -3)
📝 .devcontainer/devcontainer.json (+9 -3)
📝 .devcontainer/postCreate.sh (+7 -1)
➕ .github/workflows/ci.yml (+56 -0)
📝 .gitignore (+0 -4)
📝 .vscode/resolver.code-snippets (+5 -5)
📝 .vscode/tasks.json (+14 -14)
📝 Cargo.lock (+2234 -1435)
📝 Cargo.toml (+68 -69)
➕ action/build.ts (+2 -0)
➕ action/deno.json (+5 -0)
➕ action/deploy-fe.ts (+4 -0)
➕ action/deploy.ts (+2 -0)
➕ action/run.ts (+52 -0)
📝 bin/binaries.Dockerfile (+4 -4)
📝 bin/chef.binaries.Dockerfile (+4 -4)
📝 bin/cli/Cargo.toml (+9 -4)
📝 bin/cli/aio.Dockerfile (+3 -3)
📝 bin/cli/multi-arch.Dockerfile (+3 -3)
📝 bin/cli/single-arch.Dockerfile (+3 -3)

...and 80 more files

📄 Description

  • 🚨 Both Core and Periphery must be upgraded to v2 for the connection to work.
  • 🚨 Action users: komodo.execute_terminal / komodo.execute_container_exec changes -- see Terminals section below.

Changelog

I'm very excited to bring you Komodo v2. The major improvements are:

  • New UI with higher contrast and better UI primitives
  • Add Docker Swarm integration
  • Enable "reversing" the Periphery connection.
  • Easy upgrade to public key authentication.
  • Implement Server onboarding flow.
  • Improve the Terminal feature set.
  • Add passkey and totp 2fa support
  • Single user can link multiple primary logins.
  • Add full OpenAPI documentation

Periphery → Core Connection 🦎

One of the major limitations in Komodo v1 was that Core always had to establish the connection to Periphery. In many setups, this was not the optimal connection strategy, and would often require the usage of a VPN to establish the connection securely.

Now with v2, Periphery can be configured to establish an outbound connection to Core, and communication with Core will be multiplexed over this connection. #281

Existing Core → Periphery connections also continue working, and no configuration changes are required to update from Komodo v1.

Ideally Komodo Core should be served over HTTPS with certificates recognized by Periphery, however it also works for Periphery to connect to Core over ws://..., as well as insecure TLS (untrusted certificates) if you set PERIPHERY_CORE_TLS_INSECURE_SKIP_VERIFY=true.

It is usually both easier and more secure to use this Periphery → Core connection method, and there isn't much other difference or downside. The default compose configuration has changed to this method, and I recommend most users migrate their setups when convenient.

periphery.config.toml

## The address of Komodo Core. Must be reachable from this host.
## If provided, Periphery will operate in outbound mode.
## Use `ws://12.34.56.78:9120` if you don't have TLS enabled Core.
## Env: PERIPHERY_CORE_ADDRESS
## Default: None
core_address = "example.komodo.com"

## The Server this Periphery agent should connect as.
## If matching Server doesn't exist yet, see "Server Onboarding".
## Using `$(hostname)` will use the output of shell `hostname` command.
## Env: PERIPHERY_CONNECT_AS
## Default: None
connect_as = "$(hostname)"

If using a reverse proxy with Komodo Core, you can limit the IPs which can connect to the Periphery endpoint. For example with Caddy:

(reject-ips) {
	@externalIp not remote_ip 192.168.0.0/16 12.34.56.78/32
	respond @externalIp 403
}

komodo.example.com {
	handle /ws/periphery {
		import reject-ips
		reverse_proxy komodo-core:9120
	}
	handle {
		reverse_proxy komodo-core:9120
	}
}

Note. Your reverse proxy should set X-FORWARDED-HOST header to your Komodo Core domain, which caddy does by default.

Private / Public Key Authentication 🦎

The other limitation was the usage of a passkey for Core to authenticate to Periphery. This was not a secure usage pattern for 2 reasons:

  1. The passkey had to be sent over the network rather than using cryptographic methods.
  2. A single compromised Server would expose the passkey, which could be used to compromise other Servers.

While this passkey pattern remains supported for backward compatibility (only Core -> Periphery direction), users looking to move to Periphery -> Core (or increase Core -> Periphery security) can now replace their passkeys with paired private / public keys.

If you point to key files that don't exist yet, they will be generated. While the keys are openssl compatible, there is no need to manually generate keys.

core.config.toml

## Private key to use with Noise handshake to authenticate with Periphery agents.
## To load from file, use `file:/config/keys/core.key`, and mount `- keys:/config/keys`.
## If it doesn't exist yet, Core will generate a new key pair and store it for persistence.
## Env: KOMODO_PRIVATE_KEY or KOMODO_PRIVATE_KEY_FILE
private_key = "file:/config/keys/core.key"

Also add mount - keys:/config/keys to persist the generated keys files.

periphery.config.toml

## Private key to use with Noise handshake to authenticate with Periphery agents.
## To load from file, use `file:/path/to/periphery.key`.
## If it doesn't exist yet, Periphery will generate a new key pair and store it for persistence.
private_key = "file:/config/keys/periphery.key"

## Optional. Accepted Core public key to allow connection.
## To load from file, use `file:/path/to/core.pub`
## Env: PERIPHERY_CORE_PUBLIC_KEY
core_public_key = "file:/config/keys/core.pub"

The authentication is accomplished using a Noise XX handshake via the snow library.

Automatic Key Rotation 🦎

Storing the private keys in dedicated files allows for easy automatic rotation of key pairs. To rotate a Server's key, Core sends the RotatePrivateKey request to Periphery, which then generates a new key pair, and returns the public key back to Core to update the allowed public key in the Database. The new private key stays local to each Periphery agent and is never exposed to the network. Note that it only works for Servers that are currently connected, if a Server cannot be reached, the rotation will be skipped for that Server.

Similar to the "Backup Core Database" and "Global Auto Update" default system Procedures, one for key rotation will now be generated during first database initialization. Here is the TOML:

[[procedure]]
name = "Rotate Server Keys"
description = "Rotates all currently connected Server keys."
tags = ["system"]
config.schedule = "Every day at 06:00"

[[procedure.config.stage]]
name = "Stage 1"
enabled = true
executions = [
  { execution.type = "RotateAllServerKeys", execution.params = {}, enabled = true }
]

Server Onboarding 🦎

You can now make Onboarding Keys in Settings / Onboarding page. Giving one of these to Periphery allows itself to "onboard" as a new Server in Komodo. These keys are only used for this purpose, and cannot be used as the Periphery private key itself. They aren't needed if the Server already exists.

If you would like, you can make multiple onboarding keys, and depending on the key used to onboard, the created Server will inherit the configured Tags, as well as the configuration from the optional template Server.

periphery.config.toml

## Make Onboarding Keys in Server settings.
## Not needed if Server already exists.
## Env: PERIPHERY_ONBOARDING_KEY
onboarding_key = "MC4CAQAwBQYDK2VuBCIEIH1+pLGMYkT36gNj5fRWrgRenBjaTfuUVoScW1a9XG8y"
Screenshot 2025-10-05 at 3 01 34 PM

Terminals

In v1, the Terminal feature set grew slowly over the releases, and the implementations needed refinement. For example, Servers could create multiple Terminal tabs, but the Container was limited to a single Terminal. Additionally, access to Terminals was hidden behind multiple clicks -- first navigate to Server / Container, then Terminal tab, etc.

The issue stemmed from the implementation placing "Container" type Terminals as a subset of "Server" type Terminals. This is now refactored to "flatten" the implementation -- There is now a single "Terminal" type, with possible sub-types being "Server" or "Container". In other words, the different Terminal types move from a "Parent - Child" relationship to a "Sibling" relationship, making the implementations between Server and Container sub-types more straightforward and consistent.

The first thing to notice is the new dedicated "Terminals" page. This provides a birds-eye view of active Terminal sessions for easier management. This page includes all the expected "Create", "Connect", "Delete" functionality, enabling usage of this feature entirely from this page.

Screenshot 2025-10-28 at 12 50 25 PM
  • Container type terminals (so also Stack service / Deployment) now support multiple active Terminals. The UI is now identical to the Server terminals for maximum flexibility.
  • docker attach ... is now supported.
  • The Komodo CLI now supports direct ssh analog -- km ssh <SERVER>.
Screenshot 2025-10-28 at 12 53 56 PM

🚨Breaking Action change

Instead of komodo.execute_terminal and komodo.execute_container_exec, use the updated methods

await komodo.execute_server_terminal(
  {
    server: "my-server",
    terminal: "custom-name",
    command: "ls -l",
    // New. Provide session init args.
    init: {
       command: "bash",
       recreate: Types.TerminalRecreateMode.Always
    }
  },
  // Callbacks unchanged
  {
    onLine: console.log
  }
);
await komodo.execute_container_terminal(
  {
    server: "my-server",
    container: "my-container",
    terminal: "custom-name",
    command: "ls -l",
    init: {
       command: "sh",
       recreate: Types.TerminalRecreateMode.Always
    }
  },
  // Callbacks unchanged
  {
    onLine: console.log
  }
);
// Also can use komodo.execute_stack_service_terminal and komodo.execute_deployment_terminal

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/moghtech/komodo/pull/889 **Author:** [@mbecker20](https://github.com/mbecker20) **Created:** 9/28/2025 **Status:** ✅ Merged **Merged:** 3/24/2026 **Merged by:** [@mbecker20](https://github.com/mbecker20) **Base:** `main` ← **Head:** `2.0.0` --- ### 📝 Commits (10+) - [`5895fb8`](https://github.com/moghtech/komodo/commit/5895fb843e1747308341b35931229bd74adfb27b) modularize openapi structs - [`36ee7ed`](https://github.com/moghtech/komodo/commit/36ee7ed72ed767ab5015e3abcfd0d370a536ba31) most of execute openapi - [`24ed3cf`](https://github.com/moghtech/komodo/commit/24ed3cfcb1a1bb371e194b0412709fc4e7718bde) server / stack exec openapi - [`d893ae9`](https://github.com/moghtech/komodo/commit/d893ae92410baa0be15c88cb74de8a5e3502915a) most of write openapi - [`93430f6`](https://github.com/moghtech/komodo/commit/93430f6dc3a8ff0dccd823e4a76191e64a814696) more write openapi - [`9a48edc`](https://github.com/moghtech/komodo/commit/9a48edc43fb0f6f12724e36aa249c2dc5ea37388) add the write openapi definitions - [`5da48ec`](https://github.com/moghtech/komodo/commit/5da48ece821ffbfabd037a2373863a96e0bf5021) fmt and bump mogh auth - [`8758c9f`](https://github.com/moghtech/komodo/commit/8758c9ff8bd7311e0cfc5e85625e5b51a51dba8d) gen types - [`18ffe63`](https://github.com/moghtech/komodo/commit/18ffe635c858c51ca464eb9d8e68eb0731c6abe9) remove user api, mogh auth handles api keys - [`4e3ecf7`](https://github.com/moghtech/komodo/commit/4e3ecf7e6cf8c17c59fdfba0ef1f39a832c8aaf2) clean up ### 📊 Changes **1078 files changed** (+99299 additions, -62559 deletions) <details> <summary>View changed files</summary> 📝 `.devcontainer/dev.compose.yaml` (+9 -3) 📝 `.devcontainer/devcontainer.json` (+9 -3) 📝 `.devcontainer/postCreate.sh` (+7 -1) ➕ `.github/workflows/ci.yml` (+56 -0) 📝 `.gitignore` (+0 -4) 📝 `.vscode/resolver.code-snippets` (+5 -5) 📝 `.vscode/tasks.json` (+14 -14) 📝 `Cargo.lock` (+2234 -1435) 📝 `Cargo.toml` (+68 -69) ➕ `action/build.ts` (+2 -0) ➕ `action/deno.json` (+5 -0) ➕ `action/deploy-fe.ts` (+4 -0) ➕ `action/deploy.ts` (+2 -0) ➕ `action/run.ts` (+52 -0) 📝 `bin/binaries.Dockerfile` (+4 -4) 📝 `bin/chef.binaries.Dockerfile` (+4 -4) 📝 `bin/cli/Cargo.toml` (+9 -4) 📝 `bin/cli/aio.Dockerfile` (+3 -3) 📝 `bin/cli/multi-arch.Dockerfile` (+3 -3) 📝 `bin/cli/single-arch.Dockerfile` (+3 -3) _...and 80 more files_ </details> ### 📄 Description - 🚨 Both **Core** and **Periphery** must be upgraded to v2 for the connection to work. - 🚨 Action users: **`komodo.execute_terminal` / `komodo.execute_container_exec`** changes -- see **Terminals** section below. # Changelog I'm very excited to bring you Komodo v2. The major improvements are: - **New UI** with higher contrast and better UI primitives - Add **`Docker Swarm`** integration - Enable "reversing" the Periphery connection. - Easy upgrade to public key authentication. - Implement Server onboarding flow. - Improve the Terminal feature set. - Add passkey and totp 2fa support - Single user can link multiple primary logins. - Add full OpenAPI documentation ## **Periphery → Core Connection** 🦎 One of the major limitations in Komodo v1 was that Core always had to establish the connection to Periphery. In many setups, this was not the optimal connection strategy, and would often require the usage of a VPN to establish the connection securely. Now with v2, **Periphery can be configured to establish an outbound connection to Core**, and communication with Core will be multiplexed over this connection. #281 **Existing Core → Periphery connections also continue working, and no configuration changes are required to update from Komodo v1.** Ideally Komodo Core should be served over HTTPS with certificates recognized by Periphery, however it also works for Periphery to connect to Core over `ws://...`, as well as insecure TLS (untrusted certificates) if you set `PERIPHERY_CORE_TLS_INSECURE_SKIP_VERIFY=true`. **It is usually both easier and more secure to use this Periphery → Core connection method**, and there isn't much other difference or downside. The default compose configuration has changed to this method, and I recommend most users migrate their setups when convenient. ### periphery.config.toml ```toml ## The address of Komodo Core. Must be reachable from this host. ## If provided, Periphery will operate in outbound mode. ## Use `ws://12.34.56.78:9120` if you don't have TLS enabled Core. ## Env: PERIPHERY_CORE_ADDRESS ## Default: None core_address = "example.komodo.com" ## The Server this Periphery agent should connect as. ## If matching Server doesn't exist yet, see "Server Onboarding". ## Using `$(hostname)` will use the output of shell `hostname` command. ## Env: PERIPHERY_CONNECT_AS ## Default: None connect_as = "$(hostname)" ``` If using a reverse proxy with Komodo Core, you can limit the IPs which can connect to the Periphery endpoint. For example with Caddy: ```caddyfile (reject-ips) { @externalIp not remote_ip 192.168.0.0/16 12.34.56.78/32 respond @externalIp 403 } komodo.example.com { handle /ws/periphery { import reject-ips reverse_proxy komodo-core:9120 } handle { reverse_proxy komodo-core:9120 } } ``` Note. Your reverse proxy should set `X-FORWARDED-HOST` header to your Komodo Core domain, which caddy does by default. ## **Private / Public Key Authentication** 🦎 The other limitation was the usage of a `passkey` for Core to authenticate to Periphery. This was not a secure usage pattern for 2 reasons: 1. The passkey had to be sent over the network rather than using cryptographic methods. 2. A single compromised Server would expose the passkey, which could be used to compromise other Servers. While this `passkey` pattern remains supported for backward compatibility (only Core -> Periphery direction), users looking to move to Periphery -> Core (or increase Core -> Periphery security) can now replace their passkeys with paired private / public keys. If you point to key files that don't exist yet, they will be generated. While the keys are `openssl` compatible, there is no need to manually generate keys. ### core.config.toml ```toml ## Private key to use with Noise handshake to authenticate with Periphery agents. ## To load from file, use `file:/config/keys/core.key`, and mount `- keys:/config/keys`. ## If it doesn't exist yet, Core will generate a new key pair and store it for persistence. ## Env: KOMODO_PRIVATE_KEY or KOMODO_PRIVATE_KEY_FILE private_key = "file:/config/keys/core.key" ``` **Also add mount `- keys:/config/keys` to persist the generated keys files.** ### periphery.config.toml ```toml ## Private key to use with Noise handshake to authenticate with Periphery agents. ## To load from file, use `file:/path/to/periphery.key`. ## If it doesn't exist yet, Periphery will generate a new key pair and store it for persistence. private_key = "file:/config/keys/periphery.key" ## Optional. Accepted Core public key to allow connection. ## To load from file, use `file:/path/to/core.pub` ## Env: PERIPHERY_CORE_PUBLIC_KEY core_public_key = "file:/config/keys/core.pub" ``` The authentication is accomplished using a [Noise XX handshake](https://noiseprotocol.org/noise.html#interactive-handshake-patterns-fundamental) via the [snow](https://github.com/mcginty/snow) library. ## **Automatic Key Rotation** 🦎 Storing the private keys in dedicated files allows for easy automatic rotation of key pairs. To rotate a Server's key, Core sends the `RotatePrivateKey` request to Periphery, which then generates a new key pair, and returns the public key back to Core to update the allowed public key in the Database. The new private key stays local to each Periphery agent and is never exposed to the network. Note that it only works for Servers that are *currently* connected, if a Server cannot be reached, the rotation will be skipped for that Server. Similar to the "Backup Core Database" and "Global Auto Update" default system Procedures, one for key rotation will now be generated during first database initialization. Here is the TOML: ```toml [[procedure]] name = "Rotate Server Keys" description = "Rotates all currently connected Server keys." tags = ["system"] config.schedule = "Every day at 06:00" [[procedure.config.stage]] name = "Stage 1" enabled = true executions = [ { execution.type = "RotateAllServerKeys", execution.params = {}, enabled = true } ] ``` ## **Server Onboarding** 🦎 You can now make Onboarding Keys in Settings / Onboarding page. Giving one of these to Periphery allows itself to "onboard" as a new Server in Komodo. These keys are *only* used for this purpose, and cannot be used as the Periphery private key itself. They aren't needed if the Server already exists. If you would like, you can make multiple onboarding keys, and depending on the key used to onboard, the created Server will inherit the configured Tags, as well as the configuration from the optional template Server. ### periphery.config.toml ```toml ## Make Onboarding Keys in Server settings. ## Not needed if Server already exists. ## Env: PERIPHERY_ONBOARDING_KEY onboarding_key = "MC4CAQAwBQYDK2VuBCIEIH1+pLGMYkT36gNj5fRWrgRenBjaTfuUVoScW1a9XG8y" ``` <img width="1463" height="367" alt="Screenshot 2025-10-05 at 3 01 34 PM" src="https://github.com/user-attachments/assets/d675d012-46ca-453f-a91c-7ae652d83654" /> ## **Terminals** In v1, the Terminal feature set grew slowly over the releases, and the implementations needed refinement. For example, Servers could create multiple Terminal tabs, but the Container was limited to a single Terminal. Additionally, access to Terminals was hidden behind multiple clicks -- first navigate to Server / Container, then Terminal tab, etc. The issue stemmed from the implementation placing "Container" type Terminals as a _subset_ of "Server" type Terminals. This is now refactored to "flatten" the implementation -- There is now a single "Terminal" type, with possible sub-types being "Server" or "Container". In other words, the different Terminal types move from a "Parent - Child" relationship to a "Sibling" relationship, making the implementations between Server and Container sub-types more straightforward and consistent. The first thing to notice is the new dedicated "Terminals" page. This provides a birds-eye view of active Terminal sessions for easier management. This page includes all the expected "Create", "Connect", "Delete" functionality, enabling usage of this feature entirely from this page. <img width="1689" height="567" alt="Screenshot 2025-10-28 at 12 50 25 PM" src="https://github.com/user-attachments/assets/d7fdfcba-8bc7-4e54-88b9-0bd1f503d559" /> - Container type terminals (so also Stack service / Deployment) now support multiple active Terminals. The UI is now identical to the Server terminals for maximum flexibility. - `docker attach ...` is now supported. - The Komodo CLI now supports direct `ssh` analog -- `km ssh <SERVER>`. <img width="424" height="298" alt="Screenshot 2025-10-28 at 12 53 56 PM" src="https://github.com/user-attachments/assets/e6a6ba1b-b723-45ee-835b-dcc94a795519" /> ## 🚨Breaking Action change Instead of `komodo.execute_terminal` and `komodo.execute_container_exec`, use the updated methods ```ts await komodo.execute_server_terminal( { server: "my-server", terminal: "custom-name", command: "ls -l", // New. Provide session init args. init: { command: "bash", recreate: Types.TerminalRecreateMode.Always } }, // Callbacks unchanged { onLine: console.log } ); await komodo.execute_container_terminal( { server: "my-server", container: "my-container", terminal: "custom-name", command: "ls -l", init: { command: "sh", recreate: Types.TerminalRecreateMode.Always } }, // Callbacks unchanged { onLine: console.log } ); // Also can use komodo.execute_stack_service_terminal and komodo.execute_deployment_terminal ``` --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
GiteaMirror added the pull-request label 2026-04-27 22:08:47 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
1.19.0
1.19.1
1.19.2
1.19.3
1.19.4
2.0.0
bug
documentation
done
enhancement
help wanted
info
pull-request
Mirrored from GitHub Pull Request
 question
security
seen 👀
setup
thinking 🤔
ui
v2
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/komodo#8022
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?