# Service Mode REST API
## Keeper Commander Service Mode The Service Mode module for Keeper Commander enables REST API integration by providing a secure, configurable API server that can be deployed with minimal setup. This module allows users to execute Commander CLI commands through a REST API interface while maintaining security and configuration flexibility. The service can be run locally and it can optionally be integrated with Ngrok or Cloudflare tunnels for creating a routable address. ### Features #### Core Functionality * **API Server**: Flask-based REST API server for executing Commander CLI commands * **Service Management**: Complete lifecycle management for the API service * **Configuration Management**: Flexible configuration system with both interactive and streamlined setup options * **Security Controls**: Comprehensive security features including API key management, access controls, rate limiting and IP allow/deny * **API Versioning**: Two API versions supporting both synchronous (v1) and asynchronous (v2) operations * **Request Queue System**: Advanced asynchronous request processing with tracking and status monitoring * **Flexible Hosting Options**: Run on-prem, Docker container or in the cloud with integrated **Ngrok or Cloudflare tunnel** agent. #### Service Commands | Command | Description | | ---------------------- | ----------------------------------------------------------------- | | `service-create` | Initialize and configure the service with customizable settings | | `service-start` | Start the service with existing configuration | | `service-stop` | Gracefully stop the running service | | `service-status` | Display current service status | | `service-config-add` | Add new API configuration and command access settings | | `service-docker-setup` | Automated Docker service mode setup with KSM configuration | | `slack-app-setup` | Automated Slack App integration setup with Commander Service Mode | #### Security Features * API key authentication * Configurable token expiration (minutes/hours/days) * Optional AES-256 GCM encryption for API responses * TLS support with provided certificate (.pem) * Rate limiting with configurable rules * IP Allow list (whitelist) and IP Deny list (blacklist) management. * Request validation and policy enforcement * Local service config JSON or YAML file encryption using private key ### Security The Keeper Commander Service Mode feature is a self-hosted middleware that wraps an existing Commander session with a REST API. This feature is suited to environments where high speed requests and simple HTTPS-based APIs are desired. To ensure the most secure use of this feature, we recommend the following: * Use a service account dedicated to the Commander service, which is limited in scope to the necessary rights and capabilities. * Limit the scope of the Command access controls to only those commands which are required based on the use case. * Apply IP allowlist for accessing the REST API endpoint * Protect access to the machine running the Commander service * Use different API tokens for different commands and use cases ### Usage #### Basic Setup [Install Keeper Commander](https://docs.keeper.io/en/keeperpam/commander-cli/commander-installation-setup) and then login to the shell. 
keeper shell
Log in with your Keeper credentials when prompted. Since the Commander Service Mode is typically run as a service, it is recommended to use biometric login or a persistent login session. Biometric Login: ``` biometric register ``` Or create a persistent login session using the commands below: ``` this-device persistent-login on this-device register this-device timeout 30d this-device 2fa_expiration forever ``` #### Service Mode Create : Using Interactive Configuration Create and configure the service with interactive prompts: ``` service-create ``` You'll be prompted to configure: * Port number * Ngrok auth token (optional) * Cloudflare tunnel token (optional) * TLS certificate path (optional) * Request Queue system (y/n) * Security settings (optional) * Config format (yaml/json) (if not previously created) * Run mode (foreground/background) * Command access controls Example: Create Service Mode using TSL certificate (https) ``` My Vault> service-create Enter Port No:9090 Enable Ngrok Tunneling? (y/n):n Enable TLS Certificate (y/n):y Enter Certificate Path:/Users/cert/cert.pem Enter Certificate Password:/Users/cert/key.pem Enable Request Queue? (y/n):y Enable Advanced Security? (y/n):n Select Run Mode (foreground/background):foreground List of supported commands, Enter comma separated:whoami,record-add,tree,ls Select configuration format (json/yaml):yaml Generated API key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Uploading service_config.yaml ... Commander Service starting on https://localhost:9090/api/v2/ Commander Service started with PID: 35215 ``` #### Streamlined Configuration: Configure the service quickly with a single command (default is foreground mode with http) : ``` service-create -p 9090 -c 'record-add,whoami' -f json ``` Configure the service quickly with **Ngrok** (providing Ngrok auth token and Ngrok subdomain) {% code overflow="wrap" %} ``` service-create -p 9090 -c 'record-add,whoami' -ng xxxxxxxxxxx -cd mydomain ``` {% endcode %} Configure the service quickly with **Cloudflare** (providing Cloudflare auth token and domain name) {% code overflow="wrap" %} ``` service-create -p 9090 -c 'record-add,whoami' -cf xxxxxxxxxxx -cfd myname ``` {% endcode %} Configure the service with advanced options: {% code overflow="wrap" %} ``` service-create -p -f -c -rm -q -crtf -crtp -aip -dip ``` {% endcode %} **Streamline Parameters**: * `-p, --port`: Port number for the service (required to trigger streamline configuration) * `-c, --commands`: Comma-separated list of allowed commands or aliases (required) * `-ng, --ngrok`: Ngrok authentication token for cloud managed URL access (Optional) * `-cd`: Ngrok custom domain, just subdomain portion (Optional) * `-cf,--cloudflare`: Cloudflare tunnel token for cloud managed URL access (Optional) * `-cfd`: Cloudflare custom domain (Optional) * `-crtf, --certfile`: SSL certificate file path, accepts `.crt`, `.pem` or `.key` (Optional) * `-crtp, --certpassword`: SSL certificate password (Optional) * `-q, --queue_enabled`: Enable request queue system (y/n) - **Default: y** * `-rm, --run_mode`: Service run mode (foreground/background) - **Default: foreground** * `-f, --fileformat`: Configuration file format (json/yaml) - The service checks the local config file and Vault for an existing configuration format before prompting for setup. * `-rl, --ratelimit`: Rate limit per endpoint per IP (e.g., `10/minute`, `100/hour`, `1000/day`) (Optional) * `-aip, --allowedip`: IP allow list (Optional) - **Default: 0.0.0.0/0,::/0** * `-dip`: Denied IP list (Optional) * `-ek, --encryption_key`: Base64-encoded 32-byte key for AES-256 response encryption (Optional) * `-te, --token_expiration`: API key expiration time (e.g., `30m`, `24h`, `7d`) (Optional) * `-ur, --update-record `: Store the generated API key and service URL in the specified vault record - Useful to hide API Key from logs (Optional) #### Configuration File After the initial configuration, Commander will create a record in the vault with the title of "Commander Service Mode". This record will contain a YAML/JSON file called `service_config`.

