Dokku Integration via SSH Bridge
Relevant source files
The following files were used as context for generating this wiki page:
The Dokku MCP server interacts with a Dokku instance not through a direct API, but by executing Dokku's command-line interface (CLI) commands over a secure SSH connection. The internal/dokku-api package serves as this crucial integration bridge, encapsulating all the logic for establishing SSH connections, authenticating, preparing and executing commands, and parsing the results. This approach allows the Go application to control a standard Dokku installation without requiring any modifications to Dokku itself.
This system is designed to be robust, with features for command validation, security blacklisting, connection management, and multiple authentication strategies. It forms the foundational infrastructure layer upon which all Dokku-specific server plugins are built.
Architecture Overview
The SSH bridge is composed of several key components that work together to execute a Dokku command. The DokkuClient is the primary entry point for other parts of the application. It delegates the complexities of SSH connection and command construction to the SSHConnectionManager, which in turn uses SSHConfig for connection parameters and SSHAuthService for authentication.
The following diagram illustrates the relationship between these components.
Core Components
The integration is handled by a set of specialized structs within the dokkuApi package.
| Component | Description | Source File |
|---|---|---|
DokkuClient | The main interface for executing Dokku commands. It handles command validation, caching, and orchestrates the execution via the SSHConnectionManager. | internal/dokku-api/client.go |
SSHConnectionManager | Manages the SSH connection, combining configuration and authentication to prepare the final ssh command arguments and environment variables. | internal/dokku-api/ssh_integration.go |
SSHConfig | A data object holding all necessary parameters for an SSH connection, such as host, user, port, and key path. It also provides the base SSH arguments. | internal/dokku-api/ssh_integration.go |
SSHAuthService | Determines the appropriate SSH authentication method (e.g., ssh-agent or a specific private key) and modifies the SSH arguments accordingly. | internal/dokku-api/ssh_auth.go |
SSHConfigBuilder | A fluent builder for programmatically creating SSHConfig and SSHConnectionManager instances, often used in tests or complex setups. | internal/dokku-api/ssh_integration.go |
Sources: internal/dokku-api/client.go, internal/dokku-api/ssh_integration.go, internal/dokku-api/ssh_auth.go
Configuration
The SSH connection can be configured through a config.yaml file or by using environment variables. The server will look for the configuration file in several locations, including /etc/dokku-mcp/, ~/.dokku-mcp/, and the local directory.
Configuration Parameters
| YAML Key | Environment Variable | Description | Default |
|---|---|---|---|
ssh.host | DOKKU_MCP_SSH_HOST | The hostname or IP address of the Dokku server. | 127.0.0.1 |
ssh.port | DOKKU_MCP_SSH_PORT | The SSH port on the Dokku server. | 22 |
ssh.user | DOKKU_MCP_SSH_USER | The SSH user for the Dokku instance. | dokku |
ssh.key_path | DOKKU_MCP_SSH_KEY_PATH | Absolute path to the SSH private key. If empty, ssh-agent is used. | "" |
timeout | DOKKU_MCP_TIMEOUT | The timeout for each SSH command execution. | 30s |
Sources: README.md:120-137, scripts/setup-dokku-local.sh:77-86, internal/dokku-api/ssh_integration.go:21-27
Local Development Setup
The make setup-dokku command and its underlying script scripts/setup-dokku-local.sh provide a complete local development environment. This script generates a dedicated SSH key pair (.ssh/dokku_mcp_test), adds the public key to the local Dokku container, and creates a config.yaml file pre-filled with the correct local connection details, including the local-only port 3022.
Sources: scripts/setup-dokku-local.sh:41-99
Command Execution Flow
When a service in a plugin needs to run a Dokku command, it calls DokkuClient.ExecuteCommand. This initiates a sequence of steps involving validation, command preparation, and execution.
This sequence diagram shows the detailed flow of executing a command like apps:list.
Base SSH Arguments
To ensure compatibility with Dokku, a set of default arguments are always included in the ssh command. The most important is -t, which forces pseudo-terminal allocation, a requirement for many Dokku commands.
The BaseSSHArgs function returns the following default arguments:
-t: Force pseudo-terminal allocation.-o LogLevel=QUIET: Suppress verbose SSH logging.-o StrictHostKeyChecking=no: Automatically accept new host keys.-p <port>: Specifies the connection port.
Sources: internal/dokku-api/ssh_integration_test.go:60-70
Authentication Strategy
The SSHAuthService automatically determines the best authentication method to use. It follows a specific priority order to find valid credentials.
This flowchart illustrates the decision-making process.
If a specific key is used (not ssh-agent), the -i /path/to/key argument is added to the SSH command.
Sources: internal/dokku-api/ssh_integration_test.go:210-226
Security
Security is a primary concern when executing shell commands. The SSH bridge implements two main layers of protection: command validation and a configurable blacklist.
Command Validation
Before any command is executed, it undergoes a strict validation process within the ValidateCommand function. This function is designed to prevent command injection attacks.
- Blacklist Check: The command is first checked against a list of blacklisted patterns.
- Dangerous Character Check: The command name and all of its arguments are scanned for a set of dangerous characters that could be used to alter or inject commands.
The following characters are considered dangerous and will cause validation to fail:
;, &, |, \``, $, (, ), {, }, <, >, \n, \r`
- Character Set Check: The command name itself is restricted to alphanumeric characters, dashes (
-), and colons (:).
Sources: internal/dokku-api/client.go:21-58, internal/dokku-api/client_blacklist_test.go:70-100
Command Blacklisting
To provide an additional layer of runtime security, the DokkuClient supports a command blacklist. This is a list of strings, and if any part of a command name contains one of these strings, the command is blocked. This is useful for disabling destructive commands in certain environments.
The blacklist can be configured via the DOKKU_MCP_SECURITY_BLACKLIST environment variable or the security.blacklist key in config.yaml.
Example configuration to block destructive commands:
"env": {
"DOKKU_MCP_SECURITY_BLACKLIST": "destroy,uninstall,remove"
}
With this configuration, any command containing "destroy" (e.g., apps:destroy), "uninstall" (e.g., plugin:uninstall), or "remove" would be blocked.
Sources: README.md:46-56, internal/dokku-api/client.go:26-31, internal/dokku-api/client_blacklist_test.go:39-57
Summary
The Dokku SSH Bridge is the foundational component that enables the MCP server to manage a Dokku instance. It provides a secure and robust mechanism for executing CLI commands remotely by encapsulating SSH configuration, authentication, and command execution logic. Its design prioritizes security through strict command validation and a configurable blacklist, while offering flexible authentication and configuration options. All higher-level features, such as application management and plugin control, are built on top of this essential integration layer.