Commander Service Mode record

Subsequent startups require the `service-start` command with no parameters. Configuration is loaded from the local encrypted service\_config file. {% hint style="info" %} Although the config is stored securely in Vault, the service uses a locally cached encrypted file for startup. To force a reload from Vault, delete the local config file (\~/.keeper/service\_config.json or .yaml) before running service-start. {% endhint %} #### Example: Starting from the Terminal in the Foreground The service can be started from the system terminal. For example, the below command runs the `/api/v1` in foreground mode. (Enable queue mode (-q y) for /api/v2): {% code overflow="wrap" %} ``` keeper service-create -p 8090 -f json -c 'sync-down,whoami,record-add,login-status' -rm foreground -q n ``` {% endcode %} Ctrl-C will stop the service. Once the service has been created, subsequent terminal commands can just start up the service like this: 
 keeper service-start
If [biometric login](https://docs.keeper.io/en/keeperpam/commander-installation-setup/logging-in#logging-in-with-biometric-authentication) or [persistent login](https://docs.keeper.io/en/keeperpam/commander-installation-setup/logging-in#persistent-login-sessions-stay-logged-in) mode is enabled, the service startup is seamless. #### Service Management Check service status: ``` My Vault> service-status Current status: Commander Service is Running (PID: 12345, Terminal: /dev/ttys003) ``` Add additional configuration: ``` My Vault> service-config-add List of supported commands, Enter comma separated:tree Generated API key: XXXXXXXXXXXXXXXXXXX= Uploading service_config.yaml ... Config Record with API key created successfully. ``` Start the service: ``` My Vault> service-start Commander Service starting on https://localhost:8900/api/v2/ Commander Service started with PID: 12345 ``` Stop the service: ``` My Vault> service-stop Service stopped successfully ``` *** ### Health Check Commander Service Mode provides a health check URL for checking the service status. Example with the service running on localhost port 8080: Request: ``` curl http://localhost:8080/health ``` Response: ``` {"status":"ok"} ``` ### Support For support or feature requests, please [open a Github issue](https://github.com/Keeper-Security/Commander/issues) or contact: * Email: *** ### Next Steps * [API Usage](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api/api-usage) * [Service Tunneling](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api/service-tunneling) * [Docker Deployment](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api/docker-deployment) * [Advanced Settings](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api/advanced-settings) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.