# Changelog
Source: https://docs.monk.io/changelog-updates

Latest updates and improvements to Monk

<Update label="2026-06-12" description="v1.25.3">
  ### Features

  * **MonkScript Entity & Module Definition Support in Analyzer**: The MonkScript analyzer now understands entity type and module definitions (defines: entity / defines: module), validating definition bodies and instances of locally defined entity types with helpful did-you-mean suggestions — eliminating false 'Unknown entity type' errors on entity packages.
  * **Devin Desktop Support**: The Monk extension can now be used inside Devin Desktop.

  ### Fixes

  * Fixed Monk CLI installation and updates failing on macOS with Homebrew 5.1+ due to the 'untrusted tap' error — the Monk tap is now trusted automatically before installing.
  * Fixed Azure resources (OS disk, network interface, public IP) leaking when a cloud node is deleted while the Monk daemon dies mid-operation — these resources are now removed together with the VM.
</Update>

<Update label="2026-06-11" description="v1.25.1">
  ### Improvements

  * CI/CD setup now generates GitHub Actions workflows using Monk's published actions instead of copying build and deploy scripts into your repository, keeping your repo cleaner and ensuring you automatically receive workflow improvements

  ### Fixes

  * Fixed false "Unknown operator" warnings in MonkScript templates using recently added operators, including URL encoding/decoding (url-encode, url-decode), comparisons (gt?, gte?, lt?, lte?, equal?), hashing (sha256, sha512, sha1, md5, hmac-sha256), path helpers (self-path, full-self-path), and the error-tolerant default operator
</Update>

<Update label="2026-06-10" description="v1.25.0">
  ### Features

  * **Shared GitHub Actions for Capsule Workflows**: Capsule CI/CD setup now generates a much leaner workflow that uses the official monk-io/monk-actions suite instead of copying \~1700 lines of shell scripts into your repository. Existing scripts/ directories from previous setups can be safely deleted.
  * **URL Encode/Decode Operators in MonkScript**: New url-encode, url-decode, url-path-encode and url-path-decode operators let templates percent-encode and decode URL query and path components.
  * **Namespace Resync Command**: New `monk system ns-resync` command re-broadcasts namespace entries to repair state desync between cluster peers.
  * **Per-Cluster Service Tokens for Cost Reporting**: Clusters now report costs using a dedicated scoped service token instead of the user's access token, with a new `monk system refresh-cluster-token` command to mint or refresh it.

  ### Improvements

  * Project analysis is faster — known irrelevant directories are skipped and YAML discovery is limited to a shallow depth
  * Template start output now shows progress during readiness checks and post-start hooks, so long-running starts are no longer silent
  * Smoother sign-in flow — the login page opens automatically after email verification
  * Clearer install and upgrade messages during onboarding

  ### Fixes

  * Fixed jobs from disconnected cluster peers being orphaned forever, which left workloads stuck in a "waiting" state; peers now drain their own jobs on disconnect and remaining peers clean up jobs of departed owners
</Update>

<Update label="2026-05-22" description="v1.24.0">
  ### Features

  * **Local-only cluster**: Create a local-only cluster that can leverage cloud resources from your local machine without provisioning remote nodes.

  ### Improvements

  * Expandable install error details in the chat strip — multi-line errors from `monk.installRuntime` (e.g. outdated Xcode Command Line Tools) now show the full message instead of a single truncated line.
  * Onboarding now auto-advances after running remediation scripts even when terminal shell integration fails to attach, removing the need for a manual Retest click in many cases.
  * Faster `monk list` on large workspaces through reduced allocations on the hot path.

  ### Fixes

  * Fixed a race where a dependent job could fail to be found if its dependency completed before the consumer was registered.
  * Fixed remediation scripts that call `exit` (such as the macOS Xcode CLI Tools installer) being incorrectly reported as timed out or terminal-closed instead of completing successfully.
</Update>

<Update label="2026-05-18" description="v1.23.1">
  ### Features

  * **CLI Authentication via Environment Variable**: Authenticate the Monk CLI non-interactively by setting the MONK\_ACCESS\_TOKEN environment variable, enabling use in CI/CD pipelines and automated workflows.
  * **Billing Alert Settings**: Configure billing alert thresholds directly from the extension settings to stay informed about usage and spending.
  * **Custom VPC and Subnet Configuration on Cluster Operations**: Specify network name, subnet name, subnet CIDR, and network CIDR when creating or growing clusters, giving you full control over the network topology of provisioned infrastructure.

  ### Improvements

  * Settings panel now supports resetting custom settings back to their defaults.
  * MANIFEST files are now reliably created at the workspace root rather than nested directories.
  * Cluster creation and growth tools more reliably handle optional parameters, reducing cases where empty values were misinterpreted as intentional input.
  * Improved version update flow and restart behavior for runnables during recovery.

  ### Fixes

  * Fixed CLI token not being refreshed before running shell commands, which could cause authentication failures.
  * Fixed orphaned blob mount temporary directories not being cleaned up.
  * Fixed duplicate blobs accumulating on single-node clusters.
  * Reduced flakiness in Azure credential validation.
  * Now requires Monk daemon v3.20.5 or newer to ensure compatibility with the latest fixes.
</Update>

<Update label="2026-05-11" description="v1.23.0">
  ### Features

  * **Neon service credentials**: Add Neon as a supported service provider with API key credential handling, validation, and inline instructions.
  * **Custom VPC and subnet configuration for clusters**: Specify network name, subnet name, subnet CIDR, and network CIDR when creating AWS or Azure clusters from the confirmation form.
  * **Configurable services subnet**: Override Monk's default 10.0.0.0/16 service IP pool via a new --services-subnet daemon flag to avoid conflicts with overlapping customer networks.

  ### Improvements

  * Validate Azure disk size against the 30–4095 GB Standard\_LRS range during capsule setup so misconfigurations fail early with a clear error.
  * Updated Hetzner API integration to handle firewall limits more reliably.
  * Added a link to the partner dashboard on the website.

  ### Fixes

  * Fix MonkScript entity autocomplete failing silently on daemons that enforce authentication on all RPC calls.
  * Fix authentication failures on Windows when the Monk token lives in a WSL distro, or when the extension targets a different environment than the CLI.
  * Fix a stream form crash when cancelling after a response has already been sent.
</Update>

<Update label="2026-05-06" description="v1.22.0">
  ### Features

  * **Cloud Credential Refresh for Capsules**: Capsule secret updates can now refresh cloud provider credentials in GitHub alongside workload secrets, with automatic provider detection.

  ### Improvements

  * Container image builds are now throttled based on available client RAM to prevent system overload during parallel builds
  * Capsule setup now fails early with specific missing-field messages when cloud credentials are incomplete, instead of pushing a broken workflow to GitHub
  * Stale forms from previous editor sessions are now properly marked to avoid confusion

  ### Fixes

  * Fixed capsule CI/CD provisioning failures on GCP and AWS caused by missing zone handling; disk type and disk size are now correctly forwarded per provider
  * Improved credential validation flow so missing provider secrets are caught and requested before deployment proceeds
</Update>

<Update label="2026-05-01" description="v1.21.2">
  ### Features

  * **Hetzner Provider for Capsules**: Capsules can now be provisioned on Hetzner Cloud — the Hetzner API token is wired through to provisioning so cloud-mode setup completes successfully.
  * **Resource Quotas Configuration**: Configure max concurrency, CPU, and RAM quotas — quotas are now passed through across all supported operating systems.

  ### Improvements

  * Deployments skip the slow project rebuild step when a MANIFEST already exists, making redeploys significantly faster.
  * Faster credential handling via parallel secrets fetching, cache checks, and label deduplication.

  ### Fixes

  * Signed-out users with an outdated CLI can now complete CLI upgrades — auth prompts no longer block the installer/upgrade flow.
  * Fixed stuck loader after cancelling an event.
  * Fixed secrets propagation across workspaces and improved environment/project detection.
  * Improved reliability of the deploy templates check.
</Update>

<Update label="2026-04-28" description="v1.21.0">
  ### Features

  * **Inline Task Details in Chat**: Click any task row in chat to expand a full timeline, artifacts, and logs view inline — no need to switch to the Task Board for routine inspection.
  * **Persistent Task History**: Inline task details now survive IDE restarts, conversation switches, and webview reloads, sharing the same history as the Task Board.
  * **Dedicated WSL Install Panel**: Windows users without WSL now see a dedicated install panel with a one-click button to open the Microsoft Store, replacing the previous dead-end error.

  ### Improvements

  * Task Board now reveals only on the first task failure per job instead of opening on every new job, reducing UI noise.
  * Chat spinner is automatically suppressed when inline task events are flowing, removing duplicated progress information.
  * Failed tasks auto-expand with a full error banner, and timeline count pills hint when detail is available.
  * Improved accessibility on task UI buttons (proper button semantics, aria-expanded, aria-label, keyboard handling).
  * GitHub repository URLs in Capsules setup now accept full URLs, SSH forms, trailing slashes, and query/fragment suffixes — pasted browser URLs normalize correctly.

  ### Fixes

  * Inline task groups are now correctly attributed to the conversation they originated from, preventing cross-conversation history corruption when switching chats during a job.
  * Switching between conversations no longer wipes inline subtask timelines, logs, and artifacts from the live store.
  * Workspace Analysis subtask timeline is no longer empty after IDE restart — fixed a race where reasoning events arrived before the task's running status.
  * Stacked loader after task completion has been resolved.
  * Sound effects in forms now have proper debouncing and cover additional forms.
  * Cluster no longer disappears on remote nodes due to a sync bug.
  * Fixed log-file accumulation caused by a snapshot compaction catch-22 in the runtime store.
  * Template namespace is now validated to prevent invalid configurations.
  * Pasting a GitHub URL with a token (userinfo) is rejected and tokens are no longer echoed into extension logs.
  * Repository values containing query strings, fragments, or stray .git suffixes are properly canonicalized before being persisted.
</Update>

<Update label="2026-04-10" description="v1.20.1">
  ### Features

  * **More Approval Gates for Sensitive Operations**: Monk now prompts you before executing sensitive operations like deleting clusters, modifying infrastructure, or changing security settings. You can approve once, always allow, or cancel. Per-tool permissions are configurable in VS Code Settings.
  * **Hetzner Cloud Provider Support**: You can now deploy clusters on Hetzner Cloud. Full support for credentials, cluster creation, scaling, and region selection.
  * **Additional Build Options for Image Builds**: You can now pass additional build options when building container images, giving more control over the build process.

  ### Improvements

  * The delete cluster confirmation dialog now includes an "Always Allow" option consistent with the new approval system
</Update>

<Update label="2026-04-09" description="v1.20.0">
  ### Improvements

  * MCP tool calls now reuse the active conversation instead of creating a new one each time, preserving context across agent interactions
  * Agent interactions from MCP-connected coding tools now include context about the calling agent for better responses
  * Template browsing and inspection is now faster, using direct API calls instead of CLI shell commands
  * Naming linter now understands template inheritance — no longer warns about variable names that come from base templates

  ### Fixes

  * Fixed a race condition where concurrent MCP calls could interfere with each other
  * Fixed template paths not resolving correctly when browsing templates from custom repositories
  * Fixed operations on runnables and entities failing when using custom template repositories
  * Fixed problems with connections to clusters on local networks
</Update>

<Update label="2026-04-07" description="v1.19.0">
  ### Features

  * **Live Cost Estimation**: See estimated cloud infrastructure costs in real-time as you configure cluster creation, with hourly and monthly breakdowns including infrastructure fees
  * **Infrastructure Cost Visibility**: View running infrastructure costs per cluster in the clusters table, with usage tracking across your organization
  * **Shared Clusters**: Share clusters across multiple environments and capsules, enabling more efficient resource utilization
  * **Slack Integration for Cluster Operations**: Respond to cluster creation confirmations, deletion prompts, environment link changes, and credential requests directly from Slack — whichever channel you respond in first wins

  ### Improvements

  * GPU-related fields no longer appear in the form summary after unchecking the GPU option
  * MCP onboarding step now completes as soon as an agent connects, rather than waiting for the first tool call
  * Graceful upgrade flow when your Monk CLI is below the minimum required version — shows a targeted upgrade strip instead of the full install wizard
  * Homebrew and Xcode Command Line Tools are now auto-installed during macOS onboarding, with clear progress messages explaining each step
  * Cluster peer names now display properly in removal and shrink confirmations instead of truncated IDs
  * Daemon idle CPU usage reduced by over 50% through internal performance optimizations

  ### Fixes

  * Fixed the extension incorrectly showing an upgrade prompt instead of starting the daemon when it was simply stopped
  * Fixed cluster grow operations failing on shared clusters linked to multiple environments
  * Fixed Slack bridge disconnections crashing in-progress operations instead of falling back to the IDE prompt
  * Fixed install flow hanging with an empty terminal when shell integration encountered an error
  * Fixed the installer spawning multiple terminals during onboarding
  * Fixed Xcode CLT install exit code being masked by a cleanup command on macOS
</Update>

<Update label="2026-04-02" description="v1.18.0">
  ### Features

  * **New Onboarding Flow**: Onboarding now happens inside the chat view with compact setup panels, making it faster to get started without switching between views. New users can now start chatting with Monk immediately before signing in or installing the runtime and continue after signing up.
  * **Slack Integration**: Connect Monk to your Slack workspace so you can respond to deployment questions, approve file changes, and fill out forms directly from Slack when you're away from the IDE. Setup is OAuth-based — just authorize in Slack and pick a channel.
  * **Slack Alerts for Watcher**: Watcher can now send alerts to Slack via an automated OAuth setup flow, replacing the previous manual webhook URL configuration.
  * **System Sleep Prevention**: Monk now prevents your machine from sleeping during long-running operations like deployments and cluster creation, ensuring they complete reliably even if you step away.
  * **Workload-Scoped Secrets and Repos**: Workloads can now be created and managed against non-local repos with scoped secret access, enabling more flexible multi-repo and multi-environment deployment setups.

  ### Improvements

  * On Windows, the UNC host restart requirement no longer blocks the entire onboarding flow — installation continues while a non-blocking reminder to restart is shown.
  * The Windows and Linux install flow now correctly picks up all required steps in a single run instead of requiring multiple attempts.
  * Cluster status updates are faster and more reliable, with reduced timeouts and fewer stale state issues after switching or deleting clusters.
  * Improved KMS validation error messages for AWS credentials.
  * The dashboard now shows a Slack card with connection status and quick actions to change channel or disconnect.
  * Better error messages when cluster dependencies fail to resolve with custom repository templates.

  ### Fixes

  * Fixed cluster disconnect, consensus recovery, and container cleanup issues that could leave clusters in a broken state.
  * Fixed missing secret scope for file-based and mounted secrets in deployments.
  * Fixed Azure container fallback behavior.
  * Replaced deprecated apt-key with modern signed-by approach for Linux and WSL installations, eliminating deprecation warnings on newer Ubuntu/Debian.
</Update>

<Update label="2026-03-24" description="v1.17.0">
  ### Improvements

  * Clearer error messages during authentication — timeout and state mismatch errors now surface specific, actionable descriptions instead of generic failures
  * Transient setup and self-test failures are now automatically retried with backoff, reducing flaky first-launch errors

  ### Fixes

  * Fixed node cleanup and load balancer deletion when destroying a cluster
  * Fixed a bug where multiple IDE windows could interfere with each other's session state
</Update>

<Update label="2026-03-20" description="v1.16.1">
  ### Features

  * **Workspace, Project, and Capsule Scheduling Tools**: New MCP tools for managing workspaces, projects, and organizations, plus capsule scheduling configuration directly from your editor.

  ### Improvements

  * Default tool timeout increased to 30 minutes so long-running MCP tools are no longer prematurely killed.
  * Upgraded default AI model to GPT-5.4 for improved agent responses.

  ### Fixes

  * File picker now renders correctly for credentials that require both a file upload and form fields.
  * Environment picker correctly handles personal environments and no longer hides default-project environments.
  * Capsule user sync now preserves cluster owners instead of accidentally removing them.
  * Cluster teardown is more robust and no longer fails on edge cases during exit.
  * Fixed a race condition that could occur when switching between clusters or contexts.
</Update>

<Update label="2026-03-12" description="v1.16.0">
  ### Features

  * **Capsule Scheduling Settings**: Configure scheduling options for your capsules directly from the extension, giving you finer control over when and how workloads run.
  * **Task Progress Summaries in Chat**: See live task and job progress inline in the chat view — including job state, elapsed time, and individual task status — without needing to switch to the task board.

  ### Improvements

  * Chat history is now more reliable: deleted conversations no longer reappear after reload, and concurrent updates no longer cause data races.
  * The stop button in the chat input is now red to clearly indicate it will cancel the current operation.
  * Status strip tooltips are more stable and no longer cause render crashes on hover.
  * Archived job snapshots are preserved so you can review historical task progress in chat after a job completes.
  * Task elapsed time displays are now accurate for completed and archived jobs.

  ### Fixes

  * Fixed a memory leak in the task scheduler that could cause increasing CPU and memory usage during long-running jobs.
  * Fixed workload group counts incorrectly inflating the status strip numbers.
  * Fixed subtitle in task groups sometimes appearing stale or hidden when content changed.
</Update>

<Update label="2026-03-10" description="v1.15.0">
  ### Features

  * **Capsule Service Token Security Redesign**: Capsule CI/CD pipelines now use a single project-scoped master token that mints short-lived JIT tokens at runtime, replacing the previous two-token authentication model. This improves security by limiting credential scope and lifetime for provision, deploy, and cleanup operations.
  * **Capsule UI**: New user interface for managing Capsules directly from the extension, providing visibility and control over capsule lifecycle and configuration.
  * **Workspace MCP Auto-Discovery**: MCP server configurations are now automatically generated and cleaned up for popular coding agents (Cursor, Claude, Gemini, Codex, CLI/IDE) so they can discover and connect to the Monk MCP server with minimal manual setup.
  * **Update Capsule Secrets Tool**: New agent tool for updating workload secrets on existing Capsules in two modes: global (pushes to GitHub environment and patches the workflow) or local (injects directly into the connected capsule via CLI).

  ### Improvements

  * GitHub repository name is now auto-detected and pre-filled when requesting GitHub credentials for Capsule setup
  * Capsule CI/CD scripts poll for daemon readiness instead of using a fixed 20-second sleep, improving reliability and reducing setup time
  * CI/CD scripts are now universal and provider-agnostic, supporting all four cloud providers at runtime via environment variables instead of compile-time interpolation
  * Non-secret Capsule parameters (service URLs, org/project slugs, cloud settings) are stored as GitHub environment variables instead of secrets, improving auditability
  * Custom disk sizes configured in the extension are now correctly passed through to cluster provisioning
  * Ingress controllers and container registries are now treated as ambient platform services, preventing the agent from unnecessarily planning or deploying them during app deployments
  * Role operations in chat now show an approval form for confirmation before executing

  ### Fixes

  * Fixed JIT token minting failures being silently swallowed in CI/CD fetch-metadata step due to set -e behavior
  * Fixed JIT token error messages being captured into variables instead of appearing in CI logs by redirecting to stderr
  * Fixed connection leak in local capsule secret updates where MonkClient connections were not closed on error
  * Fixed redundant GitHub API calls when creating multiple environment variables by resolving repository ID once
  * Fixed MCP server rejecting undisclosed tool calls and properly cleaning up multi-key config sections
  * Fixed MCP discovery continuing gracefully when legacy config cleanup fails due to permissions or unreadable files
  * Fixed cluster user sync to trigger on environment link/unlink and when applying RBAC roles
  * Fixed ingress collision validation to prevent route conflicts during deployments
</Update>

<Update label="2026-02-28" description="v1.14.0">
  ### Features

  * **Monk Capsules Setup Tool**: Added guided setup for per-branch CI/CD environments, including workflow/script generation and scoped secret provisioning
  * **Local MCP Server**: Your coding agent now can talk to monk through a built-in Streamable HTTP JSON-RPC server with progress streaming and multi-window support
  * **RBAC UX Expansion**: Added role/permission-focused forms and updated UI behavior to reflect scoped permissions
  * **Monk Networking Additions**: Added Azure DNS forwarding support for private-link/database zones and custom public IP/domain handling

  ### Improvements

  * Improved project diagnostics and project-files UI with richer file-state tooltips, per-file problem counts, and quick open/delete actions
  * Simplified agent architecture by removing dynamic agents and routing labels, reducing runtime complexity and improving stability
  * Improved tooltip behavior and placement to reduce flicker/clipping and improve keyboard accessibility

  ### Fixes

  * Fixed status false-positives by removing group-level ready/alive health signals and avoiding duplicate Docker path checks
</Update>

<Update label="2026-02-18" description="v1.13.0">
  ### Features

  * **Projects Support**: Added project-level workflows

  ### Improvements

  * Better WSL onboarding flow with automatic install in setup wizard and guided install option in dashboard mode

  ### Fixes

  * Fixed task board card overflow for long pre-formatted output so horizontal scrolling behaves correctly
</Update>

<Update label="2026-02-13" description="v1.12.0">
  ### Features

  * **Structured GPU Cluster Configuration**: Cluster create/grow now supports explicit GPU enablement, count, and instance type with backend-validated options
  * **RBAC Foundations**: Introduced role-based access control support across extension and backend flows
  * **Scoped Rules & Instructions**: Added org- and environment-scoped custom instructions for more targeted agent behavior

  ### Improvements

  * Guided cluster creation now provides dynamic region/zone/instance updates, better defaults, and stronger inline validation/advisories
  * Clearer "waiting for input" indication in chat and task views when tasks pause for user action
  * Form handling is more resilient with serialized question handlers, debounced field updates, and safer dependency refresh logic
  * Task lifecycle handling tightened to track cancelled/waiting flows more accurately across different actions

  ### Fixes

  * Fixed cancelled tasks losing job association or showing stale/duplicate entries in the task board
  * Fixed cancellation/error paths that could leave tasks stuck in `executing`
  * Fixed environment tag preservation during interactive cluster parameter changes
  * Monk runtime fixes for broken-cluster peer status updates and region-based pricing lookup
</Update>

<Update label="2026-02-09" description="v1.11.0">
  ### Features

  * **Quick Analysis Mode**: Lightweight analysis path wired end-to-end (Frontman tool + orchestrator support)
  * **Guided Region/Zone Selection**: Cluster creation form now updates and validates region/zone dynamically

  ### Improvements

  * Unified "waiting for input" UX across chat, task board, and interactive prompts during deploy/watcher flows
  * More robust form interactions
  * Clearer explanations of actions from the agent and improved chat rendering/loading indicators
  * Monk runtime reliability: better handling of broken cluster peer status and registry pull fallback

  ### Fixes

  * Prevent tasks from getting stuck waiting when form rendering fails or interrupts
</Update>

<Update label="2026-02-02" description="v1.10.2">
  ### Improvements

  * Code Editor agent now scans Elixir source files and respects `.dockerignore`

  ### Fixes

  * More robust directory traversal and error handling when listing workspace files
  * Made task board horizontal scrollbar visible at all times
  * Fixed occasional duplicate entries in workload status output
</Update>

<Update label="2026-01-29" description="v1.10.0">
  ### Improvements

  * Safer cluster creation and deploy flows with clearer prompts, defaults, and progress reporting
  * Stronger destructive delete confirmations and clearer conversation UI for high-risk actions
  * Credential prompts now link provider docs inline with clearer instructions
  * Watcher now ignores local peer updates to prevent misleading assessments
  * Improved Watcher setup form

  ### Fixes

  * Prevents secret-injection failures from emitting misleading messages
  * Fixes custom-select behavior and delete confirmation state in the UI
  * Fixes to the code editor approval flow
</Update>

<Update label="2026-01-28" description="v1.9.2">
  ### Fixes

  * Stabilized manifest blob cleanup with retries and better logging
  * Skipped deletes for missing blobs to reduce noisy failures
  * Improved installation guidance for macOS by detecting missing Xcode Command Line Tools

  ### Features

  * Made bug reporting more discoverable in the welcome UI and setup wizard
</Update>

<Update label="2026-01-26" description="v1.9.1">
  ### Improvements

  * Ignored readiness reporting for group workloads to avoid misleading assessments
</Update>

<Update label="2026-01-22" description="v1.9.0">
  ### Features

  * **Audit Trail**: Added audit implementation with a refreshed audit view
  * **Fix with Monk**: Deep links from Watcher alerts open the IDE, fetch context, and start fixing the issue

  ### Fixes

  * Fixed removal handling for environment-scoped secrets
</Update>

<Update label="2026-01-19" description="v1.8.1">
  ### Improvements

  * Enhanced workload status UI with richer health metadata, grouping, and navigation to definitions
  * Hardended cluster provisioning cleanup and improved cluster switch error guidance
</Update>

<Update label="2026-01-16" description="v1.8.0">
  ### Features

  * **Team Secret Sharing**: Teams can now share secrets across members

  ### Improvements

  * Added crashloop detection and restart metadata to deployment assessments for better stability diagnostics
</Update>

<Update label="2026-01-15" description="v1.7.7">
  ### Features

  * **Automated Deployment Assessment**: Post-deploy health checks now summarize workload status and logs
</Update>

<Update label="2026-01-14" description="v1.7.6">
  ### Features

  * **Integration Library**: Monk can now browse, suggest and install available integrations on demand

  ### Improvements

  * Enhanced internal probe operators for better diagnostics
  * Secrets handler enabled for peer-to-peer secret sharing
</Update>

<Update label="2026-01-12" description="v1.7.5">
  ### Improvements

  * PowerShell is now explicitly used for Windows terminal sessions for better compatibility
  * Enhanced ArrowScript syntax clarity and documentation
  * Improved crashloop detection in running workloads
  * Added secrets scope parameter for finer-grained access control

  ### Fixes

  * Fixed task board showing duplicate entries
  * Fixed task board persistence issues across sessions
  * Fixed URL concatenation issues in certain scenarios
</Update>

<Update label="2026-01-08" description="v1.7.4">
  ### Improvements

  * Better error messages when building container images
  * Fast-fail improvements for quicker error detection
  * Reduced memory allocation in critical paths
</Update>

<Update label="2026-01-07" description="v1.7.3">
  ### Fixes

  * Fixed LLM error event handling in agents
</Update>

<Update label="2026-01-05" description="v1.7.2">
  ### Features

  * **Configurable Editor Approval**: New settings to control when file approvals are required, with "don't ask again" option per session

  ### Improvements

  * Increased job timeout to 1 hour for long-running operations

  ### Fixes

  * Fixed "don't ask again" checkbox updating wrong setting
  * Fixed Protocol response type handling for method names containing "request"
  * Fixed code editor deny patterns preventing legitimate edits
</Update>

<Update label="2026-01-04" description="v1.7.1">
  ### Improvements

  * Refactored diff viewer component for improved styling consistency

  ### Fixes

  * Fixed approval flow hanging in certain scenarios
</Update>

<Update label="2026-01-03" description="v1.7.0">
  ### Improvements

  * Faster agent decision-making with optimized reasoning settings
  * Increased tasks concurrency for better parallelism in job execution
  * Shared cache for Monk metadata improves diagnostics performance
  * Better error tracking and for edit operations

  ### Fixes

  * Fixed code editor incorrectly denying legitimate source files (.ts, .go, etc.)
  * Fixed ArrowScript `replace` operator reporting false stack underflow errors
  * Fixed documents being skipped during rapid file opens
  * Fixed memory leak during re-analysis
  * Fixed race condition in timer scheduling
</Update>

<Update label="2025-12-25" description="v1.6.0">
  ### Major Features

  * **File Approval Flow**: Agents now request explicit review and approval before modifying source files, with an interactive diff viewer in chat
  * **Native Diff Editor**: Open full diff comparisons in VS Code's native diff editor directly from the approval UI

  ### Improvements

  * Improved reliability of interactive prompts and form handling
  * Better URI handling for diff content with special characters
  * Updated minimum Monk requirement to 3.18.7
</Update>

<Update label="2025-12-24" description="v1.5.3">
  ### Improvements

  * Relaxed member permissions for cluster synchronization
</Update>

<Update label="2025-12-23" description="v1.5.2">
  ### Fixes

  * Fixed duplicate diagnostics appearing in git diff views
  * Fixed image validation when using `image` + `image-tag` format
  * Fixed stale warnings persisting after template updates
  * Fixed image tag matching to require exact versions when explicitly specified
  * Fixed search result counts for workspace files
  * Cluster and user management fixes

  ### Improvements

  * Faster and more reliable diagnostics after edits
  * Added validation for environment variables and entrypoints
</Update>

<Update label="2025-12-19" description="v1.5.1">
  ### Improvements

  * Detection of circular service dependencies (wait-for cycles)
  * Service health checks now run on the correct cluster node
  * Agent provides guidance for accessing services via ingress routes
  * Improved ArrowScript error messages
  * Better validation suggestions for HTTP services and ingress routes
</Update>

<Update label="2025-12-19" description="v1.5.0">
  ### Major Features

  * **Source Code Editor Agent *Beta***: New agent for targeted source-code fixes (env vars, ports, connection strings, Dockerfile and build scripts) to help fix deployment-related issues
  * **Multiple Environments**: Support for multiple deployment environments, allowing separate staging/production configurations per cluster

  ### Fixes

  * Fixed file existence handling on revert operations
  * Fixed nested MANIFEST files being handled by wrong editor agent
</Update>

<Update label="2025-12-15" description="v1.4.0">
  ### Improvements

  * **Clearer task progress & diagnostics**: More detailed timeline events and better context around what the agent is doing (and why), making it easier to follow long-running jobs.
  * **Smoother, safer credential setup**: Credential requests are now more structured and validated, reducing redundant prompts and helping prevent accidental overwrites during updates.
  * **More polished prompts & forms**: Refreshed UI for confirmations and credential entry with clearer styling, improved summaries, and accessibility/interaction tweaks.
  * **More reliable builds**: Next‑gen container builder improves build/run flow, observability, and cleanup so failures are easier to understand and recover from.
  * **More consistent agent reporting**: Backend emits more structured artifacts and clearer diagnostics, including improved path handling and validation messages.
</Update>

<Update label="2025-12-12" description="v1.3.1">
  ### Improvements

  * Cluster-switch tools now available to the agent for switching between clusters

  ### Fixes

  * Fixed credential input parsing: prevents empty values from overwriting existing OAuth or file-based credentials
</Update>

<Update label="2025-12-11" description="v1.3.0">
  ### Major Features

  * **Production Watcher**: Watcher setup tool is now out of Beta and production-ready with monitoring for CPU, memory, disk usage, and service health with Slack integration

  ### Improvements

  * Smarter secret coverage detection: required secrets are now marked as stored when covered by provider credentials
  * Better status display showing stored provider credentials
  * "Generate" button for secure value generation in credential forms
  * Linter: Fixed stale symbol-kind issues during inheritance reanalysis
  * Linter: Prefer `image: "name:tag"` format over deprecated `image-tag` property (shown as hints)
  * Linter: Well-known public Docker Hub images (nginx, postgres, redis, mongo, etc.) no longer require declaration in MANIFEST
  * Linter: Global variable support with deprecation warnings to guide users toward replacements
</Update>

<Update label="2025-12-10" description="v1.2.1">
  ### Improvements

  * Internal refactoring for improved manifest parsing and Dockerfile path handling
</Update>

<Update label="2025-12-10" description="v1.2.0">
  ### Major Features

  * **Go to Definition**: Navigate directly to template definitions, services, containers, and variables across your project
  * **Smart Code Navigation**: Jump to embedded code blocks and external dependencies from template files

  ### Improvements

  * Enhanced template validation with better detection of unused variables
  * Smarter schema validation with suggestions for typos and allowed values
  * Improved secret detection in configuration files
  * Warnings when connections are missing a service specifier
  * Better syntax highlighting for ArrowScript

  ### Fixes

  * Fixed file searching accuracy for paths with special characters
  * Fixed Dockerfile path resolution in IMAGE statements
  * Fixed file path handling across different operating systems
</Update>

<Update label="2025-12-09" description="v1.1.2">
  ### Improvements

  * Enhanced credential form with better support for multiple providers
  * Improved validation feedback with gentler hints for non-critical issues
</Update>

<Update label="2025-12-09" description="v1.1.1">
  ### Improvements

  * **Enhanced Credentials Form**: Improved credential input with sectioned forms for multiple providers
  * Registry credentials now use cluster secrets for improved security
  * Enhanced template validation with smarter name suggestions
  * Better variable type handling and diagnostics in template files
  * Better code extraction accuracy for health checks and replicas configuration

  ### Fixes

  * Fixed position mapping for indented code blocks in template diagnostics
</Update>

<Update label="2025-12-08" description="v1.1.0">
  ### Improvements

  * Improved search functionality with result limits for better performance
  * Enhanced task management with new "interrupted" state for better visibility after connection issues
  * Improved job state recovery after IDE restarts
  * Better ArrowScript diagnostics with clearer error messages
</Update>

<Update label="2025-12-07" description="v1.0.1">
  ### Features

  * **Secure Credentials Form**: New dedicated form for entering sensitive credentials securely instead of pasting them in chat

  ### Improvements

  * Better documentation and guidelines for MANIFEST files and secret handling
</Update>

<Update label="2025-12-06" description="v1.0.0" />

<Update label="2025-12-05" description="v0.17.1">
  ### Improvements

  * Switched to new LLM for speed, accuracy and more succint answers
  * Improved action links in chat for interactive buttons and file references
  * Better status strip displaying workload statuses with improved tooltips
  * Optimized status comparison logic
</Update>

<Update label="2025-12-02" description="v0.17.0">
  ### Features

  * **HTTP Probe**: New probe to test containerized web applications
  * **Port Service**: Find available ports on the client machine for local development
  * Force reanalyze option in build tool

  ### Improvements

  * Improved chat context with current status awareness
  * Better job completion warnings when not all tasks were completed
  * Updated agent instructions for improved guidance
</Update>

<Update label="2025-11-30" description="v0.16.2">
  ### Improvements

  * Enhanced Monk UI with improved button contrast for better accessibility
  * Dynamic sample prompts in welcome screen and chat interface
  * Improved agent status reporting and context awareness
  * Better markdown rendering in chat interface

  ### Fixes

  * Fixed authentication and onboarding flow to prevent state mismatches
  * Fixed authentication callback handling after user cancellation
  * Fixed email verification flag sent to webview immediately after verification
  * Fixed welcome screen login state to use proper auth status
  * Fixed memory leak by clearing timeout in ReadyCard component
</Update>

<Update label="2025-11-29" description="v0.16.1">
  ### Features

  * **Interactive Forms**: New form system for structured user input within chat interface
  * Forms support for collecting configuration data and credentials
  * Question prompts on individual form sections for better guidance

  ### Improvements

  * Better fallback mechanisms for environments without full chat support
  * Force package manager re-test after distro selection on Linux

  ### Fixes

  * Fixed connection race conditions
  * Fixed connect handshake timeout issues
  * Removed max reconnect attempts, capped backoff at 6 seconds for better stability
  * Fixed status color implementation
</Update>

<Update label="2025-11-25" description="v0.15.3">
  ### Features

  * **Organization Management**: New organization view with cluster synchronization
  * **Cluster Management**: Enhanced cluster and organization management tools
  * Configuration variables cleanup option
  * Wizard waiting state for better user feedback

  ### Improvements

  * Enhanced welcome screen UI and UX
  * Improved status aggregator and chat webview integration
  * Better code readability and structure in webview components
  * Updated billing to use unified website URL
  * Improved WSL distro handling

  ### Fixes

  * Fixed subscription token calculation in MetricsRow component
  * Fixed missing button for organization management
  * Fixed borders and refresh buttons in management interfaces
  * Fixed double cancel buttons in cluster modals
  * Added DNF support to Linux remediation script
</Update>

<Update label="2025-11-23" description="v0.15.2">
  ### Improvements

  * Automatic self-test after successful authentication for better user experience
  * Ensures application state is up-to-date when user starts working
</Update>

<Update label="2025-11-20" description="v0.15.1">
  ### Improvements

  * Enhanced authentication user experience
  * Better status change signal emissions
  * Enhanced team management with refresh status on accept and refresh button
  * Improved plan label display with uppercase and extra token information
  * Added tag parameter to watcher tool

  ### Fixes

  * Fixed monkd TCP port (changed to 2137)
  * Fixed shell execution environment mutation bug
  * Fixed Unix socket permission issues by switching to TCP socket
  * Added systemd override check and migration support
</Update>

<Update label="2025-11-10" description="v0.15.0">
  ### Features

  * **Watcher Setup Tool**: New tool for setting up monitoring with Slack integration
  * **Local Deployment**: Added 'local' deployment mode for running projects on local machines
  * **Organization View**: Initial organization and cluster synchronization support

  ### Improvements

  * Skip managed service configuration for local development scenarios
  * Better credential flow for Slack webhooks
  * Enhanced watcher template embedding and reloading
</Update>

<Update label="2025-11-04" description="v0.14.17">
  ### Fixes

  * Fixed Windows selftest retest logic to prevent script sequence issues when shell integration is unavailable
</Update>

<Update label="2025-11-03" description="v0.14.16">
  ### Fixes

  * Fixed release pipeline
</Update>

<Update label="2025-10-30" description="v0.14.15">
  ### Improvements

  * Liveness/readiness: automatic checks and readiness status/errors
  * Performance: stats caching for container CPU metrics
  * TLS & ingress:
  * TLS configuration support in ingress and config files
  * Support for additional node TLS certificates in ingress
  * KMS:
  * Improved key lifecycle and permission checks
  * Switched Azure AD Graph to Microsoft Graph for Azure KMS

  ### Fixes

  * Fixed repository connection issues on macOS
  * Fixed error loops and wait-for-vault provisioning before key creation
  * Fixed panic in user list race condition
  * Fixed handling to ignore empty env values in variables
</Update>

<Update label="2025-10-29" description="v0.14.14">
  ### Features

  * Added Terms of Service, Privacy Policy, and License links to the onboarding wizard
</Update>

<Update label="2025-10-28" description="v0.14.13">
  ### Fixes

  * Fixed login flow
</Update>

<Update label="2025-10-28" description="v0.14.12">
  ### Features

  * Experimental billing support for organizations

  ### Fixes

  * General stability and bug fixes
</Update>

<Update label="2025-10-21" description="v0.14.11">
  ### Improvements

  * Automated liveness/readiness checks for services
  * Stats caching for container CPU metrics
  * Ingress TLS certificate configuration enhancements
</Update>

<Update label="2025-10-10" description="v0.14.10">
  ### Improvements

  * Performance: exclude build artifacts and temporary directories from indexing for faster, cleaner search
  * Consistency: normalized ignored path handling across workspaces
  * Billing & subscriptions:
  * Hide trial when user already has an active subscription
</Update>

<Update label="2025-10-07" description="v0.14.9">
  ### Improvements

  * Subscription & billing polish:
  * Better subscription status handling and trial visibility
  * Fixed links and labels for external billing pages
</Update>

<Update label="2025-10-02" description="v0.14.8">
  ### Improvements

  * Updated README with comprehensive feature descriptions and clearer value proposition
  * Better documentation of Monk's autonomous capabilities and integrations
</Update>

<Update label="2025-09-30" description="v0.14.7">
  ### UI Improvements

  * Made status bar icons larger for better visibility
  * Fixed cluster switching to prevent accidental resource removal
</Update>

<Update label="2025-09-26" description="v0.14.4">
  ### Major Features

  * **Cluster Switching**: You can now easily switch between multiple clusters using the status bar or command palette. Your cluster credentials and selections are saved across workspaces.

  ### Improvements

  * Improved billing transparency with centralized usage tracking
  * Added real-time status updates in the chat interface
  * Better status reporting showing current cluster, workloads, and secrets
</Update>

<Update label="2025-09-19" description="v0.14.3">
  ### Improvements

  * Log retrieval now has better defaults and won't hang indefinitely
  * Fixed chat reloading - no more duplicate messages after refreshing with Ctrl/Cmd+R
  * Chat conversations now restore properly when reopening
  * Fixed issue where new chat messages could appear in the wrong conversation
</Update>

<Update label="2025-09-11" description="v0.14.2">
  ### Major Features

  * **Unread Notifications**: Background conversations now show a green dot when complete, so you know when responses are ready
  * **Multiple Concurrent Chats**: You can now run multiple conversations simultaneously without interference

  ### Improvements

  * Better handling of streaming messages across multiple conversations
  * Improved chat history management
</Update>

<Update label="2025-09-09" description="v0.14.1">
  ### Major Features

  * **GPT-5 Integration**: Monk now uses Azure GPT-5 models for better performance and accuracy
  * **AWS SQS Support**: You can now work with AWS SQS queues
  * **Custom Domains**: Set custom domains for Netlify and Vercel deployments
  * **Enhanced Documentation Access**: Monk can now search and retrieve documentation to better answer your questions
  * **Improved Template Editing**: Better YAML editing with automatic validation and error fixing
  * **Better Project Analysis**: Improved understanding of Docker images, Dockerfiles, and build contexts in your project

  ### Features

  * New command to copy registry credentials from workspace to global scope
  * Better credential management with workspace and global scopes
  * Registry credentials created during cluster setup are now saved globally for reuse

  ### Improvements

  * Fixed credential deletion to work correctly across different scopes
  * Better validation of configuration files with helpful suggestions
  * Improved workspace analysis for more reliable builds

  ### New Agent Capabilities

  * Monk can create or adopt SQS queues (standard or FIFO), set encryption, redrive and dead-letter policies, and return queue URLs and ARNs
  * Monk can send and receive SQS messages, purge queues, and report queue statistics
  * Monk can edit Monk YAML templates and iterate until all diagnostics are resolved to zero
  * Monk can answer documentation questions about Monk concepts, CLI, and templates with enhanced semantic search
</Update>

<Update label="2025-09-06" description="v0.13.2">
  ### Features

  * **Social Login**: Sign in quickly with GitHub or Google
  * **Improved Onboarding**: Better first-run experience with provider-first authentication
  * Simplified authentication - you can now sign up directly via email
  * More streamlined login/signup process

  ### Improvements

  * Fixed issues with task history loading
  * Better handling of authentication errors with clearer guidance
</Update>

<Update label="2025-09-03" description="v0.13.0">
  ### Features

  * **Task Board Access**: New button in chat to quickly open the Task Board
  * **Task History Persistence**: Task board now remembers your jobs and tasks across sessions
  * **Archive Management**: Clear archived tasks with a new clear button

  ### Improvements

  * Better task timing displays showing local timestamps
  * Task board continues collecting events even when closed
  * Improved handling of workload deletion with options for volumes, backups, and images
  * Fixed task board data corruption issues
</Update>

<Update label="2025-08-31" description="v0.12.7">
  ### Improvements

  * More readable job names in the Task Board
  * Task board now groups archived jobs for better organization
  * Fixed issues with task board timing and display
</Update>

<Update label="2025-08-25" description="v0.12.4">
  ### Major Features

  * **Managed Services**: You can now use managed databases from DigitalOcean and S3/Spaces storage for Redis, MongoDB, Postgres, and MinIO

  ### Improvements

  * Better session management - active sessions won't timeout while you're working
  * Fixed task status display to correctly show errors instead of false successes
  * Improved GPU support for DigitalOcean deployments

  ### New Agent Capabilities

  * Monk can create DigitalOcean managed database clusters (Postgres/MySQL/Redis/MongoDB/Kafka/OpenSearch), resize clusters, list databases, create and delete databases, and provide connection strings and credentials
  * Monk can create DigitalOcean Spaces (S3-compatible), configure versioning, CORS, lifecycle, and tagging, and provide regional endpoints and URLs
  * Monk can create and delete DigitalOcean Spaces access keys and store them in secrets for programmatic access
  * Monk can configure existing components to use managed services instead of self-hosted alternatives
</Update>

<Update label="2025-08-22" description="v0.12.3">
  ### Major Improvements

  * **Automatic Multi-Architecture Deployment**: Monk now automatically detects your cluster's architecture and builds images accordingly - no manual configuration needed!
  * **Better Build Performance**: Fixed unnecessary cross-compilation when deploying from Apple Silicon to Intel clusters
  * **Smarter Deployments**: Only builds for the architectures actually used in your cluster

  ### New Agent Capabilities

  * Monk can detect cluster peer platforms and select native, cross-platform, or multi-architecture builds autonomously
  * Monk can build and push images to the configured registry with platform-aware tagging before deployment
</Update>

<Update label="2025-08-22" description="v0.12.2">
  ### Improvements

  * Improved deployment efficiency - fewer redundant operations
  * Better error handling when building multi-architecture images
  * Significantly faster builds when your local architecture matches your cluster
  * Support for insecure (non-TLS) container registries during deployment
  * Better compatibility with third-party container registries
  * Improved registry reachability detection using standard ports
</Update>

<Update label="2025-08-15" description="v0.12.0">
  ### Major Features

  * **New Onboarding Wizard**: First-time users get a guided setup experience
  * **Subscription Status**: Your subscription status is now displayed on the welcome screen
  * **Automatic Registry Setup**: No more manual registry credential prompts - Monk sets this up automatically
  * **Smart Deployment Checks**: Monk now ensures you have remote cluster nodes before allowing cluster deployments

  ### Improvements

  * Registry setup happens automatically after cluster growth
  * Better error messages and guidance throughout
  * Improved update notifications
  * Better handling of AWS Lambda and DynamoDB configurations
</Update>

<Update label="2025-08-11" description="v0.10.8">
  ### Major Features

  * **AWS Lambda & DynamoDB Support**: Monk can now deploy AWS Lambda functions and configure DynamoDB tables
  * **Improved Budget Management**: Chat continuation now costs 0.25 tokens with clearer prompts

  ### Features

  * New commands to update and manage registry addresses
  * Command to debug registry credentials

  ### Improvements

  * Token balance updates automatically after charges
  * Better handling of budget limits with clearer messaging
  * Fixed chat interface staying disabled after email verification
  * Improved email verification error messages with retry options
  * Better registry reliability with automatic reachability checks
  * Improved SSL compatibility for registry access
  * Fixed budget checking to prevent prompts when you have no tokens
  * Better error handling when chat sessions exceed budget
  * Fixed issue where chat could hang when budget limits were reached

  ### New Agent Capabilities

  * Monk can detect AWS Lambda handlers and model them as function components with an AWS Lambda deployment target
  * Monk can enrich AWS DynamoDB components with schema details inferred from code and infrastructure-as-code files
  * Monk can create DynamoDB tables with key schemas, GSIs/LSIs, billing modes, PITR, SSE, and table classes, and return table ARNs and names
  * Monk can put, get, delete, and scan items in DynamoDB tables
  * Monk can create and update Lambda functions from ZIPs or ECR images, configure environment variables, VPC networking, layers, logging, and X-Ray, and return function ARNs
  * Monk can invoke Lambda functions and update function code and configuration
  * Monk can create IAM roles with trust policies, attach and detach managed policies, and expose role ARNs for other services
  * Monk can create IAM policies from JSON documents and manage permissions for Lambda functions
</Update>

<Update label="2025-07-28" description="v0.10.5">
  ### Major Features

  * **CI/CD Automation**: New tool generates complete CI/CD configurations for GitHub Actions and CircleCI with automatic secrets management
  * **Vercel Support**: You can now authenticate with Vercel and deploy to their platform
  * **Hosting Platform Selection**: Monk helps you choose and configure Netlify or Vercel for your frontend applications
  * **Smart Conversation Management**: Long conversations are now automatically summarized to keep Monk's responses relevant and efficient
  * **Agent Refresh**: Monk automatically refreshes its understanding based on conversation length and activity

  ### Improvements

  * Monk now validates SSL certificates and manages secrets automatically for CI/CD pipelines
  * Build tool skips reporting non-critical environment issues
  * Better analytics tracking
  * Fixed chat spinner behavior - it now shows throughout the entire request
  * Better visual feedback when Monk asks questions
  * Ask prompts show immediate confirmation
  * Improved connection reliability and session management
  * Fixed task board event handling issues
  * Better connection handling after disconnections
  * More reliable task display
  * Better handling of configuration validation with helpful hints
  * Improved secret creation with better validation

  ### New Agent Capabilities

  * Monk can generate GitHub Actions workflows that build images and deploy using the MANIFEST
  * Monk can autonomously detect the repository and trigger branches for the CI/CD pipeline
  * Monk can create a short-lived Monk service token and inject it into CI/CD secrets securely
  * Monk can inject container registry address, username, and password into CI/CD secrets
  * Monk can detect or create a GitHub environment and place secrets there when appropriate
  * Monk can create or adopt Vercel projects, configure frameworks, Git repositories, build/install/dev commands, root directories, and custom domains
  * Monk can add and remove Vercel project domains and fetch production URLs
  * Monk can run Vercel production deployments from any directory using a managed builder image and a token from Monk secrets
  * Monk can guide hosting decisions between Netlify and Vercel and configure deployments with correct install, build, and output settings
  * Monk can verify Netlify and Vercel builds and provide concise, actionable guidance from build logs
</Update>

<Update label="2025-07-16" description="v0.10.0">
  ### Major Features

  * **Bug Reporting**: New integrated bug reporting system - describe issues right in the chat and optionally include logs, templates, and workspace details

  ### Improvements

  * Fixed issues with Monk expert agent reliability
  * Better error messages and clearer guidance
</Update>

<Update label="2025-07-14" description="v0.9.8">
  ### Improvements

  * Better version checking across all platforms (Linux, macOS, Windows)
  * Welcome screen now properly waits for setup to complete
  * Workload logs stay open even when containers restart
</Update>

<Update label="2025-07-08" description="v0.9.7">
  ### Major Features

  * **Full Chat Interface**: New dedicated chat panel with message streaming, conversation history, and real-time updates
  * **Interactive Questions**: When Monk asks questions, it now focuses the chat automatically so you don't miss them
  * **Build Summaries**: Collapsible build summaries show you what happened during builds
  * **Cross-Interface Sync**: Answer questions in either chat or task view, and both stay in sync

  ### UI Improvements

  * Better text wrapping in chat and task views
  * Improved progress indicators with checkmarks
  * Better styling and visual consistency
</Update>

<Update label="2025-07-04" description="v0.9.6">
  ### Improvements

  * Simplified budget continuation interface with just Yes/No buttons
  * Budget questions won't repeatedly prompt after you decline
  * Fixed memory leaks in chat handling
  * Fixed compatibility with Netlify and Windsurf
</Update>

<Update label="2025-07-03" description="v0.9.5">
  ### Improvements

  * Fixed authentication callbacks
  * Better backup scheduling support
  * Improved Netlify authentication flow
</Update>

<Update label="2025-07-02" description="v0.9.4">
  ### Major Update

  * Published to Open VSX Registry for wider IDE compatibility
  * Removed preview flag - Monk is production ready!
</Update>

<Update label="2025-06-19" description="v0.8.6">
  ### Major Features

  * **Ask Tool with Suggested Answers**: Monk can now provide suggested answers when asking questions
  * **Better Error Recovery**: Improved handling of network failures with automatic retry and reconnection

  ### Improvements

  * Fixed empty message handling
  * More resilient connection to backend
</Update>

<Update label="2025-06-12" description="v0.8.5">
  ### Major Features

  * **Template Editor**: Monk can now help you fix template errors and issues
  * **Task Timeline**: New timeline view in task cards showing agent reasoning and decision-making process

  ### Improvements

  * Better error messages with more context and helpful hints
  * Improved platform compatibility

  ### New Agent Capabilities

  * Monk can delegate template editing to a specialized editor agent and return a concise summary of fixes
  * Monk can edit Monk YAML templates and iterate until all diagnostics are resolved to zero (enhanced with diff preview)
</Update>

<Update label="2025-06-09" description="v0.8.3">
  ### Major Features

  * **YAML Language Support**: Full YAML editing support with syntax highlighting and validation
  * **New Welcome Screen**: Modern React-based welcome screen with interactive setup checklist
  * **Manifest Language Support**: Editor support for MANIFEST files with DIRS directive for better project organization

  ### Improvements

  * Monk now provides diagnostics and auto-completion for manifest files
  * Better visual feedback during setup process
  * Improved diagnostic accuracy
</Update>

<Update label="2025-05-21" description="v0.7.11">
  ### Improvements

  * Improved welcome screen with loading indicators
  * Better layout and overflow handling
  * Retry buttons for failed setup steps
</Update>

<Update label="2025-05-19" description="v0.7.10">
  ### Improvements

  * Monk can now set up Auth0 authentication for your applications
  * Welcome screen now allows continuing setup without closing
  * Better Auth0 domain handling

  ### New Agent Capabilities

  * Monk can extract or create Auth0 applications and provide client IDs and secrets
  * Monk can configure OAuth flows and return authorization and token endpoints
  * Monk can determine the application domain provider (Netlify site or container service) for Auth0 callback URLs
  * Monk can configure social login providers and return provider credentials
</Update>

<Update label="2025-05-12" description="v0.7.9">
  ### Improvements

  * Better Windows compatibility with platform-specific scripts
  * Improved "Retest" functionality in welcome screen
</Update>

<Update label="2025-04-22" description="v0.7.8">
  ### Major Features

  * **Enhanced Monk Tools**: New tools for calculating costs, growing clusters, pricing, and moving workloads
  * Support for .gitignore-style blob exclusion patterns

  ### Improvements

  * Better Java handling
  * Improved Go project support
  * More reliable Monk agent responses

  ### New Agent Capabilities

  * Monk can estimate costs for deployments and infrastructure choices
  * Monk can scale infrastructure and workloads dynamically to meet demand
  * Monk can move workloads between cluster tags or nodes to rebalance placement
</Update>

<Update label="2025-04-15" description="v0.7.7">
  ### Improvements

  * Better server URL configuration
  * Improved user preferences and tool descriptions
  * Updated to GPT-4.1 for better performance
</Update>

<Update label="2025-04-11" description="v0.7.6">
  ### Features

  * **Delete and Unload Tools**: Monk can now help you delete and unload workloads

  ### Improvements

  * Better error handling when operations fail
  * More reliable registry credential handling
  * Fixed Vercel integration
  * Better error notifications
  * Better Windows compatibility
  * Fixed various connection issues
  * Better validation of build configurations
  * Connection reliability fixes

  ### New Agent Capabilities

  * Monk can stop workloads gracefully to free resources without unloading templates
  * Monk can delete workloads and remove all runtime resources when cleanup is required
  * Monk can unload workloads to remove template definitions from the system
</Update>

<Update label="2025-04-07" description="v0.7.0">
  ### Major Features

  * **Subscription Support**: Full subscription and trial system implementation
  * **Removed Waitlist**: Monk is now available for general use
  * **Production Servers**: Extension now connects to production infrastructure by default

  ### Improvements

  * Better credential management
  * Improved connection handling
</Update>

<Update label="2025-04-04" description="v0.6.6">
  ### Improvements

  * Better template validation and cleanup
</Update>

<Update label="2025-03-31" description="v0.6.5">
  ### Features

  * Monk can now read and understand your existing templates better

  ### Improvements

  * Fixed terminal tools for non-running containers
  * Better Netlify deployment handling and configuration
  * Cancel button for authentication flows
  * Improved Vercel support
  * Enhanced authentication handling
  * Better image registry handling
  * Fixed extension activation when no workspace is open
  * Fixed startup stability issues
  * Better Netlify site naming
</Update>

<Update label="2025-03-26" description="v0.6.0">
  ### Major Features

  * **Netlify Deployments**: Full support for deploying frontend applications to Netlify
  * **Credential Management**: New tool to manage and delete credentials
  * **Domain Generation**: Automatic domain and SSL certificate generation when growing clusters

  ### New Agent Capabilities

  * Monk can create or adopt Netlify sites, configure custom domains and aliases, enable password protection and force SSL, and return site/admin URLs
  * Monk can list, create, get, and restore Netlify deploys for a site
  * Monk can run Netlify site deployments from any directory using a managed builder image and a token from Monk secrets
  * Monk can configure SPA rewrites for single-page applications on Netlify when frameworks do not handle routing
  * Monk can check whether required credentials are present for any provider or service
  * Monk can request cloud or service credentials from the user and store them securely
  * Monk can delete stored credentials on request to revoke access
</Update>

<Update label="2025-03-24" description="v0.5.12">
  ### Major Features

  * **Cross-Platform Support**: Full Windows support with automated setup checklist
  * **Welcome Page**: New welcome page for macOS with automated remediation
  * **Blob Storage**: Support for distributed blob storage across cluster nodes
  * Monk is now aware when you're not in a workspace

  ### Features

  * Progress updates during deployments
  * Automatic registry setup with retry support

  ### Improvements

  * Better event-driven status updates
  * Fixed icon bundling
  * Better ARM64 Mac support
  * Improved deployment reliability
  * Better image rebuilding before deployment
  * Enhanced credential management
  * Better manifest format for Docker images
  * Improved deployment process
  * Fixed credential handling
  * Better service provider recommendations
  * Improved image registry handling
  * Welcome screen now shows upgrade recommendations
  * Better error tracking and diagnostics
  * Improved macOS Podman detection
  * More robust welcome screen
  * Better Podman machine handling on macOS
  * Automatic upgrade support
  * Better image registry search
  * Better reconnection handling when server connection drops
  * Fixed WebSocket event handling

  ### New Agent Capabilities

  * Monk can store and retrieve distributed blobs across cluster nodes
  * Monk can mount blobs into containers for application data
  * Monk can synchronize blobs across cluster peers automatically
</Update>

<Update label="2025-03-09" description="v0.5.0">
  ### Improvements

  * Better image push to cluster registries
</Update>

<Update label="2025-03-08" description="v0.4.7">
  ### Features

  * SSH machine connections on macOS
  * Automatic cluster registry setup
  * Better registry push support
  * Improved release automation and deployment pipeline

  ***
</Update>

<Update label="2025-02-01" description="v0.4.2">
  ### Core Chat & AI Capabilities

  * AI-powered chat interface for natural language infrastructure management
  * Monk expert agent with comprehensive documentation knowledge
  * Agent reasoning and decision-making transparency
  * Custom instructions support

  ### Infrastructure Management

  * Cluster creation and growth tools
  * Cloud provider integration (AWS, DigitalOcean, Azure)
  * Multi-architecture image builds (ARM64/AMD64)
  * Container image management
  * Workload deployment and management tools

  ### Developer Tools

  * Template editor functionality
  * File search and analysis tools
  * Manifest and template validation

  ### Authentication & Security

  * Authentication flow with token management
  * Budget management system
  * Credential storage and management

  ### Network & Reliability

  * WebSocket-based communication protocol
  * Network failure recovery with automatic retry
  * Session management

  ### Initial Agent Capabilities

  * Monk can analyze a codebase and autonomously identify components, dependencies, and required services
  * Monk can discover environment variables, defaults, and service endpoints used by each component
  * Monk can infer relationships between variables across components and generate connection mappings
  * Monk can suggest safe default values and randomized secrets for configuration
  * Monk can operate across monorepos and multi-language stacks while ignoring non-deployable assets
  * Monk can containerize services by creating or adapting Dockerfiles specific to each component
  * Monk can build container images and run sanity checks, iterating until services start without critical errors
  * Monk can generate deployment configurations for projects end-to-end
  * Monk can bootstrap new clusters with minimal setup and without requiring an external control plane
  * Monk can manage clusters fully inside your cloud accounts (AWS, GCP, Azure, DigitalOcean)
  * Monk can autonomously configure networking, including subnets and security groups
  * Monk can set up encrypted overlay networks for secure intra-cluster communication
  * Monk can provide a built-in container registry for fast image pulls
  * Monk can provision a built-in container registry inside the system namespace with TLS and basic auth
  * Monk can deploy workloads locally or to a selected cluster using the project MANIFEST
  * Monk can create and provision clusters (VMs, networking, registries) as required by a deployment plan
  * Monk can deploy workloads by managing containers, secrets, environment variables, firewall rules, and external service wiring
  * Monk can update configurations and fix deployment errors autonomously
  * Monk can stream logs in real time from any container
  * Monk can provide instant shell access to any running container
  * Monk can open a shell terminal into a running workload for live debugging
  * Monk can stream logs and open a live logs terminal for a selected workload
  * Monk can answer natural-language questions about deployments and cluster health
  * Monk can select and integrate reusable vendor templates for databases, caches, queues, and other services
  * Monk can inject and propagate connection details between components via explicit variable relationships
</Update>


# Monk Features
Source: https://docs.monk.io/features

Deploy and manage full-stack applications with an autonomous AI DevOps agent

## Do Without Doing

You describe what you want. Monk analyzes your code, provisions infrastructure, and runs it in production across any cloud provider.

<CardGroup>
  <Card title="Autonomous Deployment" icon="rocket" href="/features/autonomous-deployment">
    Deploy multi-component apps without writing config files
  </Card>

  <Card title="Multi-Cloud Support" icon="globe" href="/features/multi-cloud">
    Deploy to AWS, GCP, Azure, DigitalOcean, Hetzner, and more
  </Card>

  <Card title="Package Ecosystem" icon="puzzle-piece" href="/features/service-templates">
    Pre-configured packages, automatically adapted to your stack
  </Card>

  <Card title="Agent Plugin" icon="terminal" href="/getting-started/get-started">
    Monk lives in your coding agent. No cloud consoles, no dashboards.
  </Card>
</CardGroup>

## What Makes Monk Different

<AccordionGroup>
  <Accordion title="It executes, not suggests" icon="brain">
    Monk doesn't hand you a plan and wait. It reads your code, provisions
    infrastructure, wires services together, and deploys. You stay in your
    editor the whole time.
  </Accordion>

  <Accordion title="Any language, any framework" icon="code">
    Monk understands your code structure regardless of the tech stack. You
    don't need to tell it what you're using.
  </Accordion>

  <Accordion title="Any cloud, no lock-in" icon="globe">
    Deploy to AWS, GCP, Azure, DigitalOcean, Hetzner, Netlify, Vercel, and others. Move
    between them when you need to.
  </Accordion>

  <Accordion title="Talk to it in plain language" icon="message">
    No CLI flags to memorize, no config file syntax to learn. Describe what you
    want and Monk does it.
  </Accordion>

  <Accordion title="Fits into agent workflows" icon="plug">
    Monk exposes itself to Claude Code, Gemini, Codex, Cursor, and other tools
    through MCP. Your coding agent delegates DevOps tasks to Monk without
    breaking your flow.
  </Accordion>

  <Accordion title="Cost-aware by default" icon="dollar-sign">
    Monk factors in cost when making infrastructure decisions. You get real-time
    breakdowns and recommendations to reduce spending.
  </Accordion>

  <Accordion title="Nothing to set up" icon="sparkles">
    Authorize Monk to work on your behalf. It handles the rest.
  </Accordion>
</AccordionGroup>

## Core Features

### Deployment & Build

Monk reads your code, containerizes it, and sets up build pipelines. You don't write deployment configs.

<CardGroup>
  <Card title="Autonomous Deployment" icon="rocket" href="/features/autonomous-deployment">
    From code to production, end to end
  </Card>

  <Card title="Code Analysis" icon="code" href="/features/code-analysis">
    Codebase understanding for any language
  </Card>

  <Card title="Containerization" icon="box" href="/features/containerization">
    Automatic container and orchestration setup
  </Card>

  <Card title="Build & CI/CD" icon="arrow-progress" href="/features/build-and-cicd">
    Build and deployment pipelines, generated for you
  </Card>

  <Card title="Capsules" icon="flask" href="/features/capsules">
    Automatic per-branch preview environments
  </Card>
</CardGroup>

### Infrastructure & Cloud

Monk provisions cloud resources across any provider. You can migrate workloads between clouds with a single command.

<CardGroup>
  <Card title="Cloud Provisioning" icon="server" href="/features/cloud-provisioning">
    Infrastructure setup on any cloud, handled for you
  </Card>

  <Card title="Multi-Cloud" icon="globe" href="/features/multi-cloud">
    Deploy across AWS, GCP, Azure, and more
  </Card>

  <Card title="Workload Migration" icon="shuffle" href="/features/workload-migration">
    Move apps between clouds with one command
  </Card>
</CardGroup>

### Configuration & Data

Monk generates service configs, deploys databases, and wires everything together.

<CardGroup>
  <Card title="Configuration & Wiring" icon="sliders" href="/features/configuration-and-wiring">
    Generated configs and service connections
  </Card>

  <Card title="Databases" icon="database" href="/features/databases">
    Deploy any database with one command
  </Card>

  <Card title="Essential Services" icon="boxes" href="/features/essential-services">
    Message queues and other services Monk can spin up
  </Card>

  <Card title="APIs" icon="webhook" href="/features/apis">
    API gateway, endpoints, and auth setup
  </Card>

  <Card title="Environments" icon="layer-group" href="/features/environments">
    Manage dev, staging, and production environments
  </Card>
</CardGroup>

### Networking & Security

Production-grade networking and security, configured automatically.

<CardGroup>
  <Card title="Networking" icon="network-wired" href="/features/networking">
    VPCs, load balancers, CDN, and traffic routing
  </Card>

  <Card title="Security" icon="shield" href="/features/security">
    SSL/TLS, firewalls, IAM, and security scanning
  </Card>
</CardGroup>

### Operations & Monitoring

Monitor, scale, and maintain your apps. Tell Monk what you need in plain language.

<CardGroup>
  <Card title="Monitoring" icon="gauge" href="/features/monitoring">
    Real-time monitoring and debugging from your coding agent
  </Card>

  <Card title="Watcher" icon="eye" href="/features/watcher">
    Autonomous monitoring and issue resolution
  </Card>

  <Card title="Updates & Maintenance" icon="refresh" href="/features/updates-and-maintenance">
    Push updates and maintain infrastructure via chat
  </Card>

  <Card title="Scaling" icon="arrow-trend-up" href="/features/scaling">
    Scale resources with plain language commands
  </Card>

  <Card title="Cost Tracking" icon="dollar-sign" href="/features/cost-tracking">
    Real-time cost tracking and breakdowns
  </Card>

  <Card title="Slack Integration" icon="slack" href="/features/slack">
    Manage infrastructure from Slack — questions, approvals, and alerts
  </Card>
</CardGroup>

### Developer Experience

Monk installs as a plugin in Claude Code, Cursor, Codex, and Antigravity. You deploy and manage everything through MCP without leaving your coding agent.

<CardGroup>
  <Card title="Agent Plugin" icon="terminal" href="/getting-started/get-started">
    Deploy and manage from your coding agent. No context switching.
  </Card>

  <Card title="MCP Support" icon="plug" href="/features/mcp-support">
    Use Monk with Claude, Gemini, Codex, Cursor, and other coding agents
  </Card>

  <Card title="Package Ecosystem" icon="puzzle-piece" href="/features/service-templates">
    Pre-configured packages, automatically adapted to your stack
  </Card>

  <Card title="Code Editing" icon="pen-to-square" href="/features/code-editing">
    AI-assisted code modifications and fixes
  </Card>
</CardGroup>

## Team Features

Features for teams managing multiple projects and environments.

<CardGroup>
  <Card title="Team Collaboration" icon="users" href="/features/team-collaboration">
    Shared workspaces and collaborative debugging
  </Card>

  <Card title="Project Organization" icon="folder-tree" href="/features/project-organization">
    Multi-project and environment management
  </Card>

  <Card title="Access Control" icon="lock" href="/features/access-control">
    RBAC, SSO, and team security controls
  </Card>

  <Card title="Custom Knowledge" icon="book-open" href="/features/custom-knowledge">
    Team-specific documentation and standards
  </Card>

  <Card title="Team Analytics" icon="bar-chart" href="/features/team-analytics">
    Usage metrics and cost allocation
  </Card>
</CardGroup>

<Card title="Get Started" icon="rocket" href="/getting-started/get-started">
  Install Monk and deploy your first app
</Card>


# Access Control & Security
Source: https://docs.monk.io/features/access-control

RBAC, audit logging, and team security

## What It Does

Monk controls who can do what across your organization. You define roles with fine-grained permissions, assign them to team members, and every action gets logged. That's it. No policy files, no YAML, no third-party auth layer.

## RBAC

You create custom roles. Each role gets explicit permissions over specific resources. Permissions are actions matched against resource patterns. Enforcement happens server-side, so it doesn't matter whether someone's using the agent plugin, the dashboard, or hitting the backend directly.

**Resource types:**

* Templates, Secrets, Images (environment-scoped)
* Builds, Clusters, Workspaces
* Org members, Org roles, Org settings
* Audit (team or self scope)

**Actions:**

* `read`, `write`, `admin`, `*`
* `deploy` (templates), `use` (secrets)

**Permission patterns:**

Glob patterns give you flexible matching:

* `/templates/**` — all templates
* `/environments/staging/secrets/**` — secrets in staging only
* `/clusters/**` — all clusters
* `/audit/team/**` — team-wide audit events

### Managing RBAC in the UI

Open the **Organization panel** and click **Manage Roles**.

**Creating roles:**

1. Click **Create new**
2. Enter role name and description
3. Add permissions — select resource type, action, and optional environment
4. Click **Create Role**

**Assigning roles:**

In the Organization panel overview, use the **Assign Role** card. Pick a member, pick a role, click Assign.

**Viewing member roles:**

<img alt="Monk RBAC" />

The Members table shows each member's assigned roles at a glance.

### Managing RBAC via Chat

You can do all of this through chat too.

```
/monk list roles for my organization
```

```
/monk create a role called deployer with deploy access to /templates/**
```

```
/monk give Alice the deployer role
```

```
/monk does Bob have access to /secrets/**?
```

```
/monk show my current permissions
```

## Audit Logging

Every action in your organization gets recorded. Builds, deployments, cluster operations, secret changes — all of it, with actor, status, and trace info attached.

**How to view:**

* **Activity panel:** Open it from the [Monk dashboard](https://monk.io/dashboard) for the full timeline.

Owners and admins see team-wide activity. Everyone else sees their own.

## Not Available Yet

Single sign-on, domain enforcement, and org-wide 2FA aren't available yet.

<CardGroup>
  <Card title="Team Collaboration" icon="users" href="/features/team-collaboration">
    Organizations, members, and shared clusters
  </Card>

  <Card title="Multiple Environments" icon="layer-group" href="/features/environments">
    Environment-scoped permissions and isolation
  </Card>
</CardGroup>


# APIs
Source: https://docs.monk.io/features/apis

Third-party API integration and lifecycle management

## What It Does

Your app talks to external services — Stripe for payments, Auth0 for authentication, SendGrid for emails, Twilio for SMS. These aren't infrastructure you run. They're third-party APIs your code depends on.

Monk doesn't just detect that you're using Stripe. It provisions Stripe resources, injects credentials into your app, and updates webhook URLs when your deployment changes. You provide credentials once. Monk handles the rest.

## How It Works

### API Orchestration

Monk treats third-party APIs as first-class resources, same as containers and cloud infrastructure.

**Example: Auth0 Integration**

1. During [code analysis](/features/code-analysis), Monk detects Auth0 SDK usage
2. You provide Auth0 management API credentials
3. Monk provisions an Auth0 application for your deployment
4. Monk obtains the client ID and secret, configures callback URLs (e.g., `https://yourapp.com/auth/callback`)
5. Monk injects credentials into your app via [Configuration & Wiring](/features/configuration-and-wiring)
6. When you redeploy or move clouds, Monk updates callback URLs automatically

Your code just initiates Auth0 login. Monk handles the rest.

**Example: Stripe Integration**

1. Monk detects Stripe SDK usage in your code
2. You provide Stripe API credentials
3. Monk creates webhook endpoints pointing to your API, configures signing secrets
4. Monk injects publishable and secret keys into frontend/backend
5. When you scale or redeploy, Monk updates webhook URLs to match

### Automatic Detection

During code analysis, Monk identifies your third-party API integrations — SDKs, API key references, webhook handlers, OAuth flows, and redirect URLs. It understands your API dependencies before you configure anything.

### Unified System Map

Monk maintains a complete map of your system: your containers, cloud infrastructure, [databases](/features/databases), [essential services](/features/essential-services), and third-party API resources. It tracks the relationships between all of them.

No more bouncing between the Stripe dashboard, Auth0 dashboard, AWS console, and DNS provider. It's all in one place.

### Dynamic Configuration Updates

When your deployment changes, API configurations need to follow. Monk handles this automatically — webhook URLs, OAuth callback URLs, CORS origins, API endpoint references, and signing secret rotation.

Without Monk, a redeployment means logging into every provider dashboard and updating URLs by hand. With Monk, you deploy and everything stays in sync.

### Authorization & Credentials

You provide API credentials for each service (API keys, OAuth tokens, management API access). Monk provisions resources, obtains necessary secrets, and updates configurations throughout the lifecycle.

<Info>
  Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS. They are never sent to Monk servers and never exposed to the LLM. Monk needs these because it manages your accounts with third-party providers on your behalf (BYOI). See [Security](/features/security) for details.
</Info>

### Supported Integrations

Monk supports several third-party API providers via [integrations](/integrations):

* **Identity & Authentication:** Auth0, AWS Cognito, AWS IAM
* **Payments:** Stripe (payment processing, subscriptions, webhooks)

Don't see your API? Let us know. Any API with a management interface can potentially be orchestrated by Monk.

## Next Steps

<CardGroup>
  <Card title="Configuration & Wiring" icon="plug" href="/features/configuration-and-wiring">
    How Monk injects credentials and connects your services.
  </Card>

  <Card title="Integrations" icon="puzzle-piece" href="/integrations">
    Full list of supported APIs and providers.
  </Card>
</CardGroup>


# Autonomous Deployment
Source: https://docs.monk.io/features/autonomous-deployment

End-to-end deployment automation from code to production

## What It Does

Open your project in your coding agent. Tell Monk to deploy it. Monk handles everything from code analysis to production — no configuration files, no container definitions, no infrastructure templates. It works whether you're shipping a single service or a polyglot monorepo.

## How It Works

### Phase 1: Analysis & Planning

Open your project in your [coding agent](/getting-started/get-started) and tell your coding agent to deploy it. Monk then:

1. **Analyzes your source code** — [Deep-dives](/features/code-analysis) into your app structure across any language or framework
2. **Maps all components** — Frontends, backends, API servers, workers, cron jobs
3. **Containerizes services** — [Builds containers](/features/containerization) for each component and verifies they run
4. **Identifies third-party services** — [Databases](/features/databases), [message queues](/features/essential-services), [APIs](/features/apis) your app depends on
5. **Infers configuration** — [Generates](/features/configuration-and-wiring) environment variables and connection strings based on service relationships

You get a human-readable configuration of your entire system to review before anything ships.

<img alt="Monk analyzing and planning a deployment" />

### Phase 2: Infrastructure & Deployment

Once you approve, Monk:

1. **Provisions infrastructure** — [Creates cloud resources](/features/cloud-provisioning) (VMs, GPUs, VPCs, load balancers) across [any provider](/features/multi-cloud)
2. **Deploys your app** — Your code and all third-party services, wired together
3. **Places each component optimally**:
   * **Frontend** (React, Vue, etc.) → Netlify or Vercel
   * **API server** → Containerized on cloud compute
   * **Database** → Managed service or self-hosted
   * **Workers** → Containerized with auto-scaling

### Example: E-commerce App

Say you have a project with a React frontend, Node.js API, Python recommendation engine, PostgreSQL, Redis, and Stripe.

**You:** `deploy this project`

**Monk:** Analyzes all three codebases, detects Postgres/Redis/Stripe dependencies, containerizes the Node.js and Python services, and presents a plan — frontend on Netlify, API on AWS ECS, recommendation engine on AWS with GPU, Postgres on RDS, Redis on Redis Cloud, Stripe wired in.

**You:** Approve and provide credentials.

**Monk:** Provisions everything and deploys. Fully wired, ready to go.

## Credentials & Security

Monk needs **credentials and authorization** for your cloud providers, hosting platforms, and database providers. That's the only thing it asks of you.

<Info>
  Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for details.
</Info>

You authorize Monk once per provider. It handles the rest.

> [How to obtain credentials](/getting-started/obtaining-credentials) for all supported providers

***

<CardGroup>
  <Card title="Code Analysis" icon="magnifying-glass-chart" href="/features/code-analysis">
    How Monk understands your codebase before deployment
  </Card>

  <Card title="Multi-Cloud Support" icon="globe" href="/features/multi-cloud">
    Deploy across AWS, GCP, Azure, DigitalOcean, Hetzner, and more
  </Card>
</CardGroup>


# Build & CI/CD
Source: https://docs.monk.io/features/build-and-cicd

Autonomous build and deployment pipelines

## What It Does

Once your app's deployed, Monk sets up continuous deployment. Every code push automatically updates your running application. No GitHub Actions workflows to write. No secrets to configure. No container registry setup.

Tell Monk to set up CI. Your app auto-deploys on every push to main.

## How to Set It Up

### Trigger CI/CD Setup

After your app is deployed, chat with Monk in your [coding agent](/getting-started/get-started):

**You:** `set up CI/CD for this project`

Monk walks you through the rest.

<img alt="CICD" />

### Prerequisites

You'll need:

1. **GitHub repository** - Your project must live in a GitHub repo
2. **Deployed application** - Your project must already be [deployed](/features/autonomous-deployment) and running
3. **GitHub PAT (optional)** - A [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) lets Monk automate the full setup

<Info>
  **Without a PAT:** Monk generates the necessary files and walks you
  through manual GitHub configuration. **With a PAT:** Monk handles everything
  automatically, including secure injection of deployment keys.
</Info>

## How It Works

### Step 1: Configuration

Once you ask Monk to configure CI and [code analysis](/features/code-analysis) completes, Monk:

1. **Generates a GitHub Action workflow** - Creates `.github/workflows/deploy.yml`
2. **Configures intelligent rebuilds** - Only rebuilds what changed:
   * [Service configuration](/features/configuration-and-wiring) updates
   * [Container](/features/containerization) rebuilds when code changes
   * Dependency updates when needed

### Step 2: Deployment Keys

**If you provided a GitHub PAT:**

* Monk injects deployment keys into your repository secrets
* Everything's configured automatically
* You just commit and push

**If you didn't provide a PAT:**

* Monk generates the necessary secrets
* Gives you step-by-step instructions for manual GitHub configuration
* Shows you exactly where to paste each secret

### Step 3: Activation

1. **Review the changes** - Monk shows you the generated workflow file
2. **Commit and push** - The changes go into your repository
3. **That's it** - Every push to `main` updates your deployment from here on

### The Build Process

The CI job mirrors what happened during initial deployment.

**On every push to main:**

1. **Code analysis** - Monk analyzes what changed
2. **Configuration update** - Updates [service configuration](/features/configuration-and-wiring) if needed
3. **Container rebuild** - Rebuilds [containers](/features/containerization) for modified services
4. **Zero-downtime deployment** - Monk's orchestrator updates running services without interruption
5. **Verification** - Confirms updated services are healthy

**Smart rebuilds:**

* Changed frontend — rebuilds and redeploys frontend only
* Changed API code — rebuilds API container, rolling update in production
* Changed worker — rebuilds worker container, replaces instances
* No code changes — skips unnecessary builds

## Currently Supported

**CI/CD Platform:**

* **GitHub Actions** - Fully supported

<Info>
  Support for Jenkins, GitLab CI/CD, Bitbucket Pipelines, and Azure DevOps is on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).
</Info>

## CI/CD vs. Capsules

CI/CD deploys a selected branch (typically `main`) to your existing, long-lived cluster — your production or staging environment. It's the pipeline that keeps your deployed application up to date with every merge.

[Capsules](/features/capsules) take this further: they use CI/CD to spin up an isolated, ephemeral cluster for every feature branch. Each cluster lives only as long as the branch does. Where CI/CD answers "how do I ship `main`?", Capsules answers "how do I test every branch in a real environment before it reaches `main`?"

You can use either or both. Most teams start with CI/CD for their main deployment and add Capsules when they want per-branch preview environments.

## Related Features

<CardGroup>
  <Card title="Capsules" icon="flask" href="/features/capsules">
    Per-branch preview environments — isolated, ephemeral clusters for every branch.
  </Card>

  <Card title="Autonomous Deployment" icon="rocket" href="/features/autonomous-deployment">
    How Monk handles your initial deployment before CI/CD kicks in.
  </Card>

  <Card title="Containerization" icon="cube" href="/features/containerization">
    How Monk builds and rebuilds containers during the CI process.
  </Card>
</CardGroup>


# Capsules
Source: https://docs.monk.io/features/capsules

Automatic per-branch preview environments — every push gets its own isolated cluster

## What It Does

Capsules gives every Git branch its own production environment — same cloud provider, same cluster topology, same container images, same deployment pipeline. The only difference is it runs your branch instead of `main`, and there are no users hitting it. Secrets can be shared with production or overridden per capsule.

Push a branch — Monk provisions a dedicated cloud cluster, builds your app, and deploys it with a unique TLS-enabled preview URL. Merge or delete the branch — the cluster is destroyed and all resources are released.

No shared staging. No environment conflicts. No forgotten resources running up cloud bills.

Available on Pro and Team plans.

<Info>
  Capsules and [CI/CD](/features/build-and-cicd) are complementary. CI/CD deploys a selected branch (typically `main`) to an existing, long-lived cluster. Capsules uses CI/CD to create isolated, ephemeral clusters for every other branch — each cluster lives only as long as the branch does.
</Info>

## Problems It Solves

**The staging bottleneck.** Teams share a handful of staging environments. Developers queue up to test, conflicts arise when multiple features land on the same environment, and bugs slip through because the test environment doesn't match what ships. Capsules eliminates this — every branch gets its own isolated environment.

**AI code verification.** AI agents can generate code, but without a real environment to deploy into, they can't verify it works. Capsules give agents a production-grade environment to deploy, test, and iterate against — so the output is code that demonstrably works, not code that should work.

## Setup

Open the Monk chat and say:

```
/monk set up Capsules
```

You can also say "enable preview environments" or "set up dynamic environments."

Monk walks you through a few choices:

<Steps>
  <Step title="Choose your cloud">
    Pick a cloud provider — AWS, Azure, GCP, DigitalOcean, or Hetzner — and select a region and instance size for capsule clusters.
  </Step>

  <Step title="Configure branch filtering">
    Choose which branches to exclude (typically `main` and `master` — your permanent environments). You can also filter by naming convention.
  </Step>

  <Step title="Monk generates everything">
    Monk creates a GitHub Actions workflow and supporting scripts, pushes all required credentials (cloud keys, API tokens) to GitHub as encrypted secrets, and commits the configuration to your repository.
  </Step>

  <Step title="Commit and push">
    Commit the generated files and push:

    ```bash theme={null}
    git add .github/workflows/dynenv.yml scripts/
    git commit -m "Add Monk Capsules configuration"
    git push
    ```
  </Step>
</Steps>

That's it. From this point on, everything is automatic.

**You need:**

* A project already [deployed through Monk](/features/autonomous-deployment) with a build manifest
* A GitHub repository with Actions enabled
* Cloud provider credentials for at least one provider
* An organization and project set up in Monk (Monk prompts you if these are missing)

## The Automatic Lifecycle

Once Capsules is configured, the lifecycle is fully automatic:

| Git event                             | What happens                                                                                                 |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Push a branch**                     | A new cluster is provisioned, containers are built, and the app is deployed. A pull request is auto-created. |
| **Push again to the same branch**     | The app is redeployed with the latest code. No new cluster needed.                                           |
| **PR is merged or branch is deleted** | The cluster is destroyed and all cloud resources are released.                                               |

Each capsule appears as a GitHub Deployment, so status is visible directly in pull requests — reviewers can see whether the environment is live, deploying, or failed without leaving GitHub.

## Schedule Policies

Capsules don't need to run 24/7. Schedule policies control when environments are up or down so you're not paying for idle clusters overnight.

**Set a schedule:**

```
/monk set capsules to run weekdays 8am-7pm UTC
```

**Check the current schedule:**

```
/monk show capsule schedule
```

**Override for a specific capsule:**

```
/monk override the schedule for the feature-auth capsule
```

**Clear an override:**

```
/monk clear the schedule override for feature-auth
```

Schedule options:

* **Daily windows** — e.g., up from 8 AM to 7 PM, down overnight
* **Weekly windows** — e.g., only on weekdays
* **Per-capsule overrides** — keep a specific capsule up during a demo, or shut one down early

Schedules can be set at the project level (applies to all capsules) or overridden per capsule. A background job enforces the schedule hourly.

## Managing Capsules

The [Monk dashboard](https://monk.io/dashboard) has a dedicated **Capsules** panel where you can see all active capsules, their branch, status, cluster, and preview URL.

You can also manage everything through the chat:

**List active capsules:**

```
/monk show my capsules
```

**Tear down a capsule manually:**

```
/monk destroy the capsule for feature-auth
```

**Provision a capsule manually:**

```
/monk provision a capsule for the feature-auth branch
```

### Updating Secrets

Capsule secrets can be updated in two modes:

```
/monk update capsule secrets
```

Monk asks you to choose:

* **Global** — updates GitHub encrypted secrets and the workflow. Affects all future capsules. Requires a commit and push.
* **Local** — injects secrets directly into the running capsule via the CLI. Immediate, but only affects that one instance.

### Manual GitHub Actions Dispatch

The generated workflow supports manual dispatch from the GitHub Actions tab. You can trigger `provision_deploy`, `deploy`, `deprovision`, or `destroy` for any branch.

## How Teams Use It

1. A developer creates a feature branch and pushes code
2. Within minutes, a fully deployed preview environment is live
3. The developer shares the preview URL in the PR for review
4. QA tests directly against the capsule — no waiting for staging
5. Product reviews the feature in an isolated, realistic setting
6. The PR is approved and merged — the capsule cleans itself up

No infrastructure tickets. No environment conflicts. No forgotten resources.

## For AI Agents

An AI coding agent can use Capsules to verify its own work:

1. Create a branch and write code
2. Push the branch — a capsule spins up automatically
3. Hit real endpoints, observe real behavior, read real logs
4. Find issues, fix them, push again — the capsule redeploys
5. Hand off a working, verified pull request — not a guess

The agent operates against a real running system that mirrors production, iterates until things work, and only surfaces results when they're validated.

## Key Details

* **Multi-cloud** — AWS, Azure, GCP, DigitalOcean, and Hetzner
* **Full isolation** — each capsule runs on its own cluster with no shared state
* **GitHub-native** — uses GitHub Actions for orchestration and GitHub Deployments for status tracking
* **Secure credentials** — cloud credentials and app secrets stored in GitHub's encrypted environment secrets; short-lived tokens minted at runtime
* **Preview URLs** — every capsule gets a TLS-enabled shareable URL
* **Branch filtering** — include or exclude branches by pattern

<CardGroup>
  <Card title="CI/CD" icon="arrow-progress" href="/features/build-and-cicd">
    Deploy a selected branch to a long-lived cluster — the pipeline Capsules builds on
  </Card>

  <Card title="Multiple Environments" icon="layer-group" href="/features/environments">
    Permanent staging, production, and dev environments on long-lived clusters
  </Card>
</CardGroup>


# Cloud Infrastructure
Source: https://docs.monk.io/features/cloud-provisioning

Autonomous cloud resource setup across providers

## What It Does

You describe what you need. Your coding agent and Monk figure out the infrastructure — VMs, networks, storage, load balancers, GPUs — and provision it across any cloud provider. No cloud consoles. No Terraform. No provider-specific tooling.

Monk reads your application's structure and requirements, then creates right-sized resources in the best regions for your workload.

## Supported Cloud Providers

Monk works with your existing cloud accounts:

* [AWS](https://aws.amazon.com/) — Full support
* [Google Cloud Platform](https://cloud.google.com/) — Full support
* [Microsoft Azure](https://azure.microsoft.com/) — Full support
* [DigitalOcean](https://www.digitalocean.com/) — Full support
* [Hetzner](https://www.hetzner.com/cloud) — Full support

<Info>
  **Need another provider?** [Let us know](/getting-help). Monk's architecture
  makes it straightforward to add new cloud platforms.
</Info>

## How It Works

### Connect Your Cloud Account

Monk uses your existing cloud accounts. No new accounts needed.

1. Monk detects it needs to provision resources
2. You're asked for cloud credentials for the target provider
3. You provide credentials once per provider

After that, Monk provisions and manages infrastructure automatically. No further cloud console work required.

<Warning>
  **Your credentials stay secure.** Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for full details.
</Warning>

> [Step-by-step credential guides](/getting-started/obtaining-credentials) for AWS, GCP, Azure, DigitalOcean, and Hetzner

### Intelligent Resource Selection

Based on [code analysis](/features/code-analysis), Monk understands what your app needs and provisions accordingly.

**Instance sizing:**

* **API servers** — sized for your expected traffic and compute needs
* **GPU workloads** — appropriate GPU instances for ML/AI services
* **Memory-intensive services** — sufficient RAM for databases, caches
* **Workers** — right-sized for background job processing

**Region selection:**

* **Performance** — minimizes latency to your users
* **Cost** — balances performance with budget
* **Compliance** — respects data residency requirements
* **Multi-region** — distributes across regions when needed

**You confirm before anything gets created.** Monk shows the proposed infrastructure. You can discuss, adjust, and approve — all in chat.

**Example conversation:**

```
Monk: Your API needs 2 VMs for the backend. I'm recommending:
      - 2x n1-standard-2 (2 vCPU, 7.5GB RAM) in us-central1
      - Estimated cost: ~$100/month

You: Can we use a cheaper region?

Monk: Sure! Using us-central1 (Iowa) is 15% cheaper than us-east1 (Virginia).
      Updated estimate: ~$85/month. Sound good?

You: Perfect

Monk: Creating resources...
```

### Core Resources

Monk provisions and manages these automatically.

**Compute:**

* **Virtual machines** — right-sized instances for your workloads
* **GPUs** — for AI/ML, rendering, or compute-intensive tasks

**Storage:**

* **Persistent volumes** — for databases and stateful services
* **Snapshots** — automatic backups with point-in-time recovery
* **Block storage** — attached to instances as needed

**Networking:**

* **VPCs** — isolated networks for your application
* **Subnets** — proper network segmentation
* **Security groups and firewalls** — access control
* **Load balancers** — traffic distribution and high availability

### Beyond Core Resources

Monk handles specialized cloud services too. See [Integrations](/integrations) for the full list:

* Managed databases (RDS, Cloud SQL, Azure Database)
* Object storage (S3, Cloud Storage, Azure Blob)
* Message queues (SQS, Pub/Sub, Service Bus)
* Caching services (ElastiCache, Memorystore)
* DNS services (Route 53, Cloud DNS, Azure DNS)

When your application needs one of these, Monk integrates it automatically.

### Intelligent Placement

Monk co-locates resources with their dependencies.

* Redis Cloud in GCP `eu-central`? Monk places your containers in the same region.
* AWS RDS in `us-west-2`? API servers go to `us-west-2`.
* External API in Europe? Services placed nearby for low latency.

It also understands third-party service locations (Redis Cloud, MongoDB Atlas, etc.), minimizes inter-cloud data transfer costs, and optimizes for latency when crossing provider boundaries.

### Multi-Region and Multi-Cloud

You can use one region for simplicity, or span multiple regions for global reach. Monk handles the complexity either way.

Not sure which region? Ask. "Which region should I use for US customers?" Monk recommends based on latency, cost, and availability.

You can also run parts of your application on different providers simultaneously — frontend on one, API on another, database on a third. See [Multi-Cloud Support](/features/multi-cloud) for details.

### Continuous Infrastructure Management

Monk doesn't just provision once. It manages infrastructure throughout your application's lifecycle.

**While your app runs, Monk:**

* **Adds resources** — scales up when needed
* **Removes unused resources** — cleans up to save costs
* **Tracks costs** — real-time spending per resource. See [Cost Tracking](/features/cost-tracking).
* **Optimizes placement** — adjusts based on usage patterns
* **Maintains security** — updates firewalls and security groups as needed

**You stay in control.** Monk asks before making significant changes. You can tell it to scale up, scale down, or optimize. Nothing happens without your approval.

## Next Steps

<CardGroup>
  <Card title="Multi-Cloud Support" icon="cloud" href="/features/multi-cloud">
    Deploy across multiple providers simultaneously.
  </Card>

  <Card title="Security" icon="shield" href="/features/security">
    How your infrastructure and credentials are protected.
  </Card>
</CardGroup>


# Code Analysis
Source: https://docs.monk.io/features/code-analysis

Monk reads your codebase and figures out what it needs to run

## What It Does

Monk analyzes your code, figures out what your app needs, and handles the rest. You don't write config files. You don't document your architecture. Your coding agent points Monk at a repo, and Monk understands it.

Single service or complex monorepo. Any language, any framework. Existing container or Kubernetes configs, or none at all — doesn't matter.

## How It Works

### When Analysis Happens

Monk analyzes your code automatically:

* **During deployment** — whenever you or your coding agent trigger a deploy
* **When changes are detected** — new services, swapped databases, restructured architecture
* **On demand** — tell Monk `analyse my project` to run analysis without deploying

<img alt="Analysis of the project" />

### What Monk Looks For

Monk doesn't read every line of source code. It targets specific indicators to build a picture of your application:

* **Entry points** — `main.py`, `index.js`, `server.go`, application start files
* **Environment variable references** — `process.env.DATABASE_URL`, `os.getenv()`, config loading
* **Dependencies** — `package.json`, `requirements.txt`, `go.mod`, `Gemfile`
* **Exposed endpoints** — API routes, port bindings, server configurations
* **Database connections** — ORM configs, database client initialization
* **Third-party integrations** — API clients, SDK usage, service connections

The goal: understand what your code does, what it connects to, and what values it needs to run.

### Existing Configuration

If you already have config files, Monk reads those too:

* **READMEs** — setup instructions, architecture notes
* **Compose files** — service definitions and relationships
* **Helm charts** — Kubernetes configurations
* **Terraform files** — infrastructure requirements
* **CI/CD configs** — build and deployment steps

<Info>
  Monk uses these files for additional context, but **doesn't require them**.
  Hand Monk raw code with zero config files and it'll figure everything out.
</Info>

### Example: What Monk Sees

Here's what Monk picks up in a typical Node.js + React project:

```
my-ecommerce-app/
├── frontend/
│   ├── package.json           # Monk sees: React dependencies, build scripts
│   ├── src/
│   │   ├── index.tsx         # Entry point for frontend
│   │   └── api/
│   │       └── client.ts     # Monk sees: API_URL environment variable needed
│   └── .env.example          # Monk reads: Expected environment variables
│
├── backend/
│   ├── package.json           # Monk sees: Express, pg (PostgreSQL client), Stripe SDK
│   ├── server.js             # Entry point, PORT binding (3000)
│   ├── routes/
│   │   ├── api.js            # Monk sees: REST endpoints exposed
│   │   └── payments.js       # Monk sees: Stripe integration needs STRIPE_SECRET_KEY
│   └── db/
│       └── connection.js     # Monk sees: PostgreSQL connection string needed
│
├── docker-compose.yml         # Monk reads: Service structure, postgres:14
└── README.md                  # Monk reads: "Run npm install, then npm start"
```

**From this, Monk understands:**

* **Frontend**: React SPA that needs an API connection — deploy to Netlify/Vercel
* **Backend**: Express API on port 3000, needs PostgreSQL and Stripe — containerize and deploy to cloud
* **Database**: PostgreSQL required — provision a managed instance or self-host
* **Config needed**: `API_URL`, `DATABASE_URL`, `STRIPE_SECRET_KEY`
* **Build process**: `npm install` then `npm start` for both services

### What Happens Next

Once Monk understands your code, your coding agent and Monk work together to:

1. **Configure and wire services** — generate all environment variables and connection strings
2. **Containerize your application** — create optimized containers tailored to your app
3. **Set up build & CI/CD** — create build pipelines that match your app's needs
4. **Deploy everything** — place each component on the right platform

## Privacy & Security

<Info>
  Fragments of your source code are sent to Monk servers for analysis but are
  **not stored** and are **not used for training**. The code is examined solely
  to infer deployment details. See [Security](/features/security) for full
  details on how your code and credentials are protected.
</Info>

<CardGroup>
  <Card title="Autonomous Deployment" icon="rocket" href="/features/autonomous-deployment">
    See how Monk deploys your app end-to-end after analysis.
  </Card>

  <Card title="Configuration & Wiring" icon="plug" href="/features/configuration-and-wiring">
    How Monk auto-generates configs from what it learns about your code.
  </Card>
</CardGroup>


# Source Code Editing (Alpha)
Source: https://docs.monk.io/features/code-editing

Targeted code fixes to resolve deployment issues

<Info>
  **Alpha Feature** -- Source code editing is currently in alpha. Monk makes
  targeted fixes to resolve deployment issues, not general code refactoring.
</Info>

## What It Does

When you deploy, Monk sometimes finds issues in your source code that block a successful deployment. Wrong ports, missing environment variables, broken connection strings, container build problems.

Monk doesn't just report these. It fixes them. Targeted, deployment-focused edits to get your app running.

## How It Works

### When Monk Edits Code

During deployment, if Monk hits a fixable issue, it tells you what's wrong and offers to fix it.

**Example -- Wrong Port Configuration:**

```
Monk: I found an issue: Your server listens on port 8080,
      but the Containerfile exposes port 3000.

      I can fix this in server.js. Should I proceed?

You: Yes, fix it

Monk: [Makes targeted change to port configuration]
      Fixed! Server now uses port 3000 to match Containerfile.
```

Monk shows you a diff before applying anything. You decide what happens next:

* **Approve** -- Apply the fix
* **Reject** -- Skip it
* **Revert** -- Undo after seeing the result

Every edit goes through this review. No changes land without your sign-off. Monk also keeps changes minimal and scoped strictly to deployment -- it won't touch business logic, and it can't edit secrets or template files. Rollback is always possible.

### Types of Fixes

**Deployment-related:**

* **Port configuration** -- Aligning server port with Containerfile EXPOSE
* **Environment variables** -- Reading from correct env var names
* **Connection strings** -- Fixing database URLs, Redis hosts
* **Build commands** -- Correcting package.json scripts, Makefiles
* **Entry points** -- Fixing main files, startup commands

**Containerization:**

* **Containerfile issues** -- EXPOSE directives, CMD/ENTRYPOINT
* **Build scripts** -- Missing build steps, incorrect paths
* **Health checks** -- Adding or fixing health check endpoints
* **Dependencies** -- Critical missing dependencies for deployment

**Configuration:**

* **Config file paths** -- Fixing paths that work locally but fail in containers
* **Static file serving** -- Correct asset paths for containerized apps
* **API endpoints** -- Environment-aware endpoint configuration

### What Monk Won't Touch

Monk's code editing is strictly for deployment. It won't:

* Add new features to your application
* Refactor code for better structure
* Fix business logic bugs
* Optimize performance (unless it blocks deployment)
* Modify your application's core functionality

Use your regular coding tools for application development. Use Monk for deployment fixes.

## Files Monk Can Edit

### Source Code

* **JavaScript/TypeScript:** `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.mjs`, `*.cjs`
* **Python:** `*.py`
* **Go:** `*.go`
* **Java/Kotlin:** `*.java`, `*.kt`
* **Rust:** `*.rs`
* **Ruby:** `*.rb`
* **PHP:** `*.php`
* **C/C++:** `*.c`, `*.cpp`, `*.h`, `*.hpp`
* **Shell scripts:** `*.sh`, `*.bash`

### Build & Configuration

* **Package files:** `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`
* **Build configs:** `tsconfig.json`, `jsconfig.json`, `pyproject.toml`, `Makefile`, `Procfile`
* **Container:** `Containerfile`, `docker-compose.yml`
* **CI/CD:** `.github/workflows/*.yml`, `netlify.toml`, `vercel.json`

### Off-Limits

* **Monk templates** -- `MANIFEST`, `*.yaml` (use the template editor)
* **Environment files** -- `.env`, `.env.production` (security)
* **Lock files** -- `package-lock.json`, `yarn.lock`, etc. (integrity)
* **Generated files** -- `dist/`, `build/`, `target/` directories
* **Binary files** -- Images, fonts, archives

## Example Scenarios

### Scenario 1: Port Mismatch

**Problem:** Containerfile exposes 3000, but Express app listens on 8080.

**Monk's fix:**

```typescript theme={null}
// server.js - BEFORE
const port = 8080;
app.listen(port);

// server.js - AFTER (Monk's fix)
const port = process.env.PORT || 3000;
app.listen(port);
```

Aligns your code with what the container expects.

### Scenario 2: Missing Environment Variable

**Problem:** App crashes because DATABASE\_URL isn't read from the environment.

**Monk's fix:**

```python theme={null}
# config.py - BEFORE
DB_URL = "postgresql://localhost/mydb"

# config.py - AFTER (Monk's fix)
import os
DB_URL = os.environ.get("DATABASE_URL", "postgresql://localhost/mydb")
```

Now the app works with Monk's configuration injection.

### Scenario 3: Incorrect Connection String

**Problem:** Hardcoded localhost Redis connection fails in production.

**Monk's fix:**

```javascript theme={null}
// redis.js - BEFORE
const redis = new Redis({ host: 'localhost', port: 6379 });

// redis.js - AFTER (Monk's fix)
const redis = new Redis({
  host: process.env.REDIS_HOST || 'localhost',
  port: parseInt(process.env.REDIS_PORT || '6379')
});
```

Lets Monk inject the correct Redis connection details.

### Scenario 4: Container Build Issue

**Problem:** Containerfile COPY command fails because the path is wrong.

**Monk's fix:**

```dockerfile theme={null}
# Containerfile - BEFORE
COPY src/app /app

# Containerfile - AFTER (Monk's fix)
COPY ./src /app/src
```

Fixes the build error. That's it.

## When Code Editing Happens

### During Deployment

Most often, during initial deployment:

```
/monk deploy this project
```

Monk may find that the container build fails, the app crashes on startup, or the health check hits the wrong port. Instead of stopping, it proposes fixes.

### On Demand

You can ask directly:

```
/monk fix the container build error
```

```
/monk update my code to use environment variables
```

```
/monk fix the port configuration for deployment
```

Monk examines the issue and proposes targeted fixes.

### After Failed Deployments

If a deployment fails due to code issues:

```
Monk: Deployment failed. The API server expects REDIS_URL
      but your code only reads REDIS_HOST and REDIS_PORT.

      I can update your code to read from REDIS_URL instead.
      Should I fix this?
```

## Limitations

<Info>
  This is an **alpha feature**. It works well for common deployment issues but may not catch every edge case.
  Best suited for straightforward codebases. Complex fixes may still need human review.
  Monk errs on the side of caution -- if it's unsure, it asks rather than guessing.
</Info>

Monk doesn't generate new features, write application logic, implement business requirements, or create new components. It fixes what's blocking your deployment. Nothing more.

<CardGroup>
  <Card title="Autonomous Deployment" icon="rocket" href="/features/autonomous-deployment">
    See how code editing fits into Monk's deployment flow.
  </Card>

  <Card title="Configuration & Wiring" icon="plug" href="/features/configuration-and-wiring">
    How Monk handles environment variables and service connections.
  </Card>
</CardGroup>


# Configuration & Wiring
Source: https://docs.monk.io/features/configuration-and-wiring

Auto-generated configs and service connections

## What It Does

Your services need to talk to each other. Your API needs database credentials. Your frontend needs the API URL. Your workers need message queue config.

Monk figures this out during [code analysis](/features/code-analysis) and generates the complete configuration for your entire application. Connection strings, environment variables, secrets — all derived and wired automatically.

## How It Works

### Automatic Configuration Generation

Based on code analysis, Monk computes every configuration value you need.

**What Monk discovers:**

* Environment variables your code references (`DATABASE_URL`, `API_KEY`, etc.)
* Services that need to connect (API to Database, Worker to Redis)
* External APIs your application calls
* Port numbers and endpoints
* Secret values that need protection

**What Monk generates:**

* Database connection strings (`postgresql://user:pass@host:5432/db`)
* Service URLs (`https://api.yourapp.com`)
* API endpoints between services (`http://api-service:3000/graphql`)
* Credentials for databases and services
* All environment variables your code expects

Monk asks for clarification when it needs your input.

### Dynamic Service Discovery

You don't need to know database hostnames, internal IPs, or port numbers. Monk uses built-in service discovery to derive values dynamically:

* **Database connection strings** — Generated from database host, port, and credentials
* **Service endpoints** — Internal URLs for service-to-service communication
* **Load balancer URLs** — Public endpoints for external access
* **Network addresses** — Container IPs and DNS names

Scale from 1 to 5 API servers. All 5 get the correct configuration automatically.

### Intelligent Connection Mapping

Monk understands how your components connect and configures discovery accordingly.

**Network connections:**

* API server to Database (TCP, credentials needed)
* Worker to Message queue (pub/sub, connection string needed)
* Services within application (internal DNS, no auth needed)

**Callback connections:**

* Webhook URLs for external services (Stripe, GitHub, etc.)
* OAuth redirect URLs
* API callback endpoints

**Browser-server connections:**

* Frontend to API (public URL, CORS configuration)
* Static assets to CDN (public URLs)

Monk configures each type appropriately. Internal services use private DNS and encrypted tunnels. Public endpoints get load balancer URLs. Callbacks receive publicly accessible URLs. CORS is configured for frontend-backend communication.

### Automatic Secret Detection

Monk knows which values are secrets and treats them — and anything derived from them — securely.

**Automatically identified as secrets:**

* Database passwords
* API keys (Stripe, OpenAI, AWS credentials, etc.)
* JWT signing keys
* OAuth client secrets
* Encryption keys

**Secret handling:**

* Stored in built-in secret storage
* Never exposed in configuration files
* Injected securely at runtime
* Rotatable without code changes

### Reconfiguration at Any Time

You don't need to get configuration right upfront. Tell Monk to reconfigure whenever you want:

```
You: Change the database connection pool size to 20
```

```
You: Add FEATURE_FLAG_NEW_UI to the frontend
```

<Info>Configuration changes are applied with zero downtime after deployment.</Info>

### Review & Modify Full Configuration

You can review the full configuration file and ask Monk to modify any part of it.

## What You Need to Provide

Monk derives most configuration automatically. You provide only what it can't discover:

**External API keys:**

* Stripe, OpenAI, SendGrid, Twilio, etc.
* Monk asks for these when it finds references in your code

**Custom configuration:**

* Feature flags
* Business logic constants
* Non-standard environment variables

**Domain names:**

* Your custom domain (if not inferred from code)
* Email sending domain

That's it. Connection strings, credentials, service URLs — Monk generates all of it.

<CardGroup>
  <Card title="Code Analysis" icon="code" href="/features/code-analysis">
    How Monk discovers your configuration requirements from source code.
  </Card>

  <Card title="Security" icon="shield" href="/features/security">
    How secrets are stored, injected, and protected at runtime.
  </Card>
</CardGroup>


# Containerization & Orchestration
Source: https://docs.monk.io/features/containerization

Automatic containerization and workload management

## What It Does

Your backend services — API servers, workers, background jobs — need to run somewhere. You put them in containers that can run on any cloud VM.

After Monk [analyzes your code](/features/code-analysis), it containerizes the components that need it, tests them, and prepares them for deployment. No Containerfiles required. If you have them, Monk uses them.

<img alt="Containerization" />

## How Containerization Works

### Automatic Container Creation

After code analysis, Monk identifies which components need containerization:

* **API servers** — Express, FastAPI, Spring Boot, Go HTTP servers, etc.
* **Backend services** — Node.js, Python, Go, Java, Ruby, .NET services
* **Workers** — Celery, Sidekiq, background job processors
* **Scheduled tasks** — Cron jobs, periodic workers

For each component, Monk either uses your existing container configuration or generates one from scratch.

### Using Existing Containerfiles

If you already have a `Containerfile`, Monk will:

1. **Build it** — Uses your existing configuration as-is
2. **Test the container** — Boots it up to verify it works
3. **Iterate if needed** — If there are issues, Monk fixes them automatically
4. **Optimize if possible** — Suggests improvements for security and performance

### Generating New Containerfiles

No Containerfile? Monk generates one using best practices.

**Multi-stage builds** — Separate build and runtime stages to minimize image size:

```
# Example of what Monk generates for a Node.js API
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
```

What you'll see in practice:

* **Small base images** — Alpine Linux or distroless when possible
* **Security hardened** — Non-root users, minimal attack surface
* **Optimized layers** — Proper caching for faster builds
* **Framework-specific** — Tailored to Django, Rails, Spring Boot, etc.

### Testing & Iteration

Monk doesn't just generate containers. It validates they work.

1. **Builds the container** locally on your machine
2. **Starts the container** and tests if the service boots
3. **Checks health** to verify the service responds
4. **Fixes issues** — if problems occur, Monk iterates until they're resolved

**Example iteration:**

```
Monk: Built container for API server
Monk: Testing... Port 3000 not accessible
Monk: Issue found - server.js listens on port 8080, Containerfile exposes 3000
Monk: I can fix the port in your code. Should I proceed?
You: Yes
Monk: Fixed server.js to use PORT env var, rebuilding...
Monk: Testing... Success! Container running on port 3000
```

Monk can make targeted code fixes to resolve deployment issues.

> See [Source Code Editing](/features/code-editing) for details on code fixes

### Local Build + CI/CD Integration

Containerization happens in two places:

**Locally** — On your machine when you first deploy. Monk builds containers locally so you can test and verify before anything goes to production.

**CI/CD** — Monk [configures your pipeline](/features/build-and-cicd) so containers rebuild automatically when you push changes. Your production images stay current without manual intervention.

### Zero-Config Container Registry

Every Monk deployment includes a private container registry. No setup required.

* Your container images are stored securely
* Direct push from your machine or CI workflow
* Images deploy straight to the runtime environment
* No external registry accounts needed

<Info>
  **BYOI principle:** The container registry runs on your infrastructure, just
  like everything else Monk manages. Your images never leave your control.
</Info>

## How Orchestration Works

### Monk's Built-in Orchestrator

Monk includes a distributed orchestrator that manages all your containers regardless of where they run. It doesn't use Kubernetes under the hood.

What this means for you:

* **Direct control** — Monk manages containers natively, no abstraction layers
* **Multi-cloud aware** — Works across AWS, GCP, Azure, DigitalOcean, Hetzner
* **Unified control plane** — Replaces both Terraform and Kubernetes functions
* **Resource efficient** — No K8s overhead or complexity

### What the Orchestrator Handles

**Live resource tracking** — A real-time resource graph of your entire infrastructure. It understands dependencies, relationships, and the lifecycle of every component.

**Networking** — Automatic network segmentation, encrypted service-to-service connections, cross-region and cross-cloud support. See [Networking](/features/networking) for details.

**Cost awareness** — Tracks the cost of each resource over time. See [Cost Tracking](/features/cost-tracking) for real-time monitoring.

**Multi-cloud orchestration** — Manages containers across different providers simultaneously. One-command cluster spin-up. Works on-prem too. See [Multi-Cloud Support](/features/multi-cloud) for details.

### Universal Container Support

While Monk provides a private registry, it pulls from anywhere — AWS ECR, Google Container Registry, Azure Container Registry, public registries, private registries. You provide the address and credentials, and Monk handles the rest.

## Example: Multi-Service Application

Here's containerization in action with a Python + Node.js app.

**Your application:**

* FastAPI backend (Python)
* React frontend (doesn't need containerization — goes to Netlify)
* Celery worker (Python)
* PostgreSQL database (managed service — no container needed)

**What Monk does:**

1. **Analyzes components** — FastAPI and Celery need containers

2. **Generates Containerfiles:**

   ```
   # FastAPI
   FROM python:3.11-slim
   WORKDIR /app
   COPY requirements.txt .
   RUN pip install -r requirements.txt
   COPY . .
   CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

   # Celery
   FROM python:3.11-slim
   WORKDIR /app
   COPY requirements.txt .
   RUN pip install -r requirements.txt
   COPY . .
   CMD ["celery", "-A", "tasks", "worker"]
   ```

3. **Builds and tests** both containers locally

4. **Pushes to registry** in your cloud account

5. **Deploys containers** with proper orchestration

<CardGroup>
  <Card title="Code Analysis" icon="magnifying-glass" href="/features/code-analysis">
    How Monk understands what to containerize
  </Card>

  <Card title="Build & CI/CD" icon="arrows-spin" href="/features/build-and-cicd">
    Automatic container rebuilds on every push
  </Card>
</CardGroup>


# Cost Tracking
Source: https://docs.monk.io/features/cost-tracking

Real-time cost tracking and breakdowns

## What It Does

Monk tracks the cost of your entire infrastructure in real-time. Ask for current costs, projections, or comparisons. Monk knows the price of every resource across all cloud providers and integrations.

## How It Works

### Cost Knowledge Base

Monk maintains up-to-date cost information for cloud resources.

**What Monk tracks:**

* **Cloud provider pricing** - Current rates from AWS, GCP, Azure, DigitalOcean, Hetzner
* **Resource uptime** - How long each resource has been running
* **Integration pricing** - Costs for [databases](/features/databases), [essential services](/features/essential-services), and [APIs](/features/apis) that implement cost estimation
* **Usage-based pricing** - Data transfer, storage, API calls where applicable

<img alt="Cluster cost calculated by Monk" />

Monk continuously updates its pricing database to ensure accuracy.

### Real-Time Cost Queries

Ask Monk for cost information anytime via chat in your [coding agent](/getting-started/get-started).

**Current costs:**

```
You: What's the current cost of running this system?

Monk: Current infrastructure cost breakdown:
      - 4x AWS t3.medium instances: $0.33/hour ($240/month)
      - PostgreSQL RDS (db.t3.medium): $0.068/hour ($50/month)
      - Redis ElastiCache (cache.t3.micro): $0.017/hour ($12/month)
      - Application Load Balancer: $0.025/hour ($18/month)

      Total: $0.44/hour ($320/month)
```

**Different time units:**

```
You: How much per day?

Monk: Current daily cost: $10.56
```

```
You: Cost per week?

Monk: Current weekly cost: $73.92
```

```
You: Show me cost per second

Monk: Current cost: $0.000122/second
```

Monk can express costs in any time unit: second, hour, day, week, month.

### Cost Projections & Estimates

You want to know future costs. Ask Monk to project.

**Monthly projections:**

```
You: Project the monthly cost

Monk: Based on current usage:
      - Monthly projection: $320
      - Assumes 24/7 operation
      - Does not include usage-based charges (data transfer, API calls)
```

**Estimate before changes:**

```
You: How much would it cost to add 2 more instances?

Monk: Cost estimate with 2 additional t3.medium instances:
      - Current: $0.44/hour ($320/month)
      - With 2 more: $0.60/hour ($440/month)
      - Increase: $0.16/hour ($120/month, +37.5%)
```

You know the cost impact before you make infrastructure changes. That's it. No spreadsheets, no manual calculations.

### Integration Cost Support

Many [integrations](/integrations) implement Monk's cost estimation interface.

**Supported:**

* **Cloud-managed databases** - RDS, Cloud SQL, Azure Database, DigitalOcean Managed Database
* **Cloud storage** - S3, Cloud Storage, Azure Blob, DigitalOcean Spaces
* **Managed caches** - ElastiCache, Memorystore, Redis Cloud
* **Third-party services** - MongoDB Atlas, Redis Cloud, Neon, and more

**Coverage varies:**

* Core cloud resources (VMs, storage, networking) - Fully tracked
* Popular managed services - Some tracked
* Specialized integrations - Varies (we're working to cover all of them)

<Info>
  **Integration cost tracking:** Coverage is continuously improving. Check with
  Monk to see if a specific service supports cost estimation, or refer to
  [Integrations](/integrations) for details.
</Info>

### Cost Comparison (Hypothetical Resources)

Here's where it gets interesting. Monk understands costs of resources **you're not even using**.

Want to know if switching clouds or regions would save money? Just ask.

```
You: How much would this cost on DigitalOcean instead of AWS?

Monk: Current AWS cost: $0.44/hour ($320/month)
      Equivalent DigitalOcean Droplets: $0.28/hour ($205/month)
      Savings: $115/month (36% cheaper)
```

```
You: What if we moved to us-west-2 instead of us-east-1?

Monk: Same infrastructure in us-west-2:
      Cost: $0.46/hour ($335/month)
      Difference: +$15/month (5% more expensive)
```

```
You: Compare cost of running this on GCP vs Azure

Monk: Current (AWS): $320/month
      GCP equivalent: $295/month (-$25/month)
      Azure equivalent: $340/month (+$20/month)
```

**Use cases:**

* **Before deployment** - Compare clouds to choose the most cost-effective
* **Migration planning** - See if [migrating](/features/workload-migration) would save money
* **Region selection** - Pick the cheapest region for your needs
* **Optimization** - Evaluate alternatives to reduce costs

## Coming Soon

<Info>Proactive cost analysis — 24/7 monitoring, optimization proposals, autonomous execution, budget alerts — is on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

Here's what that'll look like:

```
Monk: Cost analysis complete. I found 3 optimization opportunities:

      1. API servers running at 20% average CPU
         → Downsize from t3.medium to t3.small
         → Savings: $120/month

      2. Database idle 18 hours/day
         → Switch to smaller instance during off-peak
         → Savings: $25/month

      3. Redis cache hit rate only 40%
         → Reduce cache size by 50%
         → Savings: $6/month

      Total potential savings: $151/month (43%)

      Approve these changes?

You: Yes, do it
```

No manual cost analysis, no spreadsheets. Monk handles it autonomously.

## Related Features

<CardGroup>
  <Card title="Cloud Infrastructure" icon="cloud" href="/features/cloud-provisioning">
    The resources Monk tracks costs for.
  </Card>

  <Card title="Workload Migration" icon="arrows-rotate" href="/features/workload-migration">
    Migrate to a cheaper cloud when the numbers say so.
  </Card>
</CardGroup>


# Custom Policies
Source: https://docs.monk.io/features/custom-knowledge

Team-specific policies and instructions for Monk agents

## What It Does

Custom policies let you define rules that Monk agents follow across your organization. You write them in Markdown. Monk reads them before every action it takes.

No ambiguity. No drift. Every team member gets the same behavior from Monk, every time.

## How It Works

Admins create instruction files scoped to three levels:

* **Organization** — applies to all members and clusters.
* **Environment** — applies when deploying to that environment.
* **Cluster** — applies when connected to that cluster.

These instructions shape everything Monk does: chat responses, project generation, infrastructure decisions, and deployments. They're enforced automatically through RBAC — you don't need to remind anyone to follow them.

Instruction files can contain any guidance you'd give a new team member:

* "Don't spawn instances larger than t3.large."
* "Always use AWS RDS for PostgreSQL. Never self-hosted."
* "Require approval before deploying to production."
* "No public IPs in production."
* "Use the internal container registry only."

## Example Instruction File

```markdown theme={null}
# Team Deployment Rules

## Instance Sizing
- Use t3.medium for staging, t3.large for production.
- Never use instances larger than t3.xlarge without approval.

## Database
- Always use AWS RDS for PostgreSQL.
- Do not deploy self-hosted databases.

## Secrets
- Never store secrets in environment variables directly.
- Use team-scoped secrets for all credentials.
```

That's it. Monk reads this file and applies it to every action it takes within the defined scope. Your standards persist even as the team changes.

## Availability

Available on the Team plan only.

## Next Steps

<CardGroup>
  <Card title="Access Control & Security" icon="shield-halved" href="/features/access-control">
    Set up RBAC and audit logging to govern who can change policies.
  </Card>

  <Card title="Team Collaboration" icon="users" href="/features/team-collaboration">
    Manage your organization and invite members.
  </Card>
</CardGroup>


# Monk Dashboard
Source: https://docs.monk.io/features/dashboard

The web console for your account, teams, clusters, and billing

The Monk dashboard at [monk.io/dashboard](https://monk.io/dashboard) is the web console for everything that lives above a single deployment: your account, teams, projects, clusters, access control, audit, and billing. Day-to-day deploy and operate work happens in your coding agent; the dashboard is where you manage the organization around it.

It is also the easiest place to [create your Monk account](https://monk.io/dashboard): sign-up starts a 5-day free trial, no credit card required.

<img alt="Monk dashboard overview" />

## Finding Your Way Around

The top bar has a context switcher: flip between your **Personal** scope and any **team**, and optionally focus a single project. Global search (<kbd>⌘K</kbd>) jumps to any project, environment, or cluster. The top-right corner has a theme toggle, your account menu, and a **bug icon** for reporting issues directly to the engineering team.

## What's Where

**Overview** — landing page with project, environment, and cluster counts, subscription status, watcher credits, and infrastructure cost for the month.

**Build** — *Projects* (create, custom instructions, capsule schedules), *Environments* (including PR-preview capsules with branch, PR link, and preview URL), *Clusters* (live status, members, and per-cluster detail), and *Workspaces* (editor workspaces linked to projects).

**Access Control** (teams) — *Members* with role management and email invites, *Roles* with a permission builder for custom roles, and *Assignments* binding roles to members with project or environment scope.

**Observability** (teams) — *Audit*: the event log of everything agents and members did, grouped into traces, filterable by project.

**Billing** — *Infra* shows cloud cost and Monk fees per cluster and month; *Subscription* manages your plan, seats, and Stripe billing portal.

**System** — *Settings* for cluster access policy, org-wide custom instructions, and billing alerts; *Install Monk* for connecting coding agents.

## Reporting Bugs

Click the bug icon in the top-right corner, pick Bug, Feature, or Other, and describe the issue. You can also report from your coding agent with `/monk report a bug` — see [Getting Help](/getting-help).

<Card title="Team collaboration" icon="users" href="/features/team-collaboration">
  How teams, invites, and shared clusters work
</Card>


# Databases
Source: https://docs.monk.io/features/databases

Deploy any database with one command

## What It Does

Your app needs a database. Monk detects that during [code analysis](/features/code-analysis), then provisions and configures it automatically — PostgreSQL, MongoDB, Redis, or any of 20+ supported databases.

You pick the deployment model: self-hosted containers, cloud-managed services, or third-party providers. Monk handles provisioning, connection strings, and configuration.

## How It Works

### Automatic Database Detection

During code analysis, Monk figures out what your app needs:

* Database type (PostgreSQL, MySQL, MongoDB, Redis, etc.)
* ORM or driver in use (Prisma, SQLAlchemy, Mongoose, etc.)
* Connection string references in your code
* Schema files and migrations
* Required features (full-text search, JSON columns, etc.)

No upfront configuration required. Monk reads the code and acts on it.

### Deployment Options

Once Monk knows which database you need, you choose how to deploy it.

#### Option 1: Self-Hosted in Containers

**Best for:** Development, staging, proof-of-concept

* Runs in a container on your infrastructure
* Monk handles setup, persistence, and configuration
* Fast to spin up, easy to tear down
* Full control over version and settings

#### Option 2: Cloud Provider Managed Database

**Best for:** Production, simplified operations, automatic backups

* Uses your cloud provider's managed service (AWS RDS, GCP Cloud SQL, Azure Database, DigitalOcean Managed Database)
* Automatic backups, updates, high availability
* You provide cloud credentials, Monk provisions and configures

#### Option 3: Third-Party Managed Database

**Best for:** Specialized features, global distribution, serverless scaling

* Uses specialized providers (MongoDB Atlas, Redis Cloud, Neon, PlanetScale)
* Often includes free tiers or serverless pricing
* Advanced features like multi-region replication

**Progression example (MongoDB):**

* Start with **MongoDB Community** (containerized) for development
* Move to **DigitalOcean Managed MongoDB** for production simplicity
* Scale to **MongoDB Atlas** for global distribution

Monk recommends the best option based on your stage, scale, and requirements. You decide.

### Supported Databases

Monk supports 20+ databases out of the box. Here are the highlights:

* **PostgreSQL** — the go-to relational database
* **MySQL** — widely supported, battle-tested
* **MongoDB** — flexible document store
* **Redis** — in-memory caching and data structures
* **Cassandra** — distributed, high-availability NoSQL
* **TimescaleDB** — time-series on top of PostgreSQL
* **Neo4j** — graph database
* **Elasticsearch** — full-text search and analytics

See [Integrations](/integrations) for the full list of supported databases.

### Automatic Connection Management

Monk generates and manages connection strings automatically via [Configuration & Wiring](/features/configuration-and-wiring):

* Connection string generation (`postgresql://user:pass@host:5432/db`)
* Credentials creation and secure storage
* Network configuration for database access
* Connection pooling settings
* SSL/TLS encryption setup

Switch between deployment options without changing your code.

<Warning>
  **Data migration between databases** isn't automated yet. When switching from
  self-hosted to managed (or vice versa), Monk updates connection strings but
  doesn't transfer data. You'll need to migrate data manually (export/import).
</Warning>

### Database Credentials

When you use managed databases (MongoDB Atlas, Redis Cloud, cloud provider databases), Monk requests the necessary credentials automatically.

**Third-party services:**

* MongoDB Atlas, Redis Cloud, Neon — Monk asks for API keys when needed

**Cloud-managed databases:**

* AWS RDS, GCP Cloud SQL, etc. — uses your cloud provider credentials

> [How to obtain database credentials](/getting-started/obtaining-credentials)

### Database Configuration

Monk can tune database settings to match your requirements:

* Memory allocation and caching
* Connection pool sizes
* Query timeouts
* Storage size and IOPS
* Replication settings
* Performance tuning parameters

Tell Monk what you need in plain language. It understands database-specific parameters for every supported engine.

### Backups & Restore

<Info>
  Automated backup integration via chat is still in development. Some managed services
  already expose backup APIs that Monk can leverage — check individual integration docs
  for details.
</Info>

**Managed databases with backup API support:**

* **MongoDB Atlas** (M10+ dedicated clusters)
* **AWS RDS** (PostgreSQL, MySQL, MariaDB, SQL Server, Oracle)
* **DigitalOcean Managed Databases** (PostgreSQL, MySQL, MongoDB, Valkey)
* **GCP Cloud SQL** (PostgreSQL, MySQL)
* **Azure Cosmos DB**
* **Redis Cloud** (Pro tier)
* **AWS DynamoDB**

**Self-hosted databases:**

For containerized databases, use manual backup procedures: volume snapshots, native tools (`mongodump`, `pg_dump`, `mysqldump`), or scheduled scripts.

## Roadmap

<Info>Data plane integration, custom management actions, and automated backups are on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

<CardGroup>
  <Card title="Integrations" icon="puzzle-piece" href="/integrations">
    Full list of supported databases, cloud providers, and third-party services.
  </Card>

  <Card title="Working with Databases" icon="terminal" href="/prompting/working-with-databases">
    Prompting examples for common database operations.
  </Card>
</CardGroup>


# Multiple Environments
Source: https://docs.monk.io/features/environments

Separate staging, production, and dev deployments

## What It Does

Monk gives you isolated environments per workspace — staging, production, dev, or whatever you call them. Each one gets its own configuration and maps to a specific cluster. Your deployments stay separate even when they share the same code.

## Creating Environments

Tell Monk what you need:

```
/monk create staging and production environments
```

Monk sets up separate configs and asks which cluster each one should target.

## Building and Deploying

### Environment-Specific Builds

Monk tailors configuration per environment — variables, managed services, sizing. Just say which one:

```
/monk build for production
```

### Deploying by Name

```
/monk deploy to staging
```

Monk switches to the right cluster, builds only what that environment needs, and deploys it. You don't manage the wiring.

### Deploy to Multiple at Once

```
/monk deploy to staging and production
```

Monk handles them sequentially, each to its own cluster.

## Linking Environments to Clusters

Each environment maps to one cluster. You set that up at deploy time or in the Clusters panel.

**At deploy time**, Monk asks if there's no link yet:

```
/monk deploy to staging
```

Monk: "Which cluster should I use for staging environment?"

**In the Clusters panel**, you can see and manage all environment-cluster associations visually.

Multiple environments can share a cluster (separated by tags), or each can have its own. Changing a link doesn't affect existing deployments.

## Use Cases

**Dev / Staging / Production pipeline:**

```
You: Create dev, staging, and prod environments
You: Link dev to my-local-cluster
You: Link staging to my-digitalocean-cluster
You: Link prod to my-aws-cluster
You: Deploy to all environments
```

Each environment deploys to its designated infrastructure.

**Feature branches:**

```
You: Create feature-auth environment
You: Deploy feature-auth to my-test-cluster
```

Test in isolation, then promote to staging when it's ready.

**Multi-region deployments:**

```
You: Create us-prod and eu-prod environments
You: Link us-prod to my-aws-us-cluster
You: Link eu-prod to my-aws-eu-cluster
```

Same app, multiple regions, separate environments.

## Managing Environments

**List them:**

```
You: What environments do I have?
```

**Check a cluster link:**

```
You: Which cluster is linked to staging?
```

**Delete one:**

```
You: Delete the dev environment
```

You can also manage everything visually in the **Clusters panel**.

## Team Environments

In an org context, environments can target org clusters. This keeps deployments consistent across team members, even when each person defines environments in their own workspace. Secrets are environment-scoped too — staging and production get different values.

> See [Team Collaboration](/features/team-collaboration) for details on shared clusters and secrets.

## Go Deeper

<CardGroup>
  <Card title="Capsules" icon="flask" href="/features/capsules">
    Automatic per-branch preview environments — every push gets its own cluster.
  </Card>

  <Card title="Configuration & Wiring" icon="sliders" href="/features/configuration-and-wiring">
    How Monk handles environment-specific config, variables, and secrets.
  </Card>

  <Card title="Cloud Infrastructure" icon="cloud" href="/features/cloud-provisioning">
    Multi-cluster setup and cloud provider management.
  </Card>
</CardGroup>


# Essential Services
Source: https://docs.monk.io/features/essential-services

Message queues, caches, storage, and any other service Monk can spin up

## What It Does

Your app doesn't just need a database. It needs message queues, object storage, caches, API gateways, and more.

Monk detects these needs during [code analysis](/features/code-analysis), then provisions and configures them automatically. You pick how they're deployed: self-hosted, cloud managed, or third-party. Monk handles provisioning, connection strings, and wiring.

## How It Works

### Automatic Service Detection

During code analysis, Monk identifies your infrastructure requirements:

* Message queue usage (RabbitMQ, Kafka, SQS clients)
* Object storage references (S3 SDK, MinIO client, file uploads)
* Caching layers (Redis, Memcached)
* API gateway and web server needs (Kong, Nginx, Apache)

It figures out what you need before you configure anything.

### Deployment Options

You've got three choices for each service.

#### Option 1: Self-Hosted in Containers

Best for development, staging, and full control. Services run in containers on your infrastructure. Monk handles setup, persistence, and configuration. Quick to spin up, easy to tear down.

#### Option 2: Cloud Provider Managed

Best for production. Uses your cloud provider's managed services (AWS S3/SQS, GCP Cloud Storage/Pub-Sub, Azure Blob/Service Bus). You provide credentials, Monk provisions and configures everything.

#### Option 3: Third-Party Managed

Best for specialized needs or multi-cloud setups. Uses providers like Cloudflare R2, Redis Cloud, or other SaaS platforms. Often have free tiers or pay-per-use pricing.

#### Progression Examples

**Object Storage:**

* Start with MinIO (containerized) for development
* Move to DigitalOcean Spaces or AWS S3 for production
* Scale to Cloudflare R2 for global CDN + storage

**Message Queues:**

* Start with RabbitMQ (containerized) for development
* Move to AWS SQS or managed RabbitMQ for production
* Scale to Apache Kafka for high-throughput event streaming

**Caching:**

* Start with Redis (containerized) for development
* Move to AWS ElastiCache or managed Redis for production
* Scale to Redis Cloud for global, multi-region caching

Monk recommends the best option based on your stage, scale, and requirements.

### Supported Services

Monk supports 50+ services out of the box. Here are the major categories:

* **Message Queues & Brokers** -- RabbitMQ, Apache Kafka, AWS SQS
* **Object Storage** -- MinIO, AWS S3, Cloudflare R2
* **Caching** -- Redis, Memcached, Hazelcast
* **API & Gateway** -- Kong, Hasura GraphQL Engine, AWS API Gateway
* **Web Servers & Proxies** -- Nginx, Apache, HAProxy
* **Security & Secrets** -- HashiCorp Vault, Keycloak
* **Monitoring & Observability** -- Prometheus + Grafana, ELK Stack, Fluent Bit
* **DevOps & CI/CD** -- Jenkins, GitLab, SonarQube
* **Data Integration & ETL** -- Airbyte, Apache Airflow
* **Analytics & BI** -- Metabase, Apache Superset
* **AI/ML Serving** -- Ollama, TensorFlow

See [Integrations](/integrations) for the full list.

### Automatic Connection Management

Monk generates and manages connection strings and credentials automatically via [Configuration & Wiring](/features/configuration-and-wiring). This includes:

* Connection string generation (queue URLs, storage endpoints, cache URLs)
* Credential creation and secure storage
* Network configuration and authentication setup
* Service discovery registration

Switch between deployment options without code changes. Move from self-hosted MinIO to AWS S3, and Monk updates your app's storage configuration automatically. Your code using the S3 SDK keeps working without modification.

<Warning>
  Data migration between service providers isn't automated yet. When you switch from self-hosted to managed (or vice versa), Monk updates connection strings but doesn't transfer existing data. You'll need to migrate data manually for now.
</Warning>

### Service Configuration

Monk can configure service settings to match your requirements -- queue sizes, storage quotas, cache memory limits, rate limits, health checks, monitoring thresholds, and more. Tell Monk what you need. It understands service-specific parameters for each supported type.

<Info>Data migration, advanced monitoring, and custom management actions are on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

## Next Steps

<CardGroup>
  <Card title="Integrations" icon="puzzle-piece" href="/integrations">
    Browse the full catalog of 50+ supported services and providers.
  </Card>

  <Card title="Configuration & Wiring" icon="plug" href="/features/configuration-and-wiring">
    Learn how Monk manages connection strings and credentials.
  </Card>
</CardGroup>


# MCP Support
Source: https://docs.monk.io/features/mcp-support

How Monk works with Claude Code, Cursor, Codex, and other coding agents

## What Monk MCP Does

Monk exposes itself as an MCP server so coding agents can call Monk directly from the same project context.

That means you do not need to choose between your coding agent and Monk.

You can use:

* your coding agent for building and changing application code
* Monk for deployment, infrastructure, connected services, runtime operations, monitoring, scaling, and cost visibility

## Why This Matters

Most coding agents are strongest when working on source code. Monk is strongest when turning that source code into a running system.

Through MCP, your coding agent can delegate operational tasks to Monk without forcing you to:

* switch tools
* copy context between chats
* hand-edit agent config files
* leave unwanted configuration files behind in every repo

## How the Mechanism Works

The [Monk plugin](/getting-started/get-started) installs a local companion process, `monk-agent`, which serves the Monk MCP endpoint on `http://127.0.0.1:7419/mcp`.

The plugin registers this endpoint with your coding agent through the host's native plugin mechanism — Claude Code, Cursor, and Codex wire it up on install, and the Antigravity plugin writes a `monk` entry to `~/.gemini/config/mcp_config.json`. Nothing is written into your project repositories.

The host still decides whether Monk is visible and usable. Depending on the agent, you may need to approve tool usage in chat or complete a one-time MCP sign-in.

Any other MCP-capable agent can connect to the same local endpoint once `monk-agent` is running, though the plugin hosts above are the supported paths.

## What Other Agents Can Ask Monk To Do

Once connected through MCP, a coding agent can use Monk to:

* inspect the project and explain what infrastructure it needs
* deploy a service or full multi-service application
* provision databases, queues, caches, and third-party services
* configure networking, domains, TLS, and secure service-to-service wiring
* inspect logs, health, and runtime state
* scale workloads and optimize cost
* migrate workloads between clouds or hosting models

In short, the coding agent handles code work, and Monk handles operational work.

## Typical Workflow

1. Build or modify the application with your coding agent
2. Ask that agent to use Monk to analyze deployment needs
3. Let Monk provision services and deploy the stack
4. Ask Monk for logs, status, scaling, or cost follow-up

This creates a much smoother path from local development to production operations.

## How To Enable It

Install the Monk plugin in your coding agent — the MCP connection is set up automatically as part of the install. See [Install Monk](/getting-started/get-started).

## Related Pages

<Card title="Install Monk" icon="plug-circle-plus" href="/getting-started/get-started">
  Install the Monk plugin in your coding agent
</Card>

<Card title="Autonomous Deployment" icon="rocket" href="/features/autonomous-deployment">
  Let Monk handle the full deploy pipeline
</Card>


# Monitoring & Observability
Source: https://docs.monk.io/features/monitoring

Logs, shell access, and metrics from your coding agent

## What It Does

Monk gives you logs, shell access, metrics, and troubleshooting right in the chat. You ask questions in plain English. Monk pulls the answers from your running system.

That's it. No dashboards, no log aggregation setup, no query languages.

## How It Works

### System Understanding

Monk maintains a live picture of your entire deployment:

* Every service and its current state (running, stopped, restarting)
* Every container and what it's doing
* Every database connection and query load
* Every API integration and its status
* Resource usage per component (CPU, memory, disk, network)
* Relationships between all components

Ask Monk about your system:

```
/monk what's running right now?
```

### Live Log Streaming

View logs from any service in real time:

```
/monk show me logs from the API server
```

Monk streams live logs, pulls historical logs, and filters by time range, severity, or keywords. You can tail multiple services at once. Everything stays in the chat.

### Log Analysis

Don't want to read logs yourself? Let Monk do it:

```
/monk check the API server logs for errors
```

Monk reads the output, finds patterns, and suggests fixes.

### Shell Access

Get a shell into any container instantly:

```
/monk give me shell access to the API server
```

This isn't SSH. Monk opens a shell connection over its intra-cluster encrypted P2P network. No SSH keys to manage, no bastion hosts, no port forwarding. It works across all clouds because the connection runs through Monk's own mesh -- not through your cloud provider's networking.

### Resource Metrics

Track resource consumption across your stack:

```
/monk what's the resource usage?
```

Monk tracks CPU, memory, disk, and network for every service. It also surfaces application-level metrics: queue depth, connection pools, cache hit rates, database query times, slow queries, API response times, and webhook deliveries.

### Autonomous Troubleshooting

Something's wrong? Describe the problem:

```
/monk users are reporting slow page loads
```

Monk reads logs across all services, checks metrics and resource usage, examines workload state, correlates the data, and identifies the root cause. It suggests fixes -- and can apply them if you say the word.

Monk has full system context. It investigates across every component simultaneously.

## 24/7 Monitoring with Watcher

For continuous monitoring and Slack alerts, set up Watcher:

```
/monk set up watcher
```

Watcher monitors your cluster around the clock and sends AI-analyzed alerts when issues arise. Each alert includes a "Fix with Monk" button that opens your coding agent with full issue context.

> See [Watcher](/features/watcher) for setup and configuration details.

Available on Pro and Team plans.

## Observability Integrations

<Info>Integrations with Datadog, New Relic, Grafana Cloud, and other observability platforms are on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

## Go Deeper

<CardGroup>
  <Card title="Watcher" icon="eye" href="/features/watcher">
    24/7 autonomous monitoring with Slack alerts
  </Card>

  <Card title="Security" icon="shield" href="/features/security">
    How Monk secures shell access and cluster communication
  </Card>
</CardGroup>


# Multi-Cloud Support
Source: https://docs.monk.io/features/multi-cloud

Deploy across all major cloud providers

## What It Does

Monk deploys your app to any supported cloud provider. The configuration it generates from [code analysis](/features/code-analysis) is cloud-agnostic. You can split a single app across multiple clouds at the same time.

## How It Works

### Platform-Agnostic Configuration

When Monk analyzes your application, the resulting configuration works everywhere:

* Configuration deploys to AWS, GCP, Azure, DigitalOcean, or Hetzner
* Deploy to one cloud today, switch to another tomorrow
* No provider-specific code or configs required
* Monk handles platform-specific details automatically

### Split Across Multiple Clouds

Monk manages multiple cloud accounts and resources as one system. Your app can span providers.

**Example architecture:**

* Compute — DigitalOcean Droplets (affordable VMs)
* AI/ML — Azure OpenAI Service (GPT models)
* CDN — Cloudflare (global edge network)

Monk orchestrates all of this as a single deployment.

### Secure Cross-Cloud Networking

When your app spans multiple clouds, Monk handles networking automatically:

* All communications encrypted by default
* No VPN setup required
* No Tailscale configuration needed
* Works across clouds and datacenters
* Automatic network segmentation

See [Networking](/features/networking) for details on how cross-cloud communication works.

### Cloud Service Replacement

Monk finds equivalent services across cloud providers, subject to available [integrations](/integrations):

| Service Type       | AWS         | GCP                  | Azure           | DigitalOcean     |
| ------------------ | ----------- | -------------------- | --------------- | ---------------- |
| Object Storage     | S3          | Cloud Storage        | Blob Storage    | Spaces           |
| Managed PostgreSQL | RDS         | Cloud SQL            | Database        | Managed Database |
| Load Balancer      | ALB/NLB     | Cloud Load Balancing | Load Balancer   | Load Balancer    |
| Cache              | ElastiCache | Memorystore          | Cache for Redis | DO Valkey        |

### On-Premises + Cloud Hybrid

Monk can run your system across on-premises infrastructure and cloud.

**Hybrid scenarios:**

* Sensitive data stays on-prem, processing in cloud
* Development/staging on-prem, production in cloud
* Legacy systems on-prem, new services in cloud
* Burst to cloud for peak loads

**Requirements:**

* Manual setup for on-premises machines (network access, orchestrator installation)
* Monk manages hybrid infrastructure as one system
* Encrypted networking between on-prem and cloud

<Info>
  **On-premises support:** See [Getting Help](/getting-help) for guidance on
  hybrid cloud + on-prem deployments. Manual setup is required for on-premises
  machines, but once configured, Monk manages everything as a unified system.
</Info>

### Migration

Need to switch cloud providers? Monk handles it. Tell it where you want to go, and it provisions, migrates, and cuts over.

See [Workload Migration](/features/workload-migration) for the full process.

## Supported Providers

**Major Cloud Providers:**

* [AWS](https://aws.amazon.com/)
* [Google Cloud Platform](https://cloud.google.com/)
* [Microsoft Azure](https://azure.microsoft.com/)
* [DigitalOcean](https://www.digitalocean.com/)
* [Hetzner](https://www.hetzner.com/cloud)

**Specialized Hosting:**

* [Netlify](https://www.netlify.com/) — Frontend hosting
* [Vercel](https://vercel.com/) — Frontend hosting
* [Cloudflare](https://www.cloudflare.com/) — CDN, Workers, R2 storage

**Managed Services:**

* [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) — Managed MongoDB
* [Redis Cloud](https://redis.com/cloud/) — Managed Redis
* [Neon](https://neon.tech/) — Serverless PostgreSQL
* And more via [integrations](/integrations)

## Next Steps

<CardGroup>
  <Card title="Cloud Infrastructure" icon="server" href="/features/cloud-provisioning">
    How Monk provisions and manages cloud resources.
  </Card>

  <Card title="Workload Migration" icon="arrow-right-arrow-left" href="/features/workload-migration">
    Move between clouds with zero downtime.
  </Card>
</CardGroup>


# Networking
Source: https://docs.monk.io/features/networking

Encrypted overlay network, dynamic routing, and zero-config connectivity

## What It Does

Monk creates an encrypted overlay network that spans all your infrastructure — across clouds, regions, and on-premises. Every service talks to every other service securely, no matter where it runs.

**Zero configuration required.** Monk derives all networking from your app's [connection graph](/features/configuration-and-wiring) and configures routing, firewalls, and load balancing automatically.

## How It Works

### Encrypted Overlay Network

Monk spans an encrypted overlay network between every VM in your system, regardless of location.

**Network coverage:**

* Single cloud, single region
* Single cloud, multi-region
* Multi-cloud (AWS + GCP + Azure + DigitalOcean + Hetzner)
* Cloud + on-premises (manual setup required)

**Encryption by default:**

* All inter-service communication encrypted automatically
* No VPN setup required
* No Tailscale or WireGuard configuration needed
* Works transparently across cloud provider boundaries

**Example:**
Your API server on AWS us-east-1 can securely reach:

* PostgreSQL on GCP europe-west1
* Redis on DigitalOcean nyc1
* An on-premises legacy system in your datacenter

All connections are encrypted and routed through the overlay network automatically.

### Dynamic Routing & Firewall Configuration

Monk configures routing and firewalls dynamically at every level of your infrastructure.

**Configuration levels:**

* **Container level** - Network policies between containers
* **Machine level** - Host firewall rules
* **Security group level** - Cloud provider security groups
* **VPC level** - Network ACLs and routing tables

**All derived from the connection graph:**

Monk reads your app's [Configuration & Wiring](/features/configuration-and-wiring) and figures out which services need to talk to each other:

```
Your application:
  Frontend → API Server → Database
  API Server → Redis
  Worker → Redis
  Worker → External API (Stripe)
```

**Monk configures:**

* Frontend can reach API Server (public endpoint)
* API Server can reach Database (internal, encrypted)
* API Server can reach Redis (internal, encrypted)
* Worker can reach Redis (internal, encrypted)
* Worker can reach Stripe API (public, via internet gateway)
* **Nothing else can communicate** — all other paths blocked by default

**Firewall rules are managed automatically:**

* Only required ports open to the internet
* Internal services stay on the private network
* Unused ports blocked by default
* Rules update dynamically as services scale

### Load Balancing

Monk handles load balancing at multiple levels.

**Cloud-managed load balancers:**

* Uses AWS ALB, GCP Load Balancing, or Azure Load Balancer as appropriate
* Automatically provisioned for public-facing services
* Health checks configured automatically
* SSL/TLS termination when using custom domains

**Internal load balancing:**

* Built-in load balancing between service replicas
* Automatic service discovery — no manual endpoint configuration
* Requests distributed across healthy instances
* Failed instances removed from rotation automatically

**Zero-downtime deployments:**

* Monk orchestrates rolling updates when containers change
* New version starts while the old version still serves traffic
* Traffic switches only after health checks pass
* Old version shuts down gracefully after traffic drains

### Temporary Domains with TLS

Every machine managed by Monk gets a free temporary domain.

**Format:** `<machine-id>.runs.onmonk.io`

**Features:**

* Automatically assigned to each VM
* Free TLS certificates included
* Only active if a workload explicitly opens a port to the internet
* Useful for development, testing, and temporary deployments

**Use cases:**

* Test API endpoints before configuring a custom domain
* Share staging environment URLs with your team
* Quick demos without DNS configuration
* Development environments with HTTPS

<Info>
  These temporary domains are assigned to all machines but only serve traffic if
  your application opens a port publicly. Internal services (databases, workers,
  etc.) don't expose anything via these domains.
</Info>

### Custom Domains with Cloudflare Integration

You can bring your own domain. Monk integrates with Cloudflare to manage DNS and domain setup automatically.

<Warning>Custom domains currently require your domain to be managed by Cloudflare. Support for additional DNS providers is on the roadmap.</Warning>

**Bring your own domain:**

* Use your domain name (e.g., `api.yourapp.com`, `www.yourapp.com`)
* Monk manages your Cloudflare DNS zone
* Automatic DNS record creation and updates
* Free SSL/TLS certificates via Cloudflare

**What Monk handles:**

* DNS zone configuration
* A/AAAA records pointing to your services
* CNAME records for aliases
* SSL/TLS certificate provisioning
* DNS updates when infrastructure changes

**Setup:**

1. Have your domain registered with Cloudflare (or transfer it)
2. Provide Cloudflare API credentials to Monk
3. Tell Monk which domain to use for your app
4. Monk configures DNS and connects your domain to your deployment

When your infrastructure changes (scaling, migration, etc.), Monk updates DNS records automatically.

### Cloud Network Provisioning

Monk provisions cloud networking resources automatically.

**What Monk creates:**

* **VPCs** - Isolated networks for your app
* **Subnets** - Public and private subnets as needed
* **Internet gateways** - For public-facing services
* **NAT gateways** - For private services that need internet access (updates, APIs)
* **Route tables** - Routing between subnets and the internet
* **Security groups** - Firewall rules at instance level
* **Network ACLs** - Additional firewall layer at subnet level

All configured based on your app's architecture. No manual network engineering required.

### API Gateway Integration

Monk uses cloud-managed API gateways when they make sense.

**Supported:**

* AWS API Gateway
* GCP API Gateway
* Azure API Management

**Benefits:**

* Centralized API management
* Rate limiting and throttling
* Request/response transformation
* API versioning support

Monk provisions and configures API gateways when your architecture benefits from them — for example, serverless functions or microservices with many endpoints.

## Built-in Ingress Controller with ModSecurity

Monk's orchestrator includes a built-in ingress controller with ModSecurity WAF (Web Application Firewall) enabled by default on all clusters:

* Automatic WAF protection against common web attacks
* DDoS mitigation at the application layer
* Request filtering and rate limiting
* Zero configuration required

## Related Features

<CardGroup>
  <Card title="Configuration & Wiring" icon="diagram-project" href="/features/configuration-and-wiring">
    The connection graph that drives all networking decisions.
  </Card>

  <Card title="Security" icon="shield-halved" href="/features/security">
    Encryption, firewalls, and access control across your infrastructure.
  </Card>
</CardGroup>


# Project Organization
Source: https://docs.monk.io/features/project-organization

Cluster assignment, team secrets, and environment-scoped access control

## The Short Version

You've got environments. You've got clusters. You've got teammates who shouldn't touch production. Project Organization is where those three things connect.

No config files. No manual wiring. You tell Monk the rules, and it enforces them.

## Cluster Assignment

Every environment maps to one cluster. That's the boundary.

```
/monk link staging to my-digitalocean-cluster
/monk link prod to my-aws-cluster
```

Multiple environments can share a cluster -- Monk separates them with tags. Or give each environment its own cluster. Either way, you set it once and deployments route automatically.

Change a link anytime. Existing deployments aren't affected.

## Team Secrets

Secrets are environment-scoped. Staging gets its own `DATABASE_URL`. Production gets a different one. They don't leak across boundaries.

```
/monk add DATABASE_URL as a team secret for staging
```

Team secrets require two things:

* An organization context
* An environment linked to an org cluster

Once that's in place, every org member with the right permissions sees the same secrets for that environment. Monk stores them on the cluster.

## Environment-Scoped RBAC

You can lock down access per environment. A junior dev gets deploy rights to staging. Production stays off-limits.

Permissions use path-based scoping:

* `/environments/staging/templates/**` -- staging templates only
* `/environments/*/secrets/**` -- secrets across all environments

That's it. Define the role, assign it, and Monk handles enforcement.

```
/monk create a role called staging-deployer with deploy access to /environments/staging/templates/**
```

## Putting It Together

A typical setup looks like this:

```
/monk link dev to my-local-cluster
/monk link staging to my-digitalocean-cluster
/monk link prod to my-aws-cluster
```

Dev, staging, and prod each hit different infrastructure. Secrets stay isolated per environment. RBAC controls who can touch what. You manage the whole thing in chat or the Clusters panel.

<CardGroup>
  <Card title="Multiple Environments" icon="layer-group" href="/features/environments">
    Creating, deploying, and managing environment lifecycles.
  </Card>

  <Card title="Access Control & Security" icon="lock" href="/features/access-control">
    RBAC roles, permissions, and audit logging.
  </Card>
</CardGroup>


# Scaling
Source: https://docs.monk.io/features/scaling

Scale resources with natural language

## What It Does

Monk scales your entire system — workloads and infrastructure. An algorithmic autoscaler handles workload scaling automatically. You tell Monk to scale infrastructure with plain language. That's it.

<img alt="Cloud Scaling" />

## How It Works

### Algorithmic Workload Autoscaling

Monk's autoscaler manages your [containerized workloads](/features/containerization) without you lifting a finger.

**What it handles:**

* Horizontal scaling — adds or removes container replicas based on load
* Resource-based scaling — scales on CPU and memory utilization
* Automatic load balancing — distributes traffic across scaled replicas

**Example:**
Your API server starts with 2 replicas. Traffic spikes during peak hours. The autoscaler spins up replicas — 3, 4, 5. Traffic drops. It scales back down. You don't do anything.

The autoscaler runs continuously in the background as part of orchestration. No manual intervention required as long as autoscaling rules exist in your Monk configuration.

### Infrastructure Scaling

Beyond workloads, Monk scales the underlying infrastructure itself.

**What Monk can scale:**

* Virtual machines — add or remove VMs from your deployment
* Instance sizing — change VM sizes (e.g., 2GB to 4GB RAM)
* Service settings — adjust database connection pools, cache sizes, worker counts
* Storage — increase disk size for databases and persistent volumes

**How to trigger it:**

Tell Monk what you need via chat in your [coding agent](/getting-started/get-started):

```
You: Add 2 more machines to the API cluster
```

```
You: Scale the database instance up to 8GB RAM
```

```
You: Increase the worker count to 5
```

```
You: Remove the extra VMs, traffic is back to normal
```

Monk provisions or deprovisions resources using your [cloud provider](/features/cloud-provisioning) accounts. No Terraform. No console clicking.

### Intelligent Scaling Decisions

When you request infrastructure changes, Monk doesn't just execute blindly.

**Instance sizing:**

* Recommends appropriate VM sizes based on current usage
* Suggests cost-effective alternatives
* Warns about over-provisioning

**Placement:**

* Places new VMs in optimal regions
* Co-locates with related services for low latency
* Balances across availability zones when needed

**Cost awareness:**

* Estimates cost impact before you confirm
* Suggests cheaper alternatives when possible
* See [Cost Tracking](/features/cost-tracking) for real-time cost monitoring

**Confirmation before changes:**

```
You: Add more machines to handle this traffic spike

Monk: Current setup: 2x t3.medium instances (4 vCPU, 8GB RAM)
      Recommendation: Add 2x t3.medium instances
      New total: 4 instances
      Cost increase: ~$50/month

      Proceed?

You: Yes
```

You stay in control. Monk does the heavy lifting.

### Zero-Downtime Scaling

Whether it's workload autoscaling or infrastructure scaling, Monk ensures zero downtime.

**Workload scaling:**

* New replicas added before old ones removed
* Health checks before traffic routing
* Graceful shutdown of scaled-down replicas

**Infrastructure scaling:**

* New VMs provisioned and containers deployed before traffic shifts
* [Load balancers](/features/networking) updated automatically
* Old VMs drained before shutdown

<Info>Proactive AI-driven scaling — autonomous 24/7 scaling, predictive patterns, cost optimization — is on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

<CardGroup>
  <Card title="Cloud Infrastructure" icon="cloud" href="/features/cloud-provisioning">
    How Monk provisions and manages your VMs
  </Card>

  <Card title="Cost Tracking" icon="dollar-sign" href="/features/cost-tracking">
    Real-time cost impact of scaling decisions
  </Card>
</CardGroup>


# Security
Source: https://docs.monk.io/features/security

Agentic safety and runtime security built-in

## What It Does

Monk handles security at two levels:

1. **Agentic Security** -- keeps the AI agent itself safe to use
2. **Runtime Security** -- protects your deployed apps and infrastructure

Both are on by default. You don't configure anything.

## Agentic Security

Monk is an autonomous agent with real privileges. It provisions infrastructure, changes configs, and manages production. That demands safety mechanisms you won't find in typical AI tools.

### Secrets Never Reach the LLM

Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS. They are never sent to Monk servers and never exposed to the LLM.

How it works:

* Secrets are handled by deterministic tooling, not AI inference
* The LLM only knows a secret exists -- it never sees the value
* Secret values are never generated by the LLM

```
Typical AI agent:
  LLM sees: DATABASE_URL=postgresql://user:password123@host:5432/db

Monk:
  LLM sees: DATABASE_URL=[SECRET:postgres_connection]
  Tooling handles: postgresql://user:password123@host:5432/db
```

### Secrets Never Leave Your Infrastructure

Where secrets live:

* **Workspace/user scope** -- local secret storage in your OS keychain, encrypted at rest (macOS Keychain, Windows Credential Manager, Linux Secret Service)
* **Team scope** -- on your org cluster, envelope-encrypted with your cloud provider's KMS
* **Never** -- Monk servers

**BYO-KMS:** Team secrets use envelope encryption with your provider's key management service -- AWS KMS, GCP Cloud KMS, Azure Key Vault, or DigitalOcean managed encryption keys. Each read uses a fresh data key. Rotation is automatic.

This is part of the BYOI (Bring Your Own Infrastructure) model. Everything runs on your infrastructure, including secret management.

### Destructive Actions Require Approval

Monk can't silently destroy things. Destructive actions are gated by tooling, not by AI judgment.

When Monk needs to delete resources, it tells you exactly what's affected. You approve or reject. The approval flow is handled by tooling -- the AI can't be manipulated to bypass it.

Protected actions include:

* Deleting infrastructure resources
* Removing databases or storage
* Tearing down production environments
* Reducing security group access

```
Monk: To complete this task, I need to delete the staging environment.
      This includes:
      - 3 VMs (total cost: $45/month)
      - PostgreSQL database (last backup: 2 hours ago)
      - 50GB storage

    [YES] [NO]

[User must explicitly click [YES] - answer not processed by AI]
```

### Blast Radius Awareness

Monk understands what depends on what. Before making changes, it knows:

* Which services break if you delete a database
* Which users see downtime if you change a domain
* Which services are affected by a security group change

This isn't guesswork. Monk tracks your resource graph and computes impact from it.

### Restricted Capabilities

Monk operates within hard boundaries.

**What Monk CAN do:**

* Generate and edit Containerfiles, Monk configurations
* Provision cloud resources via provider APIs
* Configure services via orchestrator APIs
* Read code in your open workspace

**What Monk CANNOT do:**

* Execute arbitrary CLI commands on your machine
* Make arbitrary API calls outside its tooling
* Access files outside your open workspace
* Bypass approval requirements for destructive actions

Monk does not edit source code without your explicit approval. See [Source Code Editing](/features/code-editing) for how that works.

### Deterministic Validation

Every LLM response is validated before execution:

1. LLM generates a plan and tool calls
2. Deterministic code validates the plan
3. Validation checks parameters, operation safety, and resource types
4. Only after validation do actions execute

This catches malformed API calls, invalid configs, and hallucinated operations before they touch anything.

## Runtime Security

Once your app is deployed, Monk locks it down automatically.

### Secret Storage and Management

Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS. They are never sent to Monk servers and never exposed to the LLM.

At runtime:

* Secrets are injected into containers at runtime, never baked into images
* Team secrets are environment-scoped -- staging and production get separate values
* Secrets are never logged or exposed in configurations

See [Configuration & Wiring](/features/configuration-and-wiring) for how secrets flow through your application.

### Encrypted Networking and Segmentation

All service-to-service communication is encrypted by default. Monk's overlay network spans all your infrastructure -- no manual VPN or WireGuard setup.

Traffic is segmented automatically:

* Services only communicate if your connection graph says they should
* Lateral movement is prevented by default
* See [Networking](/features/networking) for the full picture

### VM and Access Control

VMs don't expose SSH ports. You manage infrastructure through Monk's orchestrator API from your coding agent. All management actions are authenticated and encrypted.

### Automatic Firewall Management

Only the ports you need are open:

* Public-facing services expose application ports (80, 443)
* Internal services have no public ports
* Inter-service communication stays on the private network
* Everything else is blocked

Firewall rules update automatically as services scale. New instances get correct rules immediately. Removed instances are cleaned up.

### Container Security

When Monk generates Containerfiles (see [Containerization](/features/containerization)), it follows security best practices:

* Non-root users in containers
* Minimal base images (Alpine, distroless)
* No unnecessary packages
* Multi-stage builds to minimize attack surface

### Automatic IP Whitelisting

When your containers connect to external services, Monk handles IP whitelisting for you.

Example: your container connects to MongoDB Atlas. Monk knows the VM's IP, calls the Atlas API to whitelist it, and updates the whitelist automatically if the container moves. Same for Redis Cloud, managed databases, and any service that supports IP-based access control.

### Airgapped and Enclosed Deployment

**Enclosed VPC:** Run entirely within your VPC with no internet access required (except for external APIs your app needs). Manual setup required.

**Airgapped on-premises:** Run completely disconnected from the internet with all management over your local network. Manual setup required.

See [Getting Help](/getting-help) for guidance on airgapped deployments.

### Ingress WAF

Monk's ingress controller includes ModSecurity WAF on all clusters by default. See [Networking](/features/networking) for details.

<CardGroup>
  <Card title="Networking" icon="network-wired" href="/features/networking">
    Encrypted overlay network, firewalls, and ingress configuration.
  </Card>

  <Card title="Configuration & Wiring" icon="plug" href="/features/configuration-and-wiring">
    Secret management, injection, and environment wiring.
  </Card>
</CardGroup>


# Package Ecosystem
Source: https://docs.monk.io/features/service-templates

Pre-built, battle-tested packages — automatically adapted to your stack

## What It Does

Monk's package ecosystem gives you hundreds of pre-built packages for databases, services, APIs, and infrastructure. The [orchestrator](/features/containerization) uses them to deploy resources. Monk agents use them to understand and manage everything about those resources.

## How It Works

### What Packages Contain

Monk packages are comprehensive definitions. They carry everything needed to deploy and manage a service.

**Deployable workloads:**

* Container-based services (databases, web servers, message queues, etc.)
* Configuration for running the service
* Health checks and lifecycle management

**Infrastructure definitions:**

* Cloud resource requirements (VMs, storage, networking)
* Infrastructure blueprints for optimal deployment
* Multi-cloud compatibility specifications

**Custom resource definitions:**

* Interfaces for managing virtually any resource
* Integration points for third-party services
* Lifecycle hooks and operational patterns

**Extensions for Monk agents:**

* Service-specific behaviors and actions
* Monitoring and troubleshooting capabilities
* Cost estimation interfaces

### Composable by Design

Packages compose other packages. That's how you build systems without reinventing anything.

A web application package might compose a PostgreSQL database package, a Redis cache package, and an Nginx web server package. Each sub-package brings its own capabilities and management logic. The composed system works as a unified whole.

You don't copy-paste. You compose.

### Extensible Without Duplication

Want a custom PostgreSQL configuration? Override the base package. Only define what's different. Inherit everything else — container runtime setup, health checks, the works.

Less repeated code. More succinct definitions. Easier to maintain.

```yaml theme={null}
# Override just what you need:
namespace: my-app

postgresql:
  inherits: monk-postgresql # Base PostgreSQL package
  variables:
    max-connections: 200
    shared-buffers: "2GB"
```

### Programmable with Scripting

Packages can contain arbitrary scripting for complex behaviors:

* **ArrowScript** — Monk's declarative scripting language for defining service behaviors, health checks, and operational patterns inside packages.
* **TypeScript framework** — For full customization and complex logic
* **Custom operation patterns** — Entirely custom workflows and actions

Use these for database backup automation, custom health checks, complex deployment orchestration, or service-specific management operations.

### Your Code Becomes Packages

When Monk performs [code analysis](/features/code-analysis) on your application:

1. Monk packages up your services — each component becomes a package definition
2. It composes them with existing packages — your services combined with databases, caches, etc.
3. You review the resulting definition — see the full packaged system

Your application gets treated the same way as pre-built packages. Same capabilities for deployment, scaling, and management.

### Content-Addressed and Immutable

Security is built into the package system.

* **Content-addressed** — packages identified by cryptographic hash of their contents
* **Immutable** — once published, a package can't be changed
* **Guarded against supply chain attacks** — tampering is prevented by design

Packages are currently permissioned and vetted by the Monk team. Quality standards are enforced before publication, and community contributions are reviewed and tested.

### The Ecosystem

Hundreds of packages. Databases like PostgreSQL, MySQL, MongoDB, Redis. Message queues like Kafka and RabbitMQ. Monitoring stacks, DevOps tools, CMS platforms, AI/ML runtimes, and more.

See [Integrations](/integrations) for the full list.

### Open Source Contributions

Many Monk packages are open source on GitHub at [monk-io](https://github.com/monk-io). You can review package definitions, submit improvements, contribute new packages, or learn from existing implementations.

Popular repositories include [monk-metabase](https://github.com/monk-io/monk-metabase), [monk-prometheus-grafana](https://github.com/monk-io/monk-prometheus-grafana), [monk-ollama](https://github.com/monk-io/monk-ollama), and 100+ more.

<Info>Private packages for teams — team-specific repositories, version control, access control — are on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

<CardGroup>
  <Card title="Containerization & Orchestration" icon="cubes" href="/features/containerization">
    How the orchestrator uses packages to deploy your stack.
  </Card>

  <Card title="Code Analysis" icon="magnifying-glass-code" href="/features/code-analysis">
    How Monk turns your code into packages.
  </Card>
</CardGroup>


# Slack Integration
Source: https://docs.monk.io/features/slack

Manage infrastructure from Slack — respond to questions, approve changes, and get alerts without opening your coding agent

## What It Does

Connect Monk to your Slack workspace and it sends you questions, configuration forms, and task completion summaries directly in Slack. You respond right there — no need to open your coding agent.

Monk asks in both the chat and Slack at the same time. Whichever one you respond on first wins — the other is cancelled automatically. When a task finishes, you get a summary in Slack with suggested next steps you can trigger without switching back to your agent.

There are two Slack features:

* **Remote Control** — two-way interactive prompts for answering questions, filling out forms, approving changes, and following up on completed tasks from Slack
* **Watcher Alerts** — one-way monitoring notifications with AI-powered diagnosis and a Fix with Monk button

Available on Pro and Team plans.

## Connect Slack

<Steps>
  <Step title="Ask Monk to connect Slack">
    In your coding agent:

    ```
    /monk connect Slack
    ```
  </Step>

  <Step title="Authorize in Slack">
    A browser window opens where you authorize the Monk app in your Slack workspace. You need permission to install apps in the workspace.
  </Step>

  <Step title="Pick a channel">
    Back in the chat, Monk shows a list of your Slack channels and DMs. Pick where you want to receive messages. You can also send to a DM with yourself for a personal notification channel.
  </Step>
</Steps>

That's it. Monk confirms the connected channel, and you can check the connection state at any time by asking Monk for Slack status.

## Remote Control

Once Slack is connected, Monk sends interactive messages to your Slack channel whenever it needs your input — during deployments, configuration changes, scaling, credential requests, and more.

### What you can do from Slack

**Answer questions** — When Monk needs a decision ("Continue deployment to production?", "Which region?"), you get a Slack message with buttons or a text input. Tap a button or type your answer.

**Fill out forms** — Configuration forms (cluster settings, watcher thresholds, service parameters) appear as interactive Slack forms. Fill them out and submit without switching back to your agent.

**Approve file changes** — When Monk's code editor wants to modify files, you get an approval request in Slack listing the affected files and operations. Approve or reject with a reason.

**Provide credentials** — When Monk needs cloud credentials, it notifies you in Slack. The actual credential entry happens securely on your machine, but the notification means you know to check in when you're ready.

**See task results** — When Monk finishes a build, deployment, cluster operation, or other long-running task, you get a summary of what was done along with suggested next steps as clickable buttons. Tap a button to trigger the next action directly from Slack.

### Task completion notifications

When Monk finishes a task that involved a build, deployment, cluster operation, CI/CD setup, or other significant work, it sends a completion summary to Slack. The notification includes Monk's summary of what was accomplished and, when available, action buttons for common follow-up steps like opening the app, checking logs, or deploying.

Clicking an action button sends that prompt to Monk as a new message, and the response comes back to Slack — so you can go through an entire build-deploy-verify workflow from Slack without being at your computer. Each conversation's messages are grouped into a Slack thread, with the chat title shown at the top for easy identification.

### How it works

Monk asks on all available interfaces simultaneously — the chat and Slack. The first response wins. If you answer in Slack, the chat prompt is dismissed. If you answer in the chat, the Slack message is updated to show it was handled.

This means you can start a long-running operation, close your laptop, and handle the next decision from your phone when the Slack notification arrives.

### Example flow

1. You tell Monk to deploy your project and close your laptop
2. Monk provisions infrastructure, builds containers, and hits a decision point — "The deployment needs a database. Set up PostgreSQL?"
3. A Slack message arrives on your phone with **Yes** and **No** buttons
4. You tap **Yes**
5. Monk finishes deploying and sends a summary to Slack: "Deployed to production. All 3 workloads healthy." with buttons like **Open the app** and **Check logs**
6. You tap **Check logs** and the log output appears in Slack

## Watcher Alerts

[Watcher](/features/watcher) monitors your cluster 24/7 and sends one-way alert notifications to Slack when something goes wrong — crashes, CPU spikes, disk pressure, health check failures.

Watcher alerts use a separate Slack webhook (not the relay connection). During [Watcher setup](/prompting/watcher-setup), Monk offers to configure Slack alerts. If you accept, it opens a quick OAuth flow where you authorize an Incoming Webhook and pick a channel. Monk handles the entire setup — no manual webhook URLs needed.

Each alert includes:

* AI-powered diagnosis explaining what happened and why
* Severity level and affected service
* A **Fix with Monk** button that opens your coding agent with full context

See [Watcher](/features/watcher) for configuration options and alert format details.

## Managing the Connection

### Change channel

Ask Monk to change the Slack channel and pick a different one from the list.

### Disconnect

Ask Monk to disconnect Slack. This clears the connection on your side but does not uninstall the Monk app from your Slack workspace.

### Reconnect

If the connection drops (network issues, restarts), Monk reconnects automatically. You can also ask Monk to reconnect Slack.

### Connection status

Ask Monk for Slack status at any time to see whether the connection is active.

## FAQ

<Accordion title="Do I need Slack connected for Monk to work?">
  No. Slack is optional. Without it, Monk asks all questions in the chat. Slack just gives you a second interface so you can respond when you're away from your computer.
</Accordion>

<Accordion title="Can multiple people respond to the same question?">
  The first response wins. If someone answers in Slack and someone else answers in the chat, whichever comes first is used. The other is cancelled.
</Accordion>

<Accordion title="Is the Watcher webhook the same as the remote control connection?">
  No. Remote control uses a persistent WebSocket connection through the Monk relay service. Watcher alerts use a standard Slack Incoming Webhook. They're configured separately and can go to different channels.
</Accordion>

<Accordion title="What Slack permissions does the Monk app need?">
  The app needs permission to post messages and read channel lists in your workspace. It uses Slack's Socket Mode — no public URLs or firewall changes needed on your side.
</Accordion>

<CardGroup>
  <Card title="Watcher" icon="radar" href="/features/watcher">
    24/7 cluster monitoring with AI-powered Slack alerts
  </Card>

  <Card title="Watcher setup guide" icon="bell" href="/prompting/watcher-setup">
    Step-by-step setup including Slack alert configuration
  </Card>
</CardGroup>


# Team Analytics & Reporting
Source: https://docs.monk.io/features/team-analytics

Usage metrics and cost allocation

<Info>Team Analytics is on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

## What It Does

You'll get a clear picture of who's deploying what, how often, and what it costs. No spreadsheets, no guesswork.

## Planned Capabilities

**Usage Metrics** — Deployment frequency, success/failure rates, and average deploy time per team member and project.

**Cost Allocation** — Breakdowns by project, team, and environment. Per-developer resource usage. Trends and budget alerts.

**Performance Tracking** — Error rates, debugging time, infrastructure metrics, and bottleneck identification.

**Custom Reporting** — Filter by project, environment, or team member. Pick a time range. Export when you need to.

<CardGroup>
  <Card title="Cost Tracking" icon="dollar-sign" href="/features/cost-tracking">
    Real-time infrastructure costs, available now.
  </Card>

  <Card title="Access Control" icon="lock" href="/features/access-control">
    Audit logs give you activity data today.
  </Card>
</CardGroup>


# Team Collaboration
Source: https://docs.monk.io/features/team-collaboration

Shared workspaces and collaborative infrastructure management

## What It Does

Team Collaboration lets your team share infrastructure under one organization. Invite members, assign roles, link clusters, share secrets, control access with RBAC. That's it.

Organization and cluster management live in the [Monk dashboard](https://monk.io/dashboard). Day-to-day ops, secrets, and RBAC work through chat.

## How to Create an Organization

<Steps>
  <Step title="Open the Monk Dashboard">
    Go to [monk.io/dashboard](https://monk.io/dashboard) and sign in.
  </Step>

  <Step title="Open the Account Dropdown">
    In the Account section, next to Personal, click the drop-down icon.
  </Step>

  <Step title="Select Create a New Organization">
    A window titled Select Monk Plan/Context appears. Pick Create a New Organization.
  </Step>

  <Step title="Name Your Organization">
    Type a name and press Enter.
  </Step>

  <Step title="Configure Seats">
    You'll be redirected to monk.io. Choose the number of seats, then click Continue to Checkout.
  </Step>

  <Step title="Complete Checkout">
    Purchase your subscription to finalize the organization.
  </Step>

  <Step title="Return to the Dashboard">
    After checkout, you're redirected back. Your organization is ready.
  </Step>
</Steps>

<Info>
  Billing is per-seat. The monthly cost adjusts as you add or remove seats.
</Info>

## How to Access

**Organization panel:** Open the [Monk dashboard](https://monk.io/dashboard) and click the org/team button.

**Clusters panel:** Open the [Monk dashboard](https://monk.io/dashboard) and click the clusters button.

<img alt="Monk Team Features Management" />

## How It Works

### Managing Organizations

The Organization panel shows your org overview (plan, tokens, seats), members, pending invites, RBAC roles, cluster policies, environments, projects, and activity logs. Use the org selector at the top to switch between personal and organization contexts.

### Inviting Team Members

<Steps>
  <Step title="Open Organization Management">
    Click the Manage button under the Account section.
  </Step>

  <Step title="Send an Invite">
    In the Organization Management panel, go to the Invite section. Enter the user's email and click Invite.

    <img alt="Invite new member to organization" />
  </Step>

  <Step title="Member Accepts">
    The invited user gets an email. They click Accept Invitation and they're in.

    <img alt="Accept invite to organization" />
  </Step>
</Steps>

### Member Roles

Three base roles: owner, admin, and member.

* **Owner:** Full control over everything — settings, membership, clusters, environments, projects.
* **Admin:** Can manage members (except owners), clusters, environments, and RBAC.
* **Member:** Can deploy and create/delete clusters based on org policies.
* **Custom:** A role you define with specific permissions (e.g., QA Tester).

Owners can change roles and remove anyone. Admins can remove members but not owners.

### RBAC

RBAC builds on the base roles. You create custom roles with fine-grained permissions scoped to templates, secrets, clusters, projects, environments, and audit logs. Permissions can target specific environments.

**In the UI:** Click **Manage Roles** in the Organization panel.

<img alt="Monk Roles Management" />

**Via chat:**

```
/monk create a role called staging-deployer with deploy access to /environments/staging/templates/**
```

> Full details in [Access Control & Security](/features/access-control).

### Custom Instructions

You can define custom instructions at three levels: organization, project, and environment. These tell Monk's agents how to behave — what to deploy, what to avoid, what defaults to use.

<img alt="Monk Custom Instructions Team Feature" />

<Info>
  Set instructions like "don't spawn large instances" or "always use this database provider." They apply automatically to every agent action within that scope.
</Info>

> Full details in [Custom Knowledge](/features/custom-knowledge).

### Cluster Management

The Cluster Management menu lets you view and manage active clusters in your org.

**In the UI:**

* View cluster status (active, personal, organization)
* See linked environments and projects
* Actions: Add Member to Team, Switch Between Clusters, Link Cluster to Environment, Exit Cluster, Delete Cluster

Switch and Exit connect or disconnect your local machine from a cluster. Add Member to Team assigns a personal cluster to your organization.

<img alt="Monk Team Feature Cluster Management" />

**Via chat:** All cluster actions work through natural language.

<img alt="Monk Cluster Management via Chat" />

<Info>
  Personal clusters can be added to an organization via "Add to Team." This transfers ownership and applies your org's RBAC policies.
</Info>

### Environments

Manage environments across your organization — view linked projects and clusters, set per-environment instructions, delete what you don't need. Monk supports both cloud and on-premises environments.

<img alt="Monk Team Feature Environment Management" />

> Full details in [Multiple Environments](/features/environments).

### Workspaces

View all shared workspaces in your org. See which project each workspace belongs to, check its status, assign workspaces to projects, or delete them.

<img alt="Monk Team Feature Workspace Management" />

### Projects

Owners and admins can share projects with the team. Set custom instructions per project. No limit on shared projects.

The status view shows linked environments, clusters, and workspaces at a glance.

<img alt="Monk Team Feature Projects Management" />

> Full details in [Project Organization](/features/project-organization).

### Access Policies

Configure policies in the Organization panel under Cluster Policies:

* **Create policy:** Controls who can create or add clusters.
* **Default delete policy:** Applies to newly created clusters.

Per-cluster delete policies can be adjusted from each cluster card in the Clusters panel.

### Shared Secrets

Secrets can be scoped to workspace, user, or team. Team secrets require an organization context and an environment linked to an org cluster. In chat:

```
/monk add my-api-key as a team secret
```

Team secrets live on the cluster and are available to all org members with the right permissions.

### Audit Log

The audit log records org actions: builds, deployments, cluster operations, secret changes. View recent events in the Activity panel of the dashboard. Owners and admins see team-wide activity; members see their own.

<img alt="View Logs" />

> See [Access Control & Security](/features/access-control) for more on audit logging.

<CardGroup>
  <Card title="Access Control & Security" icon="shield" href="/features/access-control">
    RBAC, audit logging, and runtime security enforcement.
  </Card>

  <Card title="Project Organization" icon="folder" href="/features/project-organization">
    Environments, clusters, workspaces, and team secrets.
  </Card>
</CardGroup>


# Updates & Maintenance
Source: https://docs.monk.io/features/updates-and-maintenance

Seamless updates with automatic health checks and rollbacks

## What It Does

Tell Monk to deploy. Or push to git if you've [set up CI/CD](/features/build-and-cicd). Monk handles the rest — deployment, health checks, rollback if anything breaks.

Infrastructure changes, workload changes, API configurations, dependency upgrades — all applied automatically.

## How Updates Work

### Method 1: Direct Deployment

Tell Monk what you want:

```
You: Deploy the latest changes
```

Monk detects what changed, updates containers, applies new config, and verifies everything works.

### Method 2: Automatic via CI/CD

If you've [set up CI/CD](/features/build-and-cicd):

1. Push changes to your repository
2. CI pipeline triggers automatically
3. Monk deploys to production
4. Health checks verify the deployment

That's it.

### What Gets Updated

On every deploy, Monk handles:

**Application** — code changes, environment variables, container images, resource allocation (memory, CPU).

**Infrastructure** — new services added, removed services cleaned up, network routing updated, firewall rules adjusted.

**API configuration** — webhook URLs (Stripe, Auth0, etc.), OAuth callbacks, third-party API resources. See [APIs](/features/apis).

**Dependencies** — databases, caches, queues, and other supporting services upgraded to latest stable versions from the [package ecosystem](/features/service-templates). Data preserved.

All applied with zero downtime.

## Health Checks & Rollback

Monk doesn't consider a deployment done until it's verified.

**During rollout:**

* New containers must start successfully
* Services must respond to health endpoints
* Database connections must establish
* All dependencies must be reachable
* Traffic shifts gradually to the new version
* Old version stays live during transition

**If something fails:**

Monk reverts automatically. No manual intervention. The old version keeps running. You get notified.

### Manual Rollback

Keep your app and Monk config in git. Rolling back is straightforward:

1. Check out a previous commit: `git checkout <previous-commit>`
2. Tell Monk: `deploy this version`
3. Done — application, containers, infrastructure, service wiring all rolled back

With CI/CD, just push the previous commit. The pipeline handles it.

Monk treats your git history as your deployment history. Any commit can be deployed.

## OS & Runtime Updates

<Info>Automatic OS and runtime updates — rolling VM patches, security updates, orchestrator self-updates — are on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

<CardGroup>
  <Card icon="code-branch" title="Build & CI/CD" href="/features/build-and-cicd">
    Automatic deployments on every push.
  </Card>

  <Card icon="heart-pulse" title="Monitoring" href="/features/monitoring">
    Health checks, alerts, and validation.
  </Card>
</CardGroup>


# Watcher
Source: https://docs.monk.io/features/watcher

24/7 autonomous cluster monitoring with AI-powered alerts

## What It Does

Watcher runs on your cluster 24/7. It catches crashes, resource spikes, and health check failures. When something breaks, it figures out why and sends you a Slack alert with a diagnosis and a fix button.

That's it. No dashboards to babysit, no runbooks to follow, no pager rotation.

Available on Pro and Team plans.

## Setup

Tell Monk to set up Watcher:

```
/monk set up watcher
```

You'll get a configuration form with sensible defaults. Tweak thresholds if you want, or just click **Deploy Watcher**.

You can also say "configure watcher", "enable watcher", or "set up cluster monitoring."

**You need:**

* An active cluster with at least one non-local node
* A Slack workspace (optional — Watcher works without it, but you won't get push notifications)

## How It Works

Watcher deploys two components to your cluster:

1. **watcher-agent** — polls your nodes and workloads, collects metrics, spots problems
2. **watcher-ai** — analyzes what went wrong, writes recommendations, fires Slack alerts

Here's the flow when something breaks:

1. **Detect.** Continuous polling catches a threshold breach, crash loop, resource contention, excessive logs, or infrastructure instability.
2. **Analyze.** AI reads the logs, metrics, and context. It figures out what happened and why.
3. **Alert.** You get a Slack message with the diagnosis, severity, and a recommended fix.
4. **Fix.** Click **Fix with Monk** in the alert. Monk opens a chat session preloaded with full context and starts remediation.
5. **Recover.** When the issue clears, you get a recovery notification.

Every action is documented. You always know what happened.

<img alt="Watcher CPU notification Slack alert" />

## Slack Alerts

During setup, Monk asks if you want Slack alerts. Say yes and Monk opens a quick OAuth flow — you authorize in Slack, pick a channel, and you're done. No manual webhook URLs needed.

Skip Slack if you want. Watcher still monitors everything — you just won't get push notifications.

<Info>
  Watcher alerts are separate from the [Slack remote control](/features/slack) feature. Alerts are one-way notifications. Remote control is two-way interactive prompts for questions, forms, and approvals.
</Info>

## Slack Alert Format

**Issue detected:**

```
⚠️ AI Assessment

Sustained high CPU usage on api-server is driving node
CPU to ~80%+, with repeated warnings but no crashes yet.

Recommendation:
Confirm this is a true capacity issue rather than a
transient spike by continuing to monitor CPU usage.
If sustained, increase CPU resources or scale horizontally.

Target: api-server
Severity: warning

[Fix with Monk]
```

**Recovery:**

```
✅ AI Assessment

Recovery: CPU usage has normalized to ~78%, with workloads
running normally and no new errors.

Recommendation:
Keep current configuration but continue to observe.
```

## Fix with Monk Button

Every alert includes a **Fix with Monk** button. Click it and:

1. Your coding agent opens with Monk ready
2. The chat panel loads with full context — affected workload, logs, metrics, AI diagnosis
3. You tell Monk to fix it. It already knows what's wrong.

## Watcher Credits

Watcher is available on Pro and Team plans, and it's the only part of Monk that consumes watcher credits. Each account starts with 50 watcher credits from the free trial. Deploying, chatting with Monk, and the Monk plugin's everyday operations do not use watcher credits - only Watcher's monitoring, diagnosis, and repair cycles do. For current pricing, visit [Monk Pricing](https://monk.io/pricing).

## Configuration Options

The setup form has four sections:

### Crash Detection

* **Crash Threshold:** Restarts within the window to trigger an alert (default: 3)
* **Crash Window:** Time window for counting restarts (default: 5 minutes)
* **Health Check Failures:** Consecutive liveness failures before alerting (default: 3)

### Peer Thresholds (Cluster Nodes)

* **CPU %:** Usage threshold (default: 80%)
* **CPU Duration:** Sustained time before alerting (default: 5 minutes)
* **Memory %:** Usage threshold (default: 80%)
* **Memory Duration:** Sustained time before alerting (default: 5 minutes)
* **Disk %:** Usage threshold (default: 85%)
* **Disk Breaches:** Consecutive polls above threshold before alerting (default: 2)

### Workload Thresholds (Running Services)

* **CPU %:** Usage threshold (default: 80%)
* **CPU Duration:** Sustained time before alerting (default: 5 minutes)
* **Memory %:** Usage threshold (default: 80%)
* **Memory Duration:** Sustained time before alerting (default: 5 minutes)
* **Disk %:** Usage threshold (default: 90%)
* **Disk Breaches:** Consecutive polls above threshold before alerting (default: 3)

### Advanced Settings

Toggle "Show Advanced Options" to access:

* **Poll Interval:** How often to check cluster health (default: 15 seconds)
* **AI Only Slack:** Only send AI-analyzed alerts to Slack, cuts noise (default: on)
* **Enable Fix with Monk:** Include debugging links in Slack alerts (default: on)
* **Ignore Local Peer:** Skip local node checks, focus on remote peers (default: on)
* **Context TTL:** How long to keep alert context for debugging links (default: 24 hours)
* **Reassess Interval:** How often to re-evaluate ongoing issues (default: 15 minutes)
* **Log Lines:** Number of log lines to analyze per workload (default: 100)

<img alt="Watcher configuration" />

## Managing Watcher

**Check status:**

```
/monk is watcher running?
```

**Reconfigure:**

```
/monk set up watcher
```

**View logs:**

```
/monk show logs from system/watcher-agent
```

<Info>Autonomous auto-fixes — automatic restart, auto-scaling, smart rollback — are on the roadmap. [Vote on what to prioritize](https://monk.io/roadmap).</Info>

<CardGroup>
  <Card title="Monitoring & Observability" icon="gauge" href="/features/monitoring">
    Log streaming, metrics, and troubleshooting from your coding agent.
  </Card>

  <Card title="Scaling" icon="arrow-trend-up" href="/features/scaling">
    Scale resources when Watcher detects sustained pressure.
  </Card>
</CardGroup>


# Workload Migration
Source: https://docs.monk.io/features/workload-migration

Seamless cross-cloud application migration

## What It Does

Running on AWS but want to switch to DigitalOcean? On GCP but need to move to Azure? Tell Monk to migrate your application. It handles the rest.

## How It Works

### The Migration Process

**Starting point:**

* Your application is running on Cloud A (e.g., AWS)
* Managed by Monk

**Migration steps:**

### 1. Request Migration

Chat with Monk in your [coding agent](/getting-started/get-started):

```
You: Migrate this application to DigitalOcean
```

### 2. Provide Credentials

Monk asks for credentials to the target cloud provider:

```
Monk: I'll need DigitalOcean credentials to provision resources.
      Please provide your DigitalOcean API token.

You: [Provides token]

Monk: Credentials received. Analyzing current deployment...
```

<Info>
  Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS. They are never sent to Monk servers and never exposed to the LLM. Monk needs these because everything runs on **your infrastructure** (Bring Your Own Infrastructure - BYOI). See [Security](/features/security) for details.
</Info>

### 3. Resource Provisioning

Monk provisions matching resources on the target cloud:

```
Monk: Current AWS infrastructure:
      - 2x t3.medium instances (API servers)
      - 2x t3.small instances (workers)
      - Application Load Balancer
      - VPC with security groups

Monk: Creating equivalent DigitalOcean resources:
      - 2x 2GB Droplets (API servers)
      - 2x 1GB Droplets (workers)
      - Load Balancer
      - VPC with firewall rules
```

Monk creates infrastructure that matches your current deployment, optimized for the target cloud's instance types and services.

### 4. Workload Transfer

Monk starts your application on the new cloud and stops it on the old one.

**What gets migrated:**

* [Containerized services](/features/containerization) - API servers, workers, background jobs
* Application code and [configuration](/features/configuration-and-wiring)
* [Container images](/features/containerization) - pushed to registry on new cloud
* [Networking configuration](/features/networking) - VPCs, security groups, load balancers
* External service connections - [APIs](/features/apis), [databases](/features/databases), [essential services](/features/essential-services)

<Warning>
  **Data migration is not yet supported.** Monk migrates workloads (containers, configuration, networking) but not database data. Managed services (RDS, Cloud SQL, etc.) remain on the original cloud. Self-hosted databases stay on original infrastructure. Your migrated application connects back to databases on the original cloud. Full data migration is coming soon.
</Warning>

### 5. DNS Switchover

If you're using a DNS provider (Route 53, Cloudflare DNS, etc.):

* Monk automatically updates DNS records to point to new infrastructure
* Traffic seamlessly shifts to new cloud
* Old workloads receive no new requests

If you're not using DNS managed by Monk:

* Monk provides new IP addresses/URLs
* You manually update DNS or load balancer configuration

### 6. Cleanup

After verifying everything works on the new cloud:

```
You: Delete the old AWS resources

Monk: Confirming: Delete all AWS resources for this application?
      - 4 instances
      - Load balancer
      - VPC and security groups

You: Yes

Monk: Deleting AWS resources... Done.
      Migration finished. Running entirely on DigitalOcean.
```

That's it. Your application is now running on the new cloud provider.

## Why Migrate?

**Cost savings:**

* Move from an expensive cloud to a cheaper alternative
* Switching providers often yields significant savings on compute costs

**Better services:**

* Access provider-specific features (AWS SageMaker, Azure OpenAI, GCP BigQuery)
* Use specialized hosting (Netlify, Vercel for frontends)

**Geographic expansion:**

* Add regions available on other cloud providers
* Better latency for global users

**Vendor diversification:**

* Reduce dependency on a single cloud provider
* Increase resilience with multi-cloud architecture

**Compliance:**

* Meet data residency requirements in specific regions
* Switch to providers with required certifications

<img alt="Workload migration inside cluster example" />

## Related Features

<CardGroup>
  <Card title="Multi-Cloud Support" icon="cloud" href="/features/multi-cloud">
    Deploy and manage workloads across multiple clouds at once.
  </Card>

  <Card title="Security" icon="lock" href="/features/security">
    How your credentials and data are protected during migration.
  </Card>
</CardGroup>


# Getting Help & Support
Source: https://docs.monk.io/getting-help

How to get help, report bugs, request features, and connect with the Monk community

## Ways to Get Help

Monk provides multiple channels for getting assistance, reporting issues, and connecting with the community.

## Ask Monk Directly

The fastest way to get help is to **ask Monk directly** through your coding agent:

1. Open the coding agent where the Monk plugin is installed
2. Describe your issue or ask your question
3. Monk will guide you through troubleshooting or take action to resolve the problem

**Example questions:**

* "Why is my deployment failing?"
* "How do I add a Redis cache to my app?"
* "Can you show me the logs for my API service?"
* "How much is my infrastructure costing?"

Monk has context about your code, infrastructure, and deployment state, making it the most effective first point of contact.

## Report Bugs Through Chat

Monk has a **built-in bug reporting feature** that makes it easy to report issues without leaving your coding agent.

### How to Report a Bug

Describe the issue right in the chat:

```
/monk report a bug
```

**What happens when you report a bug:**

1. **Automatic context gathering** — Monk collects relevant information about your environment, deployment state, and the issue
2. **Direct submission** — Your report goes directly to the Monk engineering team
3. **Follow-up** — You'll receive updates on the issue status

Monk can also file reports on its own when it runs into a problem.

## Report Bugs from the Dashboard

In the [Monk dashboard](https://monk.io/dashboard), click the **bug icon in the top-right corner**, pick Bug, Feature, or Other, and describe the issue.

<Tip>
  The more detail you provide, the faster we can diagnose and fix the issue.
  Include steps to reproduce if possible.
</Tip>

## Request Features

Have an idea for a new feature or improvement?

### Through Chat

Use the same bug reporting flow to submit feature requests. Just describe what you'd like to see added to Monk.

### Community Forum

Visit the Monk community forum to:

* Submit new feature ideas
* Vote on existing requests
* See what's planned for upcoming releases
* Track bug reports and their status

**[Visit Community Forum](https://roadmap.monk.io/)**

## Community & Forums

### Monk Community Forum

Join the Monk community forum for:

* **Feature requests** — Submit and vote on new features
* **Bug reports** — Report issues and track their status
* **Product roadmap** — See what's planned and in progress
* **Community discussions** — Connect with other Monk users
* **Feedback and ideas** — Share your thoughts on Monk

**[Visit Community Forum](https://roadmap.monk.io/)**

## Documentation

### Search the Docs

Our documentation covers all of Monk's features and capabilities:

* [Getting Started](/getting-started/what-is-monk) — Installation and first deployment
* [Features](/features) — Complete feature reference
* [Prompting Cookbook](/prompting/how-prompting-works) — Task-focused guides
* [FAQ](/faq) — Frequently asked questions

### Video Tutorials

Watch video tutorials on our YouTube channel:

**[Monk on YouTube](https://youtube.com/@monk_io)**

## Direct Support

### Email Support

For account issues, billing questions, or private support inquiries:

**[hi@monk.io](mailto:hi@monk.io)**

***

<Card title="Can't Find What You Need?" icon="question">
  Start by asking Monk directly through your coding agent. Monk has full
  context about your project and can help troubleshoot or point you to the right
  resources.
</Card>


# Autonomous Operations
Source: https://docs.monk.io/getting-started/autonomous-operations

What Monk does for you after the first deployment

Your app is deployed. Now what? Monk does not stop at deployment — it keeps your system running, watches for problems, and gives you instant visibility into everything that is happening. This page covers what you can set up on day two and what keeps working on day two hundred.

Everything here can be done through your coding agent. Just ask.

<iframe title="Monk DevOps Agent (3/3): Your App Runs Itself — CI/CD, Scaling, Monitoring, FinOps" />

***

## CI/CD

Set up continuous deployment so every push to your repository triggers a new build and deploy. No pipeline files to write.

```
/monk set up CI/CD for this project
```

Monk configures GitHub Actions (or your CI provider), wires it to your deployment, and from that point on every merge to main goes live automatically.

<img alt="CI/CD setup with Monk" />

<Card title="CI/CD setup guide" icon="arrows-rotate" href="/prompting/setting-up-cicd">
  Detailed walkthrough and configuration options
</Card>

***

## Watcher

Watcher monitors your services around the clock. When something goes wrong — a container crashes, CPU spikes, a health check fails — Monk sends an alert to Slack with full context and a **Fix with Monk** button that lets you resolve the issue in one click.

```
/monk set up watcher for this project
```

Monk configures monitoring for all your services and starts watching immediately. If you connect Slack, alerts go straight to your channel.

<img alt="Watcher alert on Slack" />

<Card title="Watcher setup guide" icon="bell" href="/prompting/watcher-setup">
  Alerts, triage, Slack integration, and the Fix with Monk button
</Card>

***

## Slack

Connect Monk to Slack and you can respond to questions, approve file changes, and fill out configuration forms directly from Slack — without opening your coding agent. Start a deployment, close your laptop, and handle the next decision from your phone.

```
/monk connect Slack
```

Monk walks you through an OAuth flow and channel selection.

<Card title="Slack integration" icon="slack" href="/features/slack">
  Setup, remote control, Watcher alerts, and managing the connection
</Card>

***

## Logs and Debugging

Access logs from any running service instantly. No SSH, no dashboards to set up.

```
/monk show me the logs for the API service
```

```
/monk why the backend is returning 500 errors
```

Monk pulls logs, analyzes them, and explains what is happening. If there is a fix, it can apply it.

<img alt="View logs" />

***

## Live System View

Monk maintains a live graph of your entire application — every service, database, load balancer, and connection. You can see it anytime.

```
/monk show me the system map
```

```
/monk what infrastructure is running right now
```

This is not a static diagram. It reflects the actual state of your deployment and updates as things change.

<img alt="Task board and system view" />

***

## Scaling

Scale services up or down with a prompt. Monk handles instance resizing, load balancer updates, and zero-downtime rollouts.

```
/monk scale the API to 3 instances
```

```
/monk upgrade the database to a larger instance
```

<img alt="Cloud scaling" />

***

## Cost Visibility

See what your infrastructure costs right now, broken down by service.

```
/monk how much this project is costing me
```

```
/monk suggest ways to reduce cost
```

<img alt="Cloud cost visibility" />

***

## Migration

Move workloads between clouds or regions without rebuilding anything. Monk handles the migration end to end.

```
/monk migrate this project from AWS to DigitalOcean
```

<img alt="Migrate workloads between clouds" />

***

## What Monk Handles vs. What It Asks You

Monk executes autonomously on implementation details — container builds, networking, security groups, health checks, DNS. It does not ask permission for these.

Monk asks you about things that matter: which cloud provider, which region, whether to use a managed database or self-hosted, and before any destructive action like deleting infrastructure.

You stay in control. You can review plans before deployment, override decisions, and ask "why" at any point.

***

## Next Steps

<CardGroup>
  <Card title="Connect your cloud" icon="key" href="/getting-started/obtaining-credentials">
    Add more cloud providers and service credentials
  </Card>

  <Card title="Prompting guide" icon="lightbulb" href="/prompting/how-prompting-works">
    Tips for getting the most out of Monk
  </Card>

  <Card title="All features" icon="sparkles" href="/features">
    Complete reference of everything Monk can do
  </Card>

  <Card title="Getting help" icon="life-ring" href="/getting-help">
    Bug reports, support channels, and community
  </Card>
</CardGroup>


# Run on AWS
Source: https://docs.monk.io/getting-started/credentials-aws

Connect Monk to your AWS account

Monk needs an IAM access key to provision and manage infrastructure in your AWS account. This page walks you through creating one with the right permissions.

## What You Need

* AWS Access Key ID
* AWS Secret Access Key
* Optional: default region (e.g., `us-east-1`)

## Create Credentials

<Steps>
  <Step title="Open the IAM console">
    Log into [AWS Console → IAM → Users](https://console.aws.amazon.com/iam/home#/users).
  </Step>

  <Step title="Create a dedicated user">
    Click **Create user**. Name it something like `monk-deploy`. Do not grant console access — Monk only needs programmatic access.
  </Step>

  <Step title="Attach the Monk policy">
    On the permissions step, choose **Attach policies directly** and create a custom policy with the JSON below. Name it `MonkClusterPolicy`.
  </Step>

  <Step title="Create an access key">
    After the user is created, go to the user → **Security credentials** tab → **Create access key**. Choose "Third-party service" as the use case. Copy the **Access Key ID** and **Secret Access Key**.
  </Step>

  <Step title="Provide to Monk">
    When you deploy to AWS, Monk requests credentials through a secure local form, never through the chat. Paste them there. You can also tell your agent:

    ```
    /monk update my AWS credentials
    ```
  </Step>
</Steps>

## Required Permissions

You can use the broad managed policies for a quick start:

* `AmazonEC2FullAccess`
* `AmazonVPCFullAccess`
* `IAMReadOnlyAccess`

For production, use the minimum custom policy below. It covers exactly what Monk needs and nothing more.

**Scope summary:** EC2 instances, images, and instance types. VPCs, subnets, routing, internet gateways. Security groups, network interfaces, elastic IPs. EBS volumes and snapshots. Load balancers and target groups (ELBv2). ACM certificates (HTTPS). DLM policies (automated backups). STS `GetCallerIdentity`. `iam:PassRole` for the DLM service role.

<Accordion title="Minimum IAM policy JSON">
  ```json theme={null}
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "MonkEC2Instances",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeInstances",
          "ec2:DescribeInstanceStatus",
          "ec2:DescribeInstanceTypes",
          "ec2:RunInstances",
          "ec2:TerminateInstances",
          "ec2:StopInstances",
          "ec2:ModifyInstanceAttribute"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2Images",
        "Effect": "Allow",
        "Action": ["ec2:DescribeImages"],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2RegionsAndZones",
        "Effect": "Allow",
        "Action": ["ec2:DescribeRegions", "ec2:DescribeAvailabilityZones"],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2VPC",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeVpcs",
          "ec2:CreateVpc",
          "ec2:CreateDefaultVpc",
          "ec2:ModifyVpcAttribute"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2Subnets",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeSubnets",
          "ec2:CreateSubnet",
          "ec2:CreateDefaultSubnet",
          "ec2:ModifySubnetAttribute"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2InternetGateways",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeInternetGateways",
          "ec2:CreateInternetGateway",
          "ec2:AttachInternetGateway"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2RouteTables",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeRouteTables",
          "ec2:CreateRouteTable",
          "ec2:CreateRoute"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2SecurityGroups",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeSecurityGroups",
          "ec2:DescribeSecurityGroupRules",
          "ec2:CreateSecurityGroup",
          "ec2:DeleteSecurityGroup",
          "ec2:AuthorizeSecurityGroupIngress",
          "ec2:RevokeSecurityGroupIngress"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2NetworkInterfaces",
        "Effect": "Allow",
        "Action": ["ec2:DeleteNetworkInterface"],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2ElasticIPs",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeAddresses",
          "ec2:AllocateAddress",
          "ec2:AssociateAddress",
          "ec2:ReleaseAddress"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2Volumes",
        "Effect": "Allow",
        "Action": [
          "ec2:DescribeVolumes",
          "ec2:DescribeVolumesModifications",
          "ec2:CreateVolume",
          "ec2:DeleteVolume",
          "ec2:AttachVolume",
          "ec2:DetachVolume",
          "ec2:ModifyVolume"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2Snapshots",
        "Effect": "Allow",
        "Action": ["ec2:DescribeSnapshots", "ec2:DeleteSnapshot"],
        "Resource": "*"
      },
      {
        "Sid": "MonkEC2Tags",
        "Effect": "Allow",
        "Action": ["ec2:CreateTags"],
        "Resource": "*"
      },
      {
        "Sid": "MonkELBv2",
        "Effect": "Allow",
        "Action": [
          "elasticloadbalancing:DescribeLoadBalancers",
          "elasticloadbalancing:CreateLoadBalancer",
          "elasticloadbalancing:DeleteLoadBalancer",
          "elasticloadbalancing:DescribeListeners",
          "elasticloadbalancing:CreateListener",
          "elasticloadbalancing:DeleteListener",
          "elasticloadbalancing:DescribeTargetGroups",
          "elasticloadbalancing:CreateTargetGroup",
          "elasticloadbalancing:DeleteTargetGroup",
          "elasticloadbalancing:RegisterTargets",
          "elasticloadbalancing:DeregisterTargets",
          "elasticloadbalancing:DescribeTargetHealth",
          "elasticloadbalancing:AddTags"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkACM",
        "Effect": "Allow",
        "Action": [
          "acm:ListCertificates",
          "acm:ListTagsForCertificate",
          "acm:GetCertificate",
          "acm:ImportCertificate",
          "acm:DeleteCertificate",
          "acm:DescribeCertificate"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkDLM",
        "Effect": "Allow",
        "Action": [
          "dlm:GetLifecyclePolicies",
          "dlm:GetLifecyclePolicy",
          "dlm:CreateLifecyclePolicy",
          "dlm:UpdateLifecyclePolicy",
          "dlm:DeleteLifecyclePolicy"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkSTS",
        "Effect": "Allow",
        "Action": ["sts:GetCallerIdentity"],
        "Resource": "*"
      },
      {
        "Sid": "MonkIAMPassRole",
        "Effect": "Allow",
        "Action": ["iam:PassRole"],
        "Resource": "arn:aws:iam::*:role/service-role/AWSDataLifecycleManagerDefaultRole"
      },
      {
        "Sid": "MonkIAMSimulate",
        "Effect": "Allow",
        "Action": ["iam:SimulateCustomPolicy", "iam:SimulatePrincipalPolicy"],
        "Resource": "*"
      },
      {
        "Sid": "MonkKMS",
        "Effect": "Allow",
        "Action": [
          "kms:ListKeys",
          "kms:ListAliases",
          "kms:DescribeKey",
          "kms:CreateKey",
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:GenerateDataKey",
          "kms:ScheduleKeyDeletion",
          "kms:CreateAlias",
          "kms:UpdateAlias",
          "kms:EnableKey",
          "kms:DisableKey",
          "kms:CancelKeyDeletion"
        ],
        "Resource": "*"
      },
      {
        "Sid": "MonkCloudWatch",
        "Effect": "Allow",
        "Action": ["cloudwatch:GetMetricData"],
        "Resource": "*"
      },
      {
        "Sid": "MonkPricing",
        "Effect": "Allow",
        "Action": ["pricing:GetProducts", "ce:GetCostAndUsage"],
        "Resource": "*"
      }
    ]
  }
  ```
</Accordion>

<Accordion title="CLI setup (alternative to console)">
  ```bash theme={null}
  # Create the IAM user
  aws iam create-user --user-name monk-user

  # Create the policy (save the JSON above as monk-policy.json)
  aws iam create-policy \
    --policy-name MonkClusterPolicy \
    --policy-document file://monk-policy.json

  # Attach the policy (replace ACCOUNT_ID)
  aws iam attach-user-policy \
    --user-name monk-user \
    --policy-arn arn:aws:iam::ACCOUNT_ID:policy/MonkClusterPolicy

  # Create access keys
  aws iam create-access-key --user-name monk-user
  ```
</Accordion>

## How Credentials Are Stored

Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS — so your infrastructure can manage itself autonomously. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for full details.

## Troubleshooting

**Access keys disabled** — check the user in the IAM console and confirm the key is active.

**Missing permissions** — if Monk reports permission errors, compare the attached policy against the minimum policy above.

**Region mismatch** — if you specified a default region, make sure it matches an available AWS region.

Ask your agent for help:

```
/monk why my AWS credentials are not working
```

<Card title="Deploy your first app" icon="rocket" href="/getting-started/first-deployment">
  Credentials ready — now deploy
</Card>


# Run on Azure
Source: https://docs.monk.io/getting-started/credentials-azure

Connect Monk to your Microsoft Azure account

Monk needs a service principal to provision and manage infrastructure in your Azure subscription. This page walks you through creating one with the right permissions.

## What You Need

* Client ID (Application ID)
* Client Secret
* Tenant ID
* Subscription ID
* Resource Group name

## Create Credentials

<Steps>
  <Step title="Copy your Subscription ID">
    Log into [Azure Portal → Subscriptions](https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade) and copy the **Subscription ID** you want Monk to use.
  </Step>

  <Step title="Register an application">
    Go to [Azure Active Directory → App registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps) → **New registration**. Name it something like `monk-deployment` and click **Register**.
  </Step>

  <Step title="Copy IDs">
    On the app overview page, copy the **Application (client) ID** and **Directory (tenant) ID**.
  </Step>

  <Step title="Create a client secret">
    Go to **Certificates & secrets** → **New client secret**. Set an expiry and copy the **Value** immediately — it is shown only once.
  </Step>

  <Step title="Assign a role">
    Go to your subscription → **Access control (IAM)** → **Add role assignment**. Assign the **Contributor** role (or the custom role below) to the application you just registered.
  </Step>

  <Step title="Provide to Monk">
    When you deploy to Azure, Monk requests credentials through a secure form. You can provide them as individual fields or as an SDK auth JSON file. You can also tell your agent:

    ```
    /monk update my Azure credentials
    ```
  </Step>
</Steps>

## Required Permissions

The built-in **Contributor** role works for a quick start. For production, use the minimum custom role below.

**Scope summary:** Compute (VMs, disks, snapshots, availability sets). Networking (VNet/subnets, NICs, public IPs, NSGs). Load balancing (load balancers and application gateways). Resource groups and subscription metadata. Marketplace agreements (for some images).

<Accordion title="Minimum custom role JSON">
  ```json theme={null}
  {
    "$schema": "https://schema.management.azure.com/schemas/2018-01-01/roleDefinition.json",
    "Name": "Monk Cluster Role",
    "IsCustom": true,
    "Description": "Custom role for Monk container orchestration platform",
    "Actions": [
      "Microsoft.Network/publicIPAddresses/read",
      "Microsoft.Network/publicIPAddresses/write",
      "Microsoft.Network/publicIPAddresses/delete",
      "Microsoft.Network/publicIPAddresses/join/action",
      "Microsoft.Compute/disks/read",
      "Microsoft.Compute/disks/write",
      "Microsoft.Compute/disks/delete",
      "Microsoft.Compute/snapshots/read",
      "Microsoft.Compute/snapshots/write",
      "Microsoft.Compute/snapshots/delete",
      "Microsoft.Network/networkWatchers/read",
      "Microsoft.Network/networkWatchers/delete",
      "Microsoft.Network/virtualNetworks/read",
      "Microsoft.Network/virtualNetworks/write",
      "Microsoft.Network/virtualNetworks/delete",
      "Microsoft.Network/virtualNetworks/subnets/read",
      "Microsoft.Network/virtualNetworks/subnets/write",
      "Microsoft.Network/virtualNetworks/subnets/delete",
      "Microsoft.Network/virtualNetworks/subnets/join/action",
      "Microsoft.Compute/virtualMachines/read",
      "Microsoft.Compute/virtualMachines/write",
      "Microsoft.Compute/virtualMachines/delete",
      "Microsoft.Compute/virtualMachines/restart/action",
      "Microsoft.Compute/virtualMachines/start/action",
      "Microsoft.Compute/virtualMachines/powerOff/action",
      "Microsoft.Network/networkInterfaces/read",
      "Microsoft.Network/networkInterfaces/write",
      "Microsoft.Network/networkInterfaces/join/action",
      "Microsoft.Network/networkInterfaces/delete",
      "Microsoft.Resources/subscriptions/resourceGroups/read",
      "Microsoft.Resources/subscriptions/resourceGroups/write",
      "Microsoft.Resources/subscriptions/resourceGroups/delete",
      "Microsoft.Network/networkSecurityGroups/read",
      "Microsoft.Network/networkSecurityGroups/write",
      "Microsoft.Network/networkSecurityGroups/delete",
      "Microsoft.Network/networkSecurityGroups/join/action",
      "Microsoft.Network/loadBalancers/read",
      "Microsoft.Network/loadBalancers/write",
      "Microsoft.Network/loadBalancers/delete",
      "Microsoft.Network/loadBalancers/backendAddressPools/join/action",
      "Microsoft.Compute/availabilitySets/read",
      "Microsoft.Compute/availabilitySets/write",
      "Microsoft.Compute/availabilitySets/delete",
      "Microsoft.Network/applicationGateways/read",
      "Microsoft.Network/applicationGateways/write",
      "Microsoft.Network/applicationGateways/delete",
      "Microsoft.Compute/skus/read",
      "Microsoft.Compute/locations/usages/read",
      "Microsoft.Resources/subscriptions/locations/read",
      "Microsoft.Authorization/permissions/read",
      "Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/read",
      "Microsoft.MarketplaceOrdering/offertypes/publishers/offers/plans/agreements/write"
    ],
    "NotActions": [],
    "DataActions": [],
    "NotDataActions": [],
    "AssignableScopes": [
      "/subscriptions/YOUR_SUBSCRIPTION_ID"
    ]
  }
  ```
</Accordion>

<Accordion title="CLI setup (alternative to portal)">
  ```bash theme={null}
  # Replace YOUR_SUBSCRIPTION_ID in monk-role.json first
  az role definition create --role-definition monk-role.json

  # Create service principal with the custom role
  az ad sp create-for-rbac \
    --name "monk-cluster-sp" \
    --role "Monk Cluster Role" \
    --scopes "/subscriptions/YOUR_SUBSCRIPTION_ID" \
    --sdk-auth > azurekey.json

  # Provide the SDK auth file to Monk
  monk cluster provider add -p azure -f /absolute/path/to/azurekey.json
  ```
</Accordion>

## How Credentials Are Stored

Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS — so your infrastructure can manage itself autonomously. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for full details.

## Troubleshooting

**Client secret expired** — create a new secret in App registrations → Certificates & secrets, then update credentials in Monk.

**Wrong tenant ID** — double-check the Directory (tenant) ID on the app overview page.

**Missing Contributor role** — verify the role assignment in your subscription's Access control (IAM).

Ask your agent for help:

```
/monk why my Azure credentials are not working
```

<Card title="Deploy your first app" icon="rocket" href="/getting-started/first-deployment">
  Credentials ready — now deploy
</Card>


# Run on DigitalOcean
Source: https://docs.monk.io/getting-started/credentials-digitalocean

Connect Monk to your DigitalOcean account

Monk needs a personal access token to provision and manage infrastructure in your DigitalOcean account. This is the simplest credential setup of all four cloud providers.

## What You Need

* Personal Access Token (API token)
* Optional: default region (e.g., `nyc1`)

## Create Credentials

<Steps>
  <Step title="Open the API page">
    Log into [DigitalOcean → API → Tokens](https://cloud.digitalocean.com/account/api/tokens).
  </Step>

  <Step title="Generate a token">
    Click **Generate New Token**. Name it something like `monk-deployment`. Check both **Read** and **Write** scopes.
  </Step>

  <Step title="Copy the token">
    Copy the token immediately — it is shown only once.
  </Step>

  <Step title="Provide to Monk">
    When you deploy to DigitalOcean, Monk requests the token through a secure local form, never through the chat. You can also tell your agent:

    ```
    /monk update my DigitalOcean credentials
    ```
  </Step>
</Steps>

## Required Permissions

The token needs both **Read** and **Write** scopes. DigitalOcean tokens are all-or-nothing — there is no fine-grained permission model like AWS IAM.

## How Credentials Are Stored

Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS — so your infrastructure can manage itself autonomously. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for full details.

## Troubleshooting

**Token revoked** — generate a new token on the API page and update credentials in Monk.

**Insufficient scopes** — make sure the token has both Read and Write. Read-only tokens cannot provision infrastructure.

Ask your agent for help:

```
/monk why my DigitalOcean credentials are not working
```

<Card title="Deploy your first app" icon="rocket" href="/getting-started/first-deployment">
  Credentials ready — now deploy
</Card>


# Run on Google Cloud
Source: https://docs.monk.io/getting-started/credentials-gcp

Connect Monk to your Google Cloud account

Monk needs a service account JSON key to provision and manage infrastructure in your Google Cloud project. This page walks you through creating one with the right permissions.

## What You Need

* Service account JSON key file
* Optional: project ID (auto-extracted from the key)
* Optional: default region (e.g., `us-central1`)

## Create Credentials

<Steps>
  <Step title="Open the Service Accounts page">
    Log into [GCP Console → IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts).
  </Step>

  <Step title="Create a service account">
    Click **Create Service Account**. Name it something like `monk-deployment`.
  </Step>

  <Step title="Grant roles">
    For a quick start, grant **Compute Admin** and **Service Account User**. For production, create a custom role with the minimum permissions listed below.
  </Step>

  <Step title="Create a JSON key">
    Click the service account name → **Keys** tab → **Add Key** → **Create new key** → **JSON**. Download the file.
  </Step>

  <Step title="Provide to Monk">
    When you deploy to GCP, Monk asks for the key file through a secure form. Select the downloaded JSON. You can also tell your agent:

    ```
    /monk update my GCP credentials
    ```
  </Step>
</Steps>

## Required Permissions

**Predefined roles (simpler, broader):**

* `roles/compute.admin` (Compute Admin)
* `roles/iam.serviceAccountUser` (Service Account User)

For production, use a custom role with only the permissions Monk needs.

**Scope summary:** Compute Engine instances, images, and instance groups. Disks, snapshots, and resource policies (backups). VPC networks, subnets, firewalls, and external IPs. Load balancing: health checks, forwarding rules, backend services, proxies, URL maps. Operations and regions metadata.

<Accordion title="Minimum permissions list">
  ```
  # Disks
  compute.disks.get
  compute.disks.create
  compute.disks.delete
  compute.disks.resize
  compute.disks.update
  compute.disks.createSnapshot
  compute.disks.addResourcePolicies
  compute.disks.removeResourcePolicies

  # Resource Policies (backups)
  compute.resourcePolicies.delete
  compute.resourcePolicies.get
  compute.resourcePolicies.create

  # Snapshots
  compute.snapshots.list
  compute.snapshots.delete
  compute.snapshots.get

  # Health Checks (global + regional)
  compute.healthChecks.create
  compute.healthChecks.delete
  compute.healthChecks.get
  compute.healthChecks.update
  compute.regionHealthChecks.create
  compute.regionHealthChecks.delete
  compute.regionHealthChecks.get
  compute.regionHealthChecks.update

  # Instance Groups
  compute.instanceGroups.create
  compute.instanceGroups.delete
  compute.instanceGroups.get
  compute.instanceGroups.update
  compute.instanceGroups.list
  compute.instanceGroups.addInstances
  compute.instanceGroups.removeInstances
  compute.instanceGroupManagers.update

  # Addresses (global + regional)
  compute.globalAddresses.create
  compute.globalAddresses.delete
  compute.globalAddresses.get
  compute.addresses.list
  compute.addresses.create
  compute.addresses.delete
  compute.addresses.get

  # Target TCP Proxies (global + regional)
  compute.targetTcpProxies.create
  compute.targetTcpProxies.delete
  compute.targetTcpProxies.get
  compute.targetTcpProxies.update
  compute.regionTargetTcpProxies.create
  compute.regionTargetTcpProxies.delete
  compute.regionTargetTcpProxies.get

  # Target HTTP Proxies (global + regional)
  compute.targetHttpProxies.create
  compute.targetHttpProxies.delete
  compute.targetHttpProxies.get
  compute.targetHttpProxies.setUrlMap
  compute.regionTargetHttpProxies.create
  compute.regionTargetHttpProxies.delete
  compute.regionTargetHttpProxies.get
  compute.regionTargetHttpProxies.setUrlMap

  # Target HTTPS Proxies (global + regional)
  compute.targetHttpsProxies.create
  compute.targetHttpsProxies.delete
  compute.targetHttpsProxies.get
  compute.targetHttpsProxies.setSslCertificates
  compute.regionTargetHttpsProxies.create
  compute.regionTargetHttpsProxies.delete
  compute.regionTargetHttpsProxies.get
  compute.regionTargetHttpsProxies.setSslCertificates

  # Backend Services (global + regional)
  compute.backendServices.create
  compute.backendServices.delete
  compute.backendServices.get
  compute.backendServices.update
  compute.backendServices.use
  compute.regionBackendServices.create
  compute.regionBackendServices.delete
  compute.regionBackendServices.get
  compute.regionBackendServices.update

  # SSL Certificates (global + regional)
  compute.sslCertificates.create
  compute.sslCertificates.delete
  compute.sslCertificates.get
  compute.regionSslCertificates.create
  compute.regionSslCertificates.delete
  compute.regionSslCertificates.get

  # URL Maps (global + regional)
  compute.urlMaps.create
  compute.urlMaps.delete
  compute.urlMaps.get
  compute.urlMaps.update
  compute.regionUrlMaps.create
  compute.regionUrlMaps.delete
  compute.regionUrlMaps.get
  compute.regionUrlMaps.update

  # Forwarding Rules (global + regional)
  compute.globalForwardingRules.create
  compute.globalForwardingRules.delete
  compute.globalForwardingRules.get
  compute.forwardingRules.create
  compute.forwardingRules.delete
  compute.forwardingRules.get

  # Zones, Regions, Machine Types, Images
  compute.zones.list
  compute.regions.get
  compute.machineTypes.get
  compute.images.getFromFamily

  # Target Instances
  compute.targetInstances.create
  compute.targetInstances.delete
  compute.targetInstances.get

  # Firewalls
  compute.firewalls.create
  compute.firewalls.delete
  compute.firewalls.get
  compute.firewalls.update

  # Operations
  compute.zoneOperations.get
  compute.regionOperations.get
  compute.globalOperations.get

  # Instances
  compute.instances.use
  compute.instances.get
  compute.instances.list
  compute.instances.create
  compute.instances.delete
  compute.instances.stop
  compute.instances.setTags
  compute.instances.deleteAccessConfig
  compute.instances.addAccessConfig
  compute.instances.detachDisk
  compute.instances.attachDisk
  compute.instances.aggregatedList

  # Networks and Subnetworks
  compute.networks.useExternalIp
  compute.subnetworks.useExternalIp
  compute.subnetworks.get
  compute.subnetworks.create

  # Routers (NAT for proxy-only subnets)
  compute.routers.get
  compute.routers.create

  # Network Endpoint Groups (regional)
  compute.regionNetworkEndpointGroups.get
  compute.regionNetworkEndpointGroups.create
  compute.regionNetworkEndpointGroups.delete
  compute.regionNetworkEndpointGroups.attachNetworkEndpoints
  ```
</Accordion>

<Accordion title="CLI setup (alternative to console)">
  ```bash theme={null}
  # Create service account
  gcloud iam service-accounts create monk-cluster \
    --display-name "Monk Cluster"

  # Create a custom role (save permissions above as monk-gcp-role.yaml)
  gcloud iam roles create MonkClusterRole \
    --project PROJECT_ID \
    --file monk-gcp-role.yaml

  # Bind role to the service account
  gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:monk-cluster@PROJECT_ID.iam.gserviceaccount.com" \
    --role "projects/PROJECT_ID/roles/MonkClusterRole"

  # Create key
  gcloud iam service-accounts keys create monk-gcp-key.json \
    --iam-account "monk-cluster@PROJECT_ID.iam.gserviceaccount.com"
  ```
</Accordion>

## How Credentials Are Stored

Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS — so your infrastructure can manage itself autonomously. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for full details.

## Troubleshooting

**Service account disabled** — check the service account status in IAM & Admin.

**JSON key file malformed** — re-download the key. Make sure you selected JSON format, not P12.

**Missing roles** — if Monk reports permission errors, verify the custom role or predefined roles are bound to the service account.

Ask your agent for help:

```
/monk why my GCP credentials are not working
```

<Card title="Deploy your first app" icon="rocket" href="/getting-started/first-deployment">
  Credentials ready — now deploy
</Card>


# Run on Hetzner
Source: https://docs.monk.io/getting-started/credentials-hetzner

Connect Monk to your Hetzner Cloud account

Monk needs an API token to provision and manage infrastructure in your Hetzner Cloud account. Like DigitalOcean, this is a simple token-based setup.

## What You Need

* Hetzner Cloud API Token
* Optional: default region (e.g., `eu-central`)

## Create Credentials

<Steps>
  <Step title="Open the Hetzner Cloud Console">
    Log into [Hetzner Cloud Console](https://console.hetzner.cloud) and select the project you want Monk to manage.
  </Step>

  <Step title="Go to API Tokens">
    In the left sidebar, navigate to **Security** > **API Tokens**.
  </Step>

  <Step title="Generate a token">
    Click **Generate API Token**. Name it something like `monk-deployment`. Select **Read & Write** permissions.
  </Step>

  <Step title="Copy the token">
    Copy the token immediately — it is shown only once and cannot be retrieved later.
  </Step>

  <Step title="Provide to Monk">
    When you deploy to Hetzner, Monk requests the token through a secure local form, never through the chat. You can also tell your agent:

    ```
    /monk update my Hetzner credentials
    ```
  </Step>
</Steps>

## Required Permissions

The token needs **Read & Write** permissions. Hetzner tokens are scoped to a single project — one token cannot access resources in other projects. There is no fine-grained permission model; Read & Write grants full access to all resources within the project.

## How Credentials Are Stored

Credentials are encrypted at rest on your machine and on your Monk cluster using your cloud provider's KMS — so your infrastructure can manage itself autonomously. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for full details.

## Troubleshooting

**Token revoked** — generate a new token from Security > API Tokens in the Hetzner Cloud Console and update credentials in Monk.

**Wrong project** — Hetzner tokens are project-scoped. Make sure you generated the token in the correct project.

**Insufficient permissions** — make sure the token has Read & Write. Read-only tokens cannot provision infrastructure.

Ask your agent for help:

```
/monk why my Hetzner credentials are not working
```

<Card title="Deploy your first app" icon="rocket" href="/getting-started/first-deployment">
  Credentials ready — now deploy
</Card>


# First Deployment
Source: https://docs.monk.io/getting-started/first-deployment

Deploy your first application in minutes

This is where the loop closes. Your coding agent builds the app, Monk deploys it to your cloud, and from that point on the software runs autonomously. You describe what you want, and the agents handle the rest.

<iframe title="Monk DevOps Agent (2/3): One Prompt to Production — On Your Own Cloud" />

## Before You Start

<Steps>
  <Step title="Monk installed">
    If not, follow [Install Monk](/getting-started/get-started).
  </Step>

  <Step title="Agent connected">
    The plugin connects your coding agent to Monk over MCP automatically during install — there is no separate connection step. If you're unsure, run `/monk check installation status`.
  </Step>

  <Step title="Cloud credentials (optional)">
    If you want to deploy to the cloud (recommended), have your cloud provider credentials ready. See [Obtaining Credentials](/getting-started/obtaining-credentials) for AWS, GCP, Azure, or DigitalOcean setup.

    Want to try Monk locally first? Skip this step — Monk can deploy to your local machine too.
  </Step>
</Steps>

## Deploy

Open your project in your coding agent. Optionally, start by getting the lay of the land:

```
/monk describe this project
```

Monk analyzes the code and returns a summary with an architecture diagram of your app. Then deploy:

```
/monk deploy this project
```

That's it. No configuration files, no Dockerfiles, no Terraform. This works on existing codebases too — even if your project already has a docker-compose file, IaC definitions, or other deployment configuration. Monk uses these to orient itself but does not modify them. Your existing deployment stays working until you are ready to make the switch.

Don't have an app handy? Ask your coding agent to build one and deploy it in a single prompt:

```
create a simple todo app with a REST API and PostgreSQL, then /monk deploy it
```

<Warning>
  Deploying to your cloud account will incur cloud provider costs. These vary depending on what you are deploying. Monk always asks for confirmation before creating cloud infrastructure on your behalf. Start with smaller VMs when trying things out — you can always scale up later.
</Warning>

If you want more control upfront, be specific:

```
/monk deploy this project on AWS us-east-1 with RDS for PostgreSQL
```

More detail means fewer questions. Either way works.

## What Happens Next

The deployment is a short guided flow. You review and approve; the agents do the work.

<Steps>
  <Step title="Pick a team">
    Monk asks which team the project belongs to — Personal, or one of your organizations.
  </Step>

  <Step title="Enter credentials in the local Monk dashboard">
    A browser window opens the [local Monk dashboard](/getting-started/local-dashboard) with a form for your cloud API key and any database or service secrets. Credentials go straight into the form — they are never pasted into chat and never exposed to the agents.
  </Step>

  <Step title="Confirm the configuration">
    Back in your coding agent, Monk prepares the deployment configuration and asks you to confirm the credentials are in place.
  </Step>

  <Step title="Approve the infrastructure">
    The dashboard opens once more showing the virtual machines Monk wants to create. Inspect and approve.
  </Step>

  <Step title="Deployment runs autonomously">
    Monk builds containers, provisions the infrastructure, deploys everything, and wires services together. Because Monk can see the running app, it detects and fixes issues on its own — API routing problems, for example.
  </Step>
</Steps>

A typical first deployment takes five to fifteen minutes. You will see progress updates in your agent's chat, and when it finishes Monk hands you a live HTTPS link to your app in production.

<img alt="Credential form in the local Monk dashboard" />

## You Are Live

When deployment finishes, Monk reports live URLs, service health, and estimated monthly cost. Your application is running on your cloud.

Try:

```
/monk show me what's running right now
```

```
/monk show me the logs
```

```
/monk how much is this costing me
```

<Card title="Autonomous operations" icon="wand-magic-sparkles" href="/getting-started/autonomous-operations">
  Your app is deployed — now learn how Monk keeps it running, sets up CI/CD, and monitors your services
</Card>

## Tips

If Monk asks too many questions, put more detail in your prompt. If you want to preview the plan before committing:

```
/monk analyze this project and show me what it needs
```

If a deployment fails:

```
/monk what went wrong with the deployment
```

Credential issues are the most common cause — double-check them in [Obtaining Credentials](/getting-started/obtaining-credentials).

## Cleaning Up

Done trying things out?

```
/monk delete the cluster
```

This stops and removes all cloud infrastructure Monk created, so you do not incur costs while idle. Nothing is lost — you can always deploy again later and Monk will bring it all back.

## Troubleshooting

<Card title="Troubleshooting" icon="wrench" href="/getting-started/troubleshooting-installation">
  Common issues and how to fix them
</Card>


# Get Started
Source: https://docs.monk.io/getting-started/get-started

Install Monk in your coding agent and go from prompt to production

Monk is a DevOps agent that plugs into your coding agent. You say what you want — `/monk deploy this project` — and Monk handles the rest: containers, infrastructure, databases, networking, and monitoring, on your own cloud. This page takes you from install to a running app.

<iframe title="Monk DevOps Agent (1/3): Give Your Coding Agent a DevOps Engineer in 2 Minutes" />

***

## 1. Install Monk in Your Agent

Monk installs as a plugin. One install gets you everything: a local `monk-agent` companion, the MCP connection to your agent, and the `monk` skill. There is no separate app to run and nothing to configure by hand.

<Info>
  The plugin installs `monk-agent` under `~/.monk/bin` and connects your agent to its MCP endpoint on `127.0.0.1:7419`. On first use it also installs the Monk CLI and daemon (`monk`, `monkd`) through your system package manager — Homebrew on macOS, apt or dnf on Linux, a dedicated Ubuntu WSL distro on Windows. You need network access to GitHub and `https://get.monk.io/stable`.
</Info>

<Tabs>
  <Tab title="Claude Code">
    Run these commands inside Claude Code:

    ```text theme={null}
    /plugin marketplace add monk-io/monk-plugin
    /plugin install monk@monk-plugins
    ```

    Reload the current session:

    ```text theme={null}
    /reload-plugins
    ```

    Then run `/mcp` — Monk should appear as an MCP server. If Claude Code asks you to authenticate, complete the browser sign-in flow from `/mcp`.
  </Tab>

  <Tab title="Cursor">
    Monk is listed in the [Cursor marketplace](https://cursor.com/marketplace/monk-io), so you can install it either way:

    * **From chat:** run this command in Cursor chat:

      ```text theme={null}
      /add-plugin monk
      ```

    * **From the UI:** open Cursor's **Customize** tab, find Monk under plugins (or start from the [marketplace listing](https://cursor.com/marketplace/monk-io)), and click install.

    Restart Cursor after installation, then open **Settings → Tools & MCP** and confirm Monk is listed and enabled. If Cursor reports that Monk needs login, use Cursor's MCP login flow for the `monk` server.

    <Note>
      `/add-plugin https://github.com/monk-io/monk-plugin` also works if you prefer installing straight from the GitHub repository.
    </Note>
  </Tab>

  <Tab title="Codex">
    Add the Monk marketplace from your terminal:

    ```bash theme={null}
    codex marketplace add monk-io/monk-plugin
    ```

    Start Codex in the project where you want to use Monk, then open the plugin browser:

    ```text theme={null}
    /plugins
    ```

    In the plugin browser, open the `monk-plugins` marketplace and install Monk. Restart Codex afterward so the Monk skill and MCP config are loaded, then verify with `/mcp`.

    If Codex reports that Monk needs authentication, run:

    ```bash theme={null}
    codex mcp login monk
    ```

    Complete the browser sign-in flow, then return to Codex and run `/mcp` again.

    <Note>
      The tested Codex CLI command is `codex marketplace add monk-io/monk-plugin`. Do not use `codex plugin marketplace add`; that is not the Codex CLI marketplace command.
    </Note>
  </Tab>

  <Tab title="Antigravity">
    Antigravity 2.0 (the standalone desktop app and CLI) uses a plugin directory instead of a marketplace command:

    ```sh theme={null}
    curl -fL https://get.monk.io/stable/monk-agent-plugin.zip -o /tmp/monk-agent-plugin.zip
    unzip /tmp/monk-agent-plugin.zip -d /tmp/monk-agent-plugin
    cp -r /tmp/monk-agent-plugin/.antigravity-plugin/ ~/.gemini/config/plugins/monk
    ~/.gemini/config/plugins/monk/scripts/start-monk-agent.sh
    ```

    The start script launches `monk-agent` in the background and writes a `monk` entry to `~/.gemini/config/mcp_config.json`. Open a project in Antigravity afterward — plugins load in workspace context, so the `monk` skill and MCP tools become available once a project is open. To authenticate, go to **Agent Settings → Customizations → Authenticate** next to the `monk` server.
  </Tab>
</Tabs>

Your coding agent should call Monk's MCP tools for infrastructure and runtime operations — not run direct `monk ...` shell commands against live Monk-managed infrastructure. Any other MCP-capable agent can connect to `http://127.0.0.1:7419/mcp`, but the hosts above are the supported, tested paths.

***

## 2. Sign In

Check that everything is wired up:

```
/monk check installation status
```

Monk inspects the local runtime, installs anything still missing, and walks you through the browser sign-in. You need a Monk account: the easiest way is to sign up at [monk.io/dashboard](https://monk.io/dashboard), or let the plugin prompt you — either way it's a 5-day free trial, no credit card required.

***

## 3. First Deployment

Open your project, then tell your coding agent:

```
/monk deploy this project
```

Monk analyzes the code, builds containers, provisions cloud infrastructure, and wires everything together. You will be asked to pick a team, enter credentials in the [local Monk dashboard](/getting-started/local-dashboard) (never in chat), and approve the infrastructure. Nothing else.

A typical first deployment finishes in five to fifteen minutes. When it is done you get live URLs, service health, and an estimated monthly cost.

<Card title="First deployment walkthrough" icon="rocket" href="/getting-started/first-deployment">
  Step-by-step guide with example prompts and common scenarios
</Card>

***

## 4. Autonomous Operations

After your first deployment, Monk keeps your system running and gives you tools to manage it without writing infrastructure code.

**Watcher** monitors your services around the clock and alerts you on Slack when something needs attention. **CI/CD** can be set up with a single prompt so every push triggers a new deployment. And you can scale, migrate, or reconfigure services at any time through natural language.

<CardGroup>
  <Card title="How autonomous operations work" icon="wand-magic-sparkles" href="/getting-started/autonomous-operations">
    What Monk handles on its own vs. what it asks you
  </Card>

  <Card title="Watcher setup" icon="bell" href="/prompting/watcher-setup">
    Continuous monitoring and Slack alerts
  </Card>

  <Card title="CI/CD setup" icon="arrows-rotate" href="/prompting/setting-up-cicd">
    Auto-deploy on every code push
  </Card>

  <Card title="Prompting guide" icon="lightbulb" href="/prompting/how-prompting-works">
    Tips for getting the most out of Monk
  </Card>
</CardGroup>

***

## 5. Connect Your Cloud

Monk follows a bring-your-own-infrastructure model. Everything runs on your cloud accounts. Monk asks for credentials when it needs them, but you can also set them up ahead of time.

<CardGroup>
  <Card title="AWS" icon="cloud" href="/getting-started/credentials-aws">
    IAM access key and secret key
  </Card>

  <Card title="Google Cloud" icon="cloud" href="/getting-started/credentials-gcp">
    Service account JSON key
  </Card>

  <Card title="Microsoft Azure" icon="cloud" href="/getting-started/credentials-azure">
    Service principal with client secret
  </Card>

  <Card title="DigitalOcean" icon="cloud" href="/getting-started/credentials-digitalocean">
    Personal access token
  </Card>

  <Card title="Hetzner" icon="cloud" href="/getting-started/credentials-hetzner">
    API token
  </Card>
</CardGroup>

Monk also integrates with service providers like MongoDB Atlas, Redis Cloud, Netlify, Vercel, and Auth0. Credentials for these are requested automatically when you first use them.

<Card title="All credentials and permissions" icon="key" href="/getting-started/obtaining-credentials">
  Full reference for every provider, including minimum IAM policies
</Card>

***

## 6. Getting Help

If something goes wrong, start by asking Monk directly — it has full context about your project and infrastructure.

For bugs, say `/monk report a bug` right in the chat — Monk collects environment details automatically and sends them straight to the engineering team (it can also file reports on its own when it hits a problem). You can also use the bug icon in the top-right corner of the [Monk dashboard](https://monk.io/dashboard).

<CardGroup>
  <Card title="Help & support channels" icon="life-ring" href="/getting-help">
    Bug reports, feature requests, community forum, and direct contact
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/getting-started/troubleshooting-installation">
    Common setup and connection issues
  </Card>
</CardGroup>

***

## Updating

| Agent       | Update path                                                                             |
| ----------- | --------------------------------------------------------------------------------------- |
| Claude Code | `/plugin update monk@monk-plugins`, then `/reload-plugins`                              |
| Cursor      | Update Monk from the Customize tab / plugin UI, then restart Cursor                     |
| Codex       | Open `/plugins` and update Monk from the `monk-plugins` marketplace, then restart Codex |
| Antigravity | Re-download the plugin bundle and repeat the copy step, then re-run the start script    |

## Uninstall

First remove the plugin from the host:

| Agent       | Uninstall path                                                                             |
| ----------- | ------------------------------------------------------------------------------------------ |
| Claude Code | Use Claude Code's plugin commands for `monk@monk-plugins`                                  |
| Cursor      | Remove Monk from Cursor's plugin UI                                                        |
| Codex       | Open `/plugins` and remove Monk from the `monk-plugins` marketplace                        |
| Antigravity | Delete `~/.gemini/config/plugins/monk` and its entry in `~/.gemini/config/mcp_config.json` |

Host uninstall removes the plugin, but not the local companion. To remove it, run the cleanup script from the [plugin repository](https://github.com/monk-io/monk-plugin):

```bash theme={null}
./scripts/uninstall-monk-agent.sh --yes
```

On Windows:

```powershell theme={null}
.\scripts\uninstall-monk-agent.ps1 -Yes
```

To also remove the Monk runtime components (CLI and daemon), add the runtime option: `--runtime` on macOS/Linux, `-Runtime` on Windows.


# Monk vs. Terraform, Kubernetes, and PaaS
Source: https://docs.monk.io/getting-started/how-monk-compares

Understand what Monk is by contrast — one orchestrator that manages infrastructure, workloads, networking, and APIs as a single live graph, instead of stitching together separate tools.

The fastest way to understand Monk is to look at what it replaces and why.

Most teams run production on a stack of specialized tools: **Terraform** (or Pulumi/OpenTofu) to provision infrastructure, **Kubernetes** to run containers, **Helm charts and operators** to extend the cluster, and a layer of human-written glue — pipelines, scripts, and runbooks — to wire it all together. Each tool is excellent at its slice. None of them owns the whole.

Monk takes the opposite approach. It is a single orchestrator that manages **infrastructure, workloads, networking, and third-party APIs as one continuously-reconciled graph** — the [live application graph](/getting-started/what-is-monk#more-than-deployment). The wiring between resources is a first-class part of that graph, not an afterthought left to a human.

<Info>
  **The one-line difference.** Terraform, Kubernetes, and a PaaS each manage part of your system. Monk manages all of it — and the connections between the parts — in one loop, on your cloud.
</Info>

## The short version

| Capability                                    | Terraform | Kubernetes | PaaS | Monk |
| --------------------------------------------- | :-------: | :--------: | :--: | :--: |
| Provisions cloud infrastructure               |     ✓     |      ✗     |   ◐  |   ✓  |
| Runs and schedules containers                 |     ✗     |      ✓     |   ✓  |   ✓  |
| Reconciles state continuously                 |     ✗     |      ✓     |   ✓  |   ✓  |
| Knows infra **and** workloads together        |     ✗     |      ✗     |   ◐  |   ✓  |
| Manages networking (VPC, firewalls, DNS, TLS) |     ◐     |      ◐     |   ◐  |   ✓  |
| Cross-cloud, hybrid, and on-prem              |     ◐     |      ◐     |   ✗  |   ✓  |
| Manages third-party SaaS/API lifecycle        |     ◐     |      ✗     |   ◐  |   ✓  |
| Runs on **your** cloud accounts               |     ✓     |      ✓     |   ✗  |   ✓  |
| Autonomous day-2 operation                    |     ✗     |      ◐     |   ◐  |   ✓  |

<sub>✓ designed for it · ◐ partial or within limits · ✗ out of scope</sub>

The rest of this page explains each comparison in detail.

## Monk vs. Terraform (and other IaC)

Infrastructure-as-Code tools are declarative templates for provisioning cloud resources. Terraform is outstanding at describing a desired infrastructure state and computing a plan to reach it.

Two things define its boundaries:

* **State is a plan-time snapshot.** Terraform reads its state when you run `plan`/`apply`. Between runs, reality drifts and Terraform doesn't notice until the next human-initiated run.
* **It doesn't know about your workloads.** Terraform provisions the database and the network, but the containers running your application — and how they depend on that infrastructure — live in a different tool entirely.

Monk keeps a **live state on its orchestrator** and reconciles it continuously, so drift is observed as it happens rather than discovered at the next apply. And because the same orchestrator manages the containers *and* the infrastructure beneath them, the dependency between a workload and its database, network, or DNS record is modeled — not left for a human to remember.

<Info>
  Monk tracks what it created versus what it merely discovered in your account, so it never destroys resources it didn't provision.
</Info>

## Monk vs. Kubernetes

Kubernetes is an excellent container orchestrator. It reconciles workload state continuously and self-heals within a cluster. Monk provides the same workload guarantees — scheduling, internal load balancing, service discovery, health and readiness checks, rolling and blue/green deployments, and autoscaling — but differs in three structural ways.

**Kubernetes' world ends at the cluster edge.** Its model assumes nodes and a network already exist and places workloads onto them. It has no native concept of *provision the VPC, the VM, or the managed database*. Monk treats a container as **one kind of resource on the same control plane** as the VM it runs on, the security group in front of it, and the managed database it talks to — so the whole application is one graph, not a workload layer floating above an unknown infrastructure layer.

**Networking stops at the cluster, too.** In-cluster networking is well covered, but the cloud network (VPCs, security groups, cross-cloud and on-prem connectivity) is out of scope by design. Monk derives networking — routing, firewalls, an [encrypted overlay](/features/networking), load balancing, ingress, and TLS — directly from your application's connection graph, spanning clouds and regions automatically.

**Isolation is subtractive.** The common pattern is one large multi-tenant cluster, with isolation carved out using namespaces, RBAC, network policies, and quotas. Monk gives each [environment its own cluster](/features/environments), isolated by construction, which is what makes cheap [per-branch preview environments](/features/capsules) practical.

<Card title="Containerization & Orchestration" icon="cubes" href="/features/containerization">
  How Monk's built-in orchestrator runs your workloads — without Kubernetes underneath.
</Card>

### "Why not just build Monk on Kubernetes?"

Because the unified graph can't exist inside it. Kubernetes deliberately decentralizes state across many independent controllers, each reconciling its own slice. Adding infrastructure (via Cluster API or Crossplane) makes infra into more controllers in the same cluster — coexisting reconcilers, not one dependency model spanning infrastructure, networking, workloads, and SaaS. To get a single authoritative graph with one reconciliation loop, the graph has to be the foundation, not an integration layer bolted on top. That is why Monk's orchestrator is built from the ground up rather than wrapping Kubernetes.

## Monk vs. PaaS (Heroku, Vercel, Railway, Render)

A Platform-as-a-Service is a fast path to production for applications that fit its mold. Monk gives you that same simplicity for *any* application — and simple apps stay just as frictionless. For a static site, Monk can even drive a PaaS like Vercel or Netlify for you, managing it as one more resource in your application graph.

The difference shows the moment you outgrow the box. A PaaS owns the underlying infrastructure and supports only the architectures it anticipated. When you need multiple services, a specific cloud provider, GPU workloads, a custom database, or a topology the platform didn't plan for, you hit a wall. Monk has no such ceiling.

Monk offers the convenience of a platform — one prompt to production, no manual configuration — with the openness of owning your own infrastructure:

* **Bring your own cloud.** Everything runs on your AWS, GCP, Azure, DigitalOcean, or Hetzner accounts. You own the infrastructure; Monk orchestrates it.
* **No fixed application shape.** Any language, any framework, any combination of services and providers.
* **Swap and move.** Change a self-hosted database for a managed one by swapping a package; move between clouds by extending the cluster and migrating — same application, same configuration, different infrastructure.

## Monk vs. an AI agent with scripts or MCP tools

As coding agents gain shell access and tool integrations, a natural question is whether deployment is just another thing an agent can script. The difference is **where the state lives**.

An agent with a shell *is* the control plane during a session: its plan, the resources it discovered, and its credentials all live in the context window — and they evaporate when the session ends. The next session starts from zero and has to rediscover what exists.

Monk inverts this. The agent is a **client of a deterministic control plane that holds the state**. That state survives sessions, restarts, and failures, so operations pick up exactly where they left off. The orchestrator computes a deterministic plan from desired versus observed state; the AI provides intent, not improvisation. This is the difference between "deploy once if nothing goes wrong" and operating a system on day two hundred.

<Card title="Autonomous Operations" icon="robot" href="/getting-started/autonomous-operations">
  What Monk does for you after the first deployment.
</Card>

## Summary

|                               | Mainstream stack                           | Monk                              |
| ----------------------------- | ------------------------------------------ | --------------------------------- |
| **Model**                     | Separate tools per layer                   | One orchestrator, one graph       |
| **State**                     | Fragmented (state file + etcd + operators) | Single live application graph     |
| **Reconciliation**            | Per-tool, mostly human-triggered           | Continuous, across all layers     |
| **The wiring between layers** | Human glue and runbooks                    | First-class edges in the graph    |
| **Infrastructure**            | Yours (Terraform) / theirs (PaaS)          | Yours (bring-your-own-cloud)      |
| **Operation**                 | Deploy, then operate by hand               | Deploy *and* operate autonomously |

<Card title="Get Started" icon="play" href="/getting-started/get-started">
  Install Monk, connect your coding agent, and deploy your first app — step by step.
</Card>


# The Local Dashboard
Source: https://docs.monk.io/getting-started/local-dashboard

Where you approve actions and enter secrets — never in agent chat

The Monk plugin runs a local companion, `monk-agent`, and it serves a dashboard in your browser at `http://127.0.0.1:7419` (loopback only; nothing is exposed to the network). This is where everything sensitive happens: approvals, credentials, and secrets go through this UI so they are never pasted into agent chat and never visible to the LLM.

You rarely open it by hand. When Monk needs something from you — a cloud API key during your first deployment, an approval before creating VMs — it opens the dashboard at the right form. You can also keep it open in a tab while the agent is running.

<img alt="Local dashboard Feed with a pending credential request" />

## Feed

The home screen. Everything waiting for you shows up here as an actionable item:

**Approvals** — accept or deny a privileged action the agent wants to take, such as deploys, cluster changes, or deletions.

**Credential requests** — provider forms for AWS, GCP, Azure, DigitalOcean, Hetzner, and service integrations. Enter values manually, authorize via the provider's OAuth flow, or upload a credentials JSON file (GCP, Azure) that fills the form for you.

**Secret prompts** — single values like database passwords, with a generator for secure random values.

**TLS certificates** — add domains and upload PEM certificates and keys.

Resolved items stay as history you can clear.

## Credentials

Your local vault view. Add or update secrets at a chosen scope (this workspace, all workspaces, or cluster scopes: account, org, project, environment) and see everything that is stored, grouped by scope. Values live in your OS keychain locally and encrypted via cloud KMS on clusters.

## Clusters

The saved clusters the agent knows about, with reachability, provider, and region. Select the active cluster, forget a record, or delete a cluster (delete asks for confirmation through the Feed). Creating a cluster opens a full review form — provider, region, instance type and count, optional GPUs — that you approve before anything is provisioned.

## Status

The bottom of the sidebar shows agent health at a glance: sign-in state, runtime reachability, install status, and the agent version. If something is off, `/monk check installation status` in your coding agent usually fixes it.

<Card title="First deployment" icon="rocket" href="/getting-started/first-deployment">
  See where the dashboard appears in the deploy flow
</Card>


# Connect Your Cloud
Source: https://docs.monk.io/getting-started/obtaining-credentials

Give Monk access to your cloud accounts

Monk follows a bring-your-own-infrastructure model. Everything runs on your cloud accounts — Monk provisions and manages resources on your behalf, but you own the infrastructure and control the credentials.

All credentials — cloud provider keys and service integration secrets alike — are entered through a form in the [local Monk dashboard](/getting-started/local-dashboard) that opens in your browser when Monk needs them. Depending on the provider you can type values in, authorize via OAuth, or upload a credentials JSON file. Nothing is ever pasted into agent chat.

Credentials are stored in your OS keychain on your machine and encrypted on your Monk cluster using your cloud provider's KMS — so your infrastructure can manage itself autonomously. They are never sent to Monk servers and never exposed to the LLM. See [Security](/features/security) for the full details.

## Pick Your Cloud

Monk asks for credentials automatically when you deploy, but you can also set them up ahead of time. Pick your cloud to get started:

<CardGroup>
  <Card title="AWS" icon="cloud" href="/getting-started/credentials-aws">
    IAM access key and secret key
  </Card>

  <Card title="Google Cloud" icon="cloud" href="/getting-started/credentials-gcp">
    Service account JSON key
  </Card>

  <Card title="Microsoft Azure" icon="cloud" href="/getting-started/credentials-azure">
    Service principal with client secret
  </Card>

  <Card title="DigitalOcean" icon="cloud" href="/getting-started/credentials-digitalocean">
    Personal access token
  </Card>

  <Card title="Hetzner" icon="cloud" href="/getting-started/credentials-hetzner">
    API token
  </Card>
</CardGroup>

## Service Providers

Monk also integrates with service providers for databases, hosting, authentication, CI/CD, and monitoring. Credentials for these are requested automatically the first time you use them.

| Service           | What you need                   | How it works                                                                             |
| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------------- |
| **Netlify**       | Nothing                         | OAuth — Monk opens a browser for authorization                                           |
| **Vercel**        | Personal access token           | [Settings → Tokens](https://vercel.com/account/tokens)                                   |
| **MongoDB Atlas** | Org name + API key pair         | [Access Manager → API Keys](https://cloud.mongodb.com)                                   |
| **Redis Cloud**   | Account key + user key          | Account Settings → API Keys                                                              |
| **Auth0**         | Domain + M2M client credentials | Applications → Create M2M app                                                            |
| **Cloudflare**    | API token                       | [My Profile → API Tokens](https://dash.cloudflare.com/profile/api-tokens)                |
| **GitHub**        | Fine-grained PAT                | [Developer Settings → Fine-grained tokens](https://github.com/settings/tokens?type=beta) |
| **Slack**         | Nothing                         | OAuth — Monk opens a browser for authorization ([details](/features/slack))              |

You do not need to configure these in advance. When you ask Monk to use a service — for example, `/monk deploy frontend to Netlify` — it will request the credentials it needs at that point.

## Managing Credentials

You can check, update, or remove credentials at any time through your agent or Monk directly:

```
/monk what credentials I have configured
```

```
/monk update my AWS credentials
```

```
/monk delete my Azure credentials
```

## Security Best Practices

**Use service accounts, not personal credentials.** Create a dedicated IAM user (AWS), service account (GCP), or service principal (Azure) for Monk. Service accounts can be rotated without affecting your personal access.

**Grant minimal permissions.** Each cloud guide above lists the exact permissions Monk needs. Do not use admin or root credentials.

**Rotate regularly.** Every 90 days for production credentials, immediately if potentially exposed, and whenever team members leave.

**Enable MFA** on all provider accounts that manage the service accounts Monk uses.

<Card title="First deployment" icon="rocket" href="/getting-started/first-deployment">
  Credentials ready? Deploy your first app
</Card>


# Troubleshooting
Source: https://docs.monk.io/getting-started/troubleshooting-installation

Fix common setup, connection, and deployment issues

This page covers problems you might hit while getting started with Monk — from installation through your first deployment. For runtime issues with already-deployed applications, see the [runtime troubleshooting guide](/prompting/troubleshooting).

<Tip>
  Your coding agent troubleshoots the plugin install for you — start with `/monk check installation status` and let it diagnose. The cases below are the ones that occasionally need your hands: upgrading the plugin, restarting the agent, or fixing something on your machine.
</Tip>

***

## Plugin Not Showing Up

If Monk does not appear in your coding agent after installing the plugin:

* Reload or restart the agent — most hosts only load plugins at startup.
* **Claude Code:** run `/reload-plugins`, then `/mcp` and confirm Monk is listed.
* **Cursor:** open **Settings → Tools & MCP** and confirm Monk is listed and enabled.
* **Codex:** run `/plugins` and confirm Monk is installed from the `monk-plugins` marketplace.
* **Antigravity:** confirm `~/.monk/bin/monk-agent status` reports running and that `~/.gemini/config/mcp_config.json` has a `monk` entry. A project must be open — plugins load in workspace context.

If the MCP server shows as offline, check that no other process is blocking `127.0.0.1:7419`, then restart the agent so the plugin can start `monk-agent` again.

***

## Sign-In Problems

When you sign in, Monk opens a browser tab for authentication. If the flow does not complete:

* Make sure your default browser is not blocking pop-ups from monk.io
* Try signing in with a different browser
* If you are behind a corporate proxy or VPN, check that `monk.io` and `auth.monk.io` are not blocked
* In Claude Code, run `/mcp` and use the MCP authentication prompt; in Codex, run `codex mcp login monk`; in Cursor, use the MCP login flow for the `monk` server

***

## Setup Incomplete

If the plugin installed but Monk reports that runtime setup is incomplete, ask your coding agent:

```
/monk check installation status
```

Monk inspects the local runtime — CLI, daemon, auth, workspace state — tells you what is wrong, and either fixes it or walks you through the fix.

Common causes: missing system dependencies, network connectivity, file permission issues, or the container runtime not running.

***

## Agent Does Not See Monk (MCP Issues)

If your coding agent cannot find Monk's MCP tools:

* Restart the agent after installing the plugin — some hosts only read MCP config at startup
* Run `/mcp` (Claude Code, Codex) or check **Settings → Tools & MCP** (Cursor) to verify the connection
* Confirm `monk-agent` is running: `~/.monk/bin/monk-agent status`
* Confirm nothing else is occupying `127.0.0.1:7419`

***

## Outdated Plugin or Runtime

The plugin requires a minimum `monkd` version and prompts to upgrade older installs — accept the prompt, or upgrade through your package manager, then restart your coding agent.

If problems appear after things used to work, update the plugin itself (see [update paths per agent](/getting-started/get-started#updating)) and restart or reload the agent — most hosts only pick up plugin changes on restart.

***

## Credential Errors

Monk reports credentials as invalid or deployment fails with permission errors:

* **Double-check the values** — copy-paste errors and trailing spaces are the most common cause
* **Verify in the provider console** — log into AWS/GCP/Azure/DigitalOcean and confirm the key is active and not expired
* **Check permissions** — compare attached policies against the minimum permissions listed in the [cloud credential guides](/getting-started/obtaining-credentials)
* **Azure client secret expired** — secrets have an expiry date; create a new one in App registrations
* **GCP key disabled** — check the service account status in IAM & Admin

Update credentials through your agent:

```
/monk update my AWS credentials
```

***

## Deployment Fails

If a deployment does not complete:

<Steps>
  <Step title="Ask your agent what went wrong">
    ```
    /monk what went wrong with the deployment
    ```

    Monk has full context about the failure and can usually pinpoint the cause.
  </Step>

  <Step title="Check credentials">
    Credential issues are the most common cause. See the section above.
  </Step>

  <Step title="Check cloud quotas">
    Some cloud providers have default limits on VMs, elastic IPs, or load balancers. If Monk reports a quota error, request a limit increase in your provider console.
  </Step>

  <Step title="Check region availability">
    Not all instance types are available in all regions. If Monk reports an instance type error, try a different region or let Monk choose.
  </Step>
</Steps>

***

## Cluster Creation Takes Too Long

Cloud provisioning typically takes 3–8 minutes. If it runs longer than 15 minutes:

* Cloud provider API throttling can slow things down during peak hours
* If it is stuck, ask Monk for status: `/monk what is happening with the cluster`
* As a last resort, cancel and retry — Monk cleans up partial infrastructure automatically

***

## OS-Specific Issues

<Tabs>
  <Tab title="macOS">
    **Xcode Command Line Tools errors**

    After a macOS upgrade, you may see "invalid active developer path" or Homebrew commands fail. Monk detects this automatically and reinstalls CLT — but if the auto-fix doesn't work:

    ```bash theme={null}
    xcode-select --install
    ```

    Then run `/monk check installation status` again.

    **Homebrew not found after install**

    On Apple Silicon Macs, Homebrew installs to `/opt/homebrew/bin`. On Intel Macs, it's `/usr/local/bin`. Make sure your shell profile exports the correct path, then restart your coding agent so it picks up the updated `PATH`.

    **Podman machine conflict**

    Monk needs its own Podman machine named "monk". If another Podman machine is already running, the installer asks you to stop it first. You can do this manually:

    ```bash theme={null}
    podman machine stop
    ```
  </Tab>

  <Tab title="Windows">
    **WSL not installed or no distributions**

    If the installer can't find WSL, it opens the Microsoft Store page. After installing WSL, restart your PC and rerun the installation check — Monk picks up from where it left off.

    **WSL distribution not responding**

    If the Monk WSL distribution stops working:

    ```powershell theme={null}
    wsl --terminate Ubuntu-Monk
    wsl -d Ubuntu-Monk
    ```

    Then run `/monk check installation status` again.

    **Sign-in redirect not working**

    If you're behind a corporate proxy, ensure `monk.io` and `auth.monk.io` are allowed.
  </Tab>

  <Tab title="Linux">
    **No supported package manager**

    Monk's auto-installer requires `apt` (Debian/Ubuntu) or `dnf` (Fedora/RHEL). If your distribution uses a different package manager (e.g., `pacman`, `zypper`), check [monk.io/downloads](https://monk.io/downloads) for manual install instructions.

    **Daemon won't start**

    The Monk daemon runs as a systemd service. If it fails to start:

    ```bash theme={null}
    sudo systemctl status monkd
    sudo journalctl -u monkd --no-pager -n 50
    ```

    Common causes: port already in use, missing systemd override file, or permission issues. Monk creates the override at `/etc/systemd/system/monkd.service.d/override.conf` — if it's missing, run `/monk check installation status` and enter your sudo password when prompted.

    **Repository or GPG key issues**

    If `apt update` or `dnf check-update` fails with signature errors, the Monk repository key may need refreshing. The installer handles this automatically on retry, but you can also re-add it manually:

    ```bash theme={null}
    curl -fsSL https://get.monk.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/monk-archive-keyring.gpg
    ```
  </Tab>
</Tabs>

***

## Container Runtime Issues

Monk builds containers automatically. If the build fails:

* Make sure the container runtime is running on your machine
* On Linux, confirm your user has the right permissions to run containers
* If the build fails on a specific dependency, ask Monk — it can often adjust the container configuration it generated
* Large projects may need more memory allocated to the container runtime

***

## Still Stuck?

Ask Monk directly through your coding agent. It has context about your environment and can often diagnose the problem faster than searching docs.

If nothing helps, run `/monk report a bug` — it collects environment details automatically and sends them to the engineering team.

<Card title="Help & support" icon="life-ring" href="/getting-help">
  Bug reports, feature requests, community forum, and direct contact
</Card>


# What is Monk?
Source: https://docs.monk.io/getting-started/what-is-monk

The DevOps agent for coding agents

Monk is a DevOps agent that works alongside your coding agent. Your agent writes the code; Monk takes it to production and keeps it running on your own cloud accounts, with infrastructure, containers, databases, networking, TLS, CI/CD, and monitoring handled for you. No Dockerfiles, no Terraform, no cloud consoles.

<iframe title="Monk DevOps Agent (1/3): Give Your Coding Agent a DevOps Engineer in 2 Minutes" />

<Card title="Get Started" icon="play" href="/getting-started/get-started">
  Install Monk, connect your coding agent, and deploy your first app — step by step
</Card>

## Everything After the Code

Coding agents solved writing software. Monk solves everything after. Monk plugs into **Claude Code, Cursor, OpenAI Codex, and Google Antigravity**, and from there you deploy and operate in plain language:

```
/monk deploy this project
/monk show me the logs
/monk set up CI/CD
/monk what is this costing me?
```

Your agent writes the application, Monk provisions real cloud infrastructure, deploys, wires services together, and validates end-to-end. When something breaks, Monk diagnoses the root cause in live system context, your agent fixes the code, Monk redeploys, and the cycle continues without you in the middle. This loop runs on day one for the initial build and keeps running on day two hundred for ongoing operations.

## Built for Safety Around AI Agents

Your coding agent talks to a deterministic orchestrator instead of a shell. Three properties are enforced by tooling, not by the LLM:

* **Credentials never touch the chat.** Cloud keys and secrets go into [Monk's dashboard](/getting-started/local-dashboard), stored in your OS keychain and encrypted with your cloud's KMS. No LLM ever sees them.
* **Destructive actions need your approval.** Deploys, cluster changes, and deletions wait for your explicit sign-off in Monk's UI — below the agent, where it can't approve itself.
* **Validation runs on real systems.** Monk provisions real infrastructure and verifies the running app end-to-end. No mocks, no simulations.

## More Than a Deploy Tool

Monk maintains a **live application graph**: a continuous model of your entire system, spanning workloads, infrastructure, databases, network topology, resource utilization, and costs. It is not reconstructed from logs after something breaks; the orchestrator maintains it in real time. That is what makes autonomous operation safe: Monk does not guess at your system's state — it knows it.

<Card title="How Monk Compares" icon="scale-balanced" href="/getting-started/how-monk-compares">
  See how Monk differs from Terraform, Kubernetes, and PaaS — and why it isn't built on top of them.
</Card>

## What It Manages

Monk orchestrates anything with a lifecycle and an API:

* **Cloud infrastructure** — VMs, networking, storage, load balancers, DNS, TLS certificates
* **Workloads** — containers, services, background workers, cron jobs
* **Databases and caches** — self-hosted or managed (RDS, Atlas, Redis Cloud, Neon)
* **APIs and SaaS integrations** — Auth0, Stripe, Cloudflare, and 200+ others
* **CI/CD** — generated pipelines that deploy on every push
* **Monitoring** — 24/7 Watcher with Slack alerts and autonomous triage

## Your Cloud, Your Keys

Monk deploys to **AWS**, **Google Cloud**, **Azure**, **DigitalOcean**, and **Hetzner** under a bring-your-own-cloud model, on your accounts. You own the infrastructure and control the credentials.

<Card title="All integrations" icon="puzzle-piece" href="/integrations">
  Browse the full list of supported services and providers
</Card>

## Works With Any Codebase

Any language, any framework, any combination. Web apps, REST and GraphQL APIs, microservices, monorepos, AI/ML workloads with GPU provisioning, static sites with backends. New projects and existing codebases alike. Monk analyzes the code, figures out what is needed, and handles the rest.

Team and organization management lives in the [Monk dashboard](https://monk.io/dashboard); approvals and secrets go through the [local dashboard](/getting-started/local-dashboard) on your machine.

<Card title="Get Started" icon="play" href="/getting-started/get-started">
  Ready? From install to production in one prompt
</Card>


# Integrations
Source: https://docs.monk.io/integrations

Discover integrations you can add to your stack. Browse by category and open any card to view the full guide.

## Available Integrations

### Networking

<CardGroup>
  <Card icon="puzzle-piece" title="Amazon API Gateway" href="/integrations/aws-api-gateway">
    API management service for building and securing APIs.
  </Card>

  <Card icon="puzzle-piece" title="BIRD Internet Routing Daemon" href="/integrations/monk-bird">
    Ready-to-run BIRD container template for BGP and dynamic routing protocol daemon.
  </Card>

  <Card icon="puzzle-piece" title="CoreDNS" href="/integrations/monk-coredns">
    Ready-to-run CoreDNS container template you can run directly or inherit to integrate a flexible DNS server into your infrastructure.
  </Card>

  <Card icon="puzzle-piece" title="Gost" href="/integrations/monk-gost">
    Ready-to-run Gost container template you can run directly or inherit to integrate a tunnel/proxy server into your stack.
  </Card>

  <Card icon="puzzle-piece" title="HAProxy" href="/integrations/monk-haproxy">
    Ready-to-run HAProxy container template you can run directly or inherit to integrate a high-performance load balancer and proxy into your infrastructure.
  </Card>
</CardGroup>

### CDN & DNS

<CardGroup>
  <Card icon="puzzle-piece" title="Amazon CloudFront" href="/integrations/aws-cloudfront">
    Global CDN and edge delivery for static and dynamic content.
  </Card>

  <Card icon="puzzle-piece" title="Cloudflare DNS and Tunnel" href="/integrations/cloudflare">
    Managed DNS and Cloudflare Tunnel for secure connectivity.
  </Card>

  <Card icon="puzzle-piece" title="DigitalOcean Domains" href="/integrations/digitalocean-domains">
    Managed DNS zones and records via DigitalOcean.
  </Card>
</CardGroup>

### Identity & Auth

<CardGroup>
  <Card icon="puzzle-piece" title="Amazon Cognito" href="/integrations/aws-cognito">
    Identity and access management for web and mobile apps.
  </Card>

  <Card icon="puzzle-piece" title="AWS IAM" href="/integrations/aws-iam">
    Identity and access management for AWS accounts and services.
  </Card>
</CardGroup>

### Database

<CardGroup>
  <Card icon="puzzle-piece" title="Amazon DynamoDB" href="/integrations/aws-dynamo-db">
    Fully managed NoSQL key-value and document database.
  </Card>

  <Card icon="puzzle-piece" title="Amazon RDS" href="/integrations/aws-rds">
    Managed relational databases (MySQL, Postgres, and more).
  </Card>

  <Card icon="puzzle-piece" title="Azure Cosmos DB" href="/integrations/azure-cosmosdb">
    Globally distributed, multi-model database service.
  </Card>

  <Card icon="puzzle-piece" title="DigitalOcean Databases" href="/integrations/digitalocean-database">
    Managed Postgres, MySQL, MongoDB, Valkey, Kafka, and OpenSearch.
  </Card>

  <Card icon="puzzle-piece" title="Google Cloud Platform" href="/integrations/gcp">
    Managed cloud databases and storage (Cloud SQL, Firestore, BigQuery, Cloud Storage, Memorystore).
  </Card>

  <Card icon="puzzle-piece" title="MariaDB" href="/integrations/mariadb">
    Ready-to-run MariaDB container template you can run directly or inherit to integrate a relational database into your stack.
  </Card>

  <Card icon="puzzle-piece" title="MongoDB Atlas" href="/integrations/mongodb-atlas">
    Managed MongoDB clusters, projects, and users.
  </Card>

  <Card icon="puzzle-piece" title="Aerospike" href="/integrations/monk-aerospike">
    Ready-to-run Aerospike container template you can run directly or inherit to integrate a high-performance NoSQL database into your stack.
  </Card>

  <Card icon="puzzle-piece" title="Apache Cassandra" href="/integrations/monk-cassandra">
    Ready-to-run Apache Cassandra container template you can run directly or inherit to integrate a distributed NoSQL database into your stack.
  </Card>

  <Card icon="puzzle-piece" title="DolphinDB" href="/integrations/monk-dophindb">
    Ready-to-run DolphinDB container template you can run directly or inherit to integrate a high-performance time-series database into your stack.
  </Card>

  <Card icon="puzzle-piece" title="Apache Druid" href="/integrations/monk-druid">
    Ready-to-run Apache Druid container stack you can run directly or inherit to integrate a real-time analytics database into your infrastructure.
  </Card>

  <Card icon="puzzle-piece" title="GridDB" href="/integrations/monk-griddb">
    Ready-to-run GridDB container template you can run directly or inherit to integrate a scalable time-series database optimized for IoT and big data into your stack.
  </Card>

  <Card icon="puzzle-piece" title="MongoDB" href="/integrations/monk-mongodb">
    Ready-to-run MongoDB container template you can run directly or inherit to integrate a document-oriented NoSQL database into your stack.
  </Card>

  <Card icon="puzzle-piece" title="Microsoft SQL Server" href="/integrations/monk-mssql">
    Ready-to-run Microsoft SQL Server container template you can run directly or inherit to integrate a relational database into your stack.
  </Card>

  <Card icon="puzzle-piece" title="OrientDB" href="/integrations/monk-orientdb">
    Ready-to-run OrientDB container template you can run directly or inherit to integrate a multi-model NoSQL database into your stack.
  </Card>

  <Card icon="puzzle-piece" title="Neon" href="/integrations/neon">
    Serverless Postgres with branching and autoscaling.
  </Card>

  <Card icon="puzzle-piece" title="PostgreSQL" href="/integrations/postgresql">
    Production-ready PostgreSQL runnable you can run directly or inherit to integrate a relational database into your stack.
  </Card>

  <Card icon="puzzle-piece" title="Redis Cloud" href="/integrations/redis-cloud">
    Managed Redis databases with Essentials and Pro tiers.
  </Card>
</CardGroup>

### Compute

<CardGroup>
  <Card icon="puzzle-piece" title="Amazon EC2" href="/integrations/aws-ec2">
    Compute capacity in the AWS cloud.
  </Card>
</CardGroup>

### Serverless

<CardGroup>
  <Card icon="puzzle-piece" title="AWS Lambda" href="/integrations/aws-lambda">
    Serverless compute to run code without provisioning servers.
  </Card>
</CardGroup>

### Storage

<CardGroup>
  <Card icon="puzzle-piece" title="Amazon S3" href="/integrations/aws-s3">
    Scalable object storage for any amount of data with built-in security, compliance, and performance features.
  </Card>

  <Card icon="puzzle-piece" title="DigitalOcean Spaces" href="/integrations/digitalocean-spaces">
    S3-compatible object storage on DigitalOcean.
  </Card>

  <Card icon="puzzle-piece" title="Hetzner Storage Box" href="/integrations/hetzner-storage-box">
    Managed Hetzner Storage Box for persistent file storage via SFTP, WebDAV, Samba, and rsync.
  </Card>
</CardGroup>

### Messaging

<CardGroup>
  <Card icon="puzzle-piece" title="Amazon SQS" href="/integrations/aws-sqs">
    Fully managed message queuing service.
  </Card>

  <Card icon="puzzle-piece" title="Apache Kafka" href="/integrations/monk-kafka">
    Ready-to-run Apache Kafka container stack you can run directly or inherit to integrate a distributed event streaming platform into your infrastructure.
  </Card>

  <Card icon="puzzle-piece" title="Eclipse Mosquitto" href="/integrations/monk-mosquitto">
    Ready-to-run Eclipse Mosquitto container template you can run directly or inherit to integrate an MQTT message broker into your IoT infrastructure.
  </Card>
</CardGroup>

### Devtools

<CardGroup>
  <Card icon="puzzle-piece" title="DigitalOcean GenAI Agent" href="/integrations/digitalocean-agent">
    Create and manage GenAI agents, deployments, and API keys.
  </Card>

  <Card icon="puzzle-piece" title="DigitalOcean Container Registry" href="/integrations/digitalocean-container-registry">
    Private Docker registries on DigitalOcean.
  </Card>
</CardGroup>

### Analytics Monitoring

<CardGroup>
  <Card icon="puzzle-piece" title="DigitalOcean Monitoring" href="/integrations/digitalocean-monitoring">
    Alerts for droplets, load balancers, and databases.
  </Card>
</CardGroup>

### Hosting & CI/CD

<CardGroup>
  <Card icon="puzzle-piece" title="Netlify" href="/integrations/netlify">
    Managed hosting, deploys, and forms for static sites.
  </Card>

  <Card icon="puzzle-piece" title="Vercel" href="/integrations/vercel">
    Lightning-fast frontend hosting, serverless functions, and global deployment platform.
  </Card>
</CardGroup>

### Payments & Billing

<CardGroup>
  <Card icon="puzzle-piece" title="Stripe" href="/integrations/stripe">
    Complete payment processing, subscription management, and webhook handling for modern applications.
  </Card>
</CardGroup>

### Cache

<CardGroup>
  <Card icon="puzzle-piece" title="Hazelcast" href="/integrations/monk-hazelcast">
    Ready-to-run Hazelcast container templates you can run directly or inherit to integrate an in-memory data grid into your applications.
  </Card>

  <Card icon="puzzle-piece" title="Memcached" href="/integrations/monk-memcached">
    Ready-to-run Memcached container template you can run directly or inherit to integrate a high-performance distributed memory caching system into your stack.
  </Card>

  <Card icon="puzzle-piece" title="Redis" href="/integrations/monk-redis">
    Ready-to-run Redis container template you can run directly or inherit to integrate an in-memory data store into your stack.
  </Card>
</CardGroup>

### Web Server

<CardGroup>
  <Card icon="puzzle-piece" title="Apache HTTP Server" href="/integrations/monk-httpd">
    Ready-to-run Apache HTTP Server container template you can run directly or inherit to integrate a web server into your infrastructure.
  </Card>

  <Card icon="puzzle-piece" title="Nginx" href="/integrations/monk-nginx">
    Ready-to-run Nginx container template you can run directly or inherit to integrate a high-performance web server and reverse proxy into your infrastructure.
  </Card>
</CardGroup>

### Database Tools

<CardGroup>
  <Card icon="puzzle-piece" title="pgAdmin" href="/integrations/monk-pgadmin">
    Ready-to-run pgAdmin container template for web-based PostgreSQL administration and management.
  </Card>
</CardGroup>

### Data Engineering

<CardGroup>
  <Card icon="puzzle-piece" title="Apache Airflow" href="/integrations/monk-airflow">
    Ready-to-run Apache Airflow container template for workflow orchestration and data pipeline management.
  </Card>
</CardGroup>

### Communication

<CardGroup>
  <Card icon="puzzle-piece" title="Chatwoot" href="/integrations/monk-chatwoot">
    Ready-to-run Chatwoot container stack you can run directly or inherit to integrate a customer engagement platform into your infrastructure.
  </Card>
</CardGroup>

### Observability

<CardGroup>
  <Card icon="puzzle-piece" title="ELK Stack" href="/integrations/monk-elk">
    Ready-to-run ELK Stack (Elasticsearch, Logstash, Kibana) container stack you can run directly or inherit to integrate logging and analytics into your infrastructure.
  </Card>

  <Card icon="puzzle-piece" title="Graphite" href="/integrations/monk-graphite">
    Ready-to-run Graphite container template you can run directly or inherit to integrate a time-series monitoring and graphing system into your infrastructure.
  </Card>
</CardGroup>

### Infrastructure

<CardGroup>
  <Card icon="puzzle-piece" title="etcd" href="/integrations/monk-etcd">
    Ready-to-run etcd container cluster you can run directly or inherit to integrate a distributed key-value store into your infrastructure.
  </Card>

  <Card icon="puzzle-piece" title="Apache ZooKeeper" href="/integrations/monk-zookeeper">
    Ready-to-run Apache ZooKeeper container template you can run directly or inherit to integrate distributed coordination and configuration management.
  </Card>
</CardGroup>

### DevOps

<CardGroup>
  <Card icon="puzzle-piece" title="JFrog Artifactory" href="/integrations/monk-artifactory">
    Ready-to-run JFrog Artifactory container template for universal artifact repository manager and DevOps platform.
  </Card>

  <Card icon="puzzle-piece" title="GitLab" href="/integrations/monk-gitlab">
    Ready-to-run GitLab container stack you can run directly or inherit to integrate a complete DevOps platform into your infrastructure.
  </Card>

  <Card icon="puzzle-piece" title="SonarQube" href="/integrations/monk-sonarqube">
    Ready-to-run SonarQube container template you can run directly or inherit to integrate continuous code quality inspection into your stack.
  </Card>
</CardGroup>

### Big Data

<CardGroup>
  <Card icon="puzzle-piece" title="Apache Hadoop" href="/integrations/monk-hadoop">
    Ready-to-run Apache Hadoop container stack you can run directly or inherit to integrate distributed data processing into your infrastructure.
  </Card>
</CardGroup>

### Data Integration

<CardGroup>
  <Card icon="puzzle-piece" title="Jitsu" href="/integrations/monk-jitsu">
    Ready-to-run Jitsu container template for open-source customer data platform and event collection.
  </Card>
</CardGroup>

### Monitoring

<CardGroup>
  <Card icon="puzzle-piece" title="LibreNMS" href="/integrations/monk-librenms">
    Ready-to-run LibreNMS container template you can run directly or inherit to integrate network monitoring and autodiscovery into your infrastructure.
  </Card>

  <Card icon="puzzle-piece" title="Prometheus + Grafana" href="/integrations/monk-prometheus-grafana">
    Ready-to-run Prometheus and Grafana stack template for comprehensive monitoring, metrics collection, and visualization.
  </Card>

  <Card icon="puzzle-piece" title="TIG Stack (Telegraf + InfluxDB + Grafana)" href="/integrations/monk-tig">
    Ready-to-run TIG stack template for time-series metrics collection, storage, and visualization.
  </Card>
</CardGroup>

### Development

<CardGroup>
  <Card icon="puzzle-piece" title="Radicle" href="/integrations/monk-radicle">
    Ready-to-run Radicle container template for peer-to-peer code collaboration and decentralized Git hosting.
  </Card>
</CardGroup>

### Analytics

<CardGroup>
  <Card icon="puzzle-piece" title="Apache Superset" href="/integrations/monk-superset">
    Ready-to-run Apache Superset container template for modern data exploration and business intelligence visualization.
  </Card>

  <Card icon="puzzle-piece" title="Trino (formerly Presto SQL)" href="/integrations/monk-trino">
    Ready-to-run Trino container template for fast distributed SQL query engine for big data analytics.
  </Card>
</CardGroup>

### AI/ML

<CardGroup>
  <Card icon="puzzle-piece" title="TensorFlow" href="/integrations/monk-tensorflow">
    Ready-to-run TensorFlow container template you can run directly or inherit to integrate machine learning and deep learning capabilities.
  </Card>
</CardGroup>

### CMS

<CardGroup>
  <Card icon="puzzle-piece" title="WordPress" href="/integrations/monk-wordpress">
    Ready-to-run WordPress container template you can run directly or inherit to integrate a CMS into your stack.
  </Card>
</CardGroup>

### Documentation

<CardGroup>
  <Card icon="puzzle-piece" title="DokuWiki" href="/integrations/monk-dokuwiki">
    Ready-to-run DokuWiki container template for simple, versatile, and standards-compliant wiki software.
  </Card>
</CardGroup>

### Social

<CardGroup>
  <Card icon="puzzle-piece" title="Mastodon" href="/integrations/monk-mastodon">
    Ready-to-run Mastodon container template you can run directly or inherit to integrate a decentralized social network into your infrastructure.
  </Card>
</CardGroup>

### Other Services

<CardGroup>
  <Card icon="puzzle-piece" title="Aws Ses" href="/integrations/aws-ses">
    Aws Ses integration with Monk
  </Card>
</CardGroup>


# Amazon API Gateway
Source: https://docs.monk.io/integrations/aws-api-gateway

API management service for building and securing APIs.

## What is this integration?

Amazon API Gateway lets you create, publish, maintain, monitor, and secure APIs at scale.

## What Monk manages

* API Gateway resources as provided by the entity definitions

## What the Agent can do and how to use it

* **API Creation**: Build REST APIs, HTTP APIs, and WebSocket APIs
* **Route Management**: Define routes, methods, and integration targets (Lambda, HTTP, etc.)
* **Authentication & Authorization**: Configure API keys, JWT authorizers, and Lambda authorizers
* **CORS Support**: Set up cross-origin resource sharing for web applications
* **Stage Management**: Deploy APIs to different stages (dev, staging, production)
* **Usage Plans**: Create and manage API usage plans with throttling and quotas
* **Custom Domains**: Configure custom domain names with SSL certificates

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Auth

* Uses AWS provider credentials configured via monk cluster provider add -p aws

## Links

* Provider docs: [https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html)

## Getting Started

1. Ensure AWS provider is added:

```bash theme={null}
monk cluster provider add -p aws
```

2. Define an HTTP API with a Lambda integration (save as api-gateway.yaml):

```yaml theme={null}
namespace: aws-api-gateway-examples

hello-function:
  defines: aws-lambda/lambda-function
  region: us-east-1
  blob_name: hello-world-code
  function_name: api-gw-hello-function
  runtime: nodejs20.x
  role: arn:aws:iam::123456789012:role/lambda-execution-role
  handler: index.handler
  services:
    function:
      protocol: custom

minimal-api:
  defines: aws-api-gateway/api-gateway
  region: us-east-1
  name: minimal-http-api
  protocol_type: HTTP
  routes:
    - path: /hello
      method: ANY
      integration:
        type: lambda
        function: \<- connection-target("lambda") entity-state get-member("function_arn")
  services:
    api:
      protocol: custom
  connections:
    lambda:
      runnable: aws-api-gateway-examples/hello-function
      service: function
  depends:
    wait-for:
      runnables:
        - aws-api-gateway-examples/hello-function
      timeout: 120
```

3. Create/update:

```bash theme={null}
monk update aws-api-gateway-examples/minimal-api
monk describe aws-api-gateway-examples/minimal-api
```


# Amazon CloudFront
Source: https://docs.monk.io/integrations/aws-cloudfront

Global CDN and edge delivery for static and dynamic content.

## What is this integration?

Amazon CloudFront is a content delivery network that accelerates delivery of your content through edge locations.

## What Monk manages

* Distribution and related configuration

## What the Agent can do and how to use it

* **Distribution Management**: Create, update, and delete CloudFront distributions
* **Origin Configuration**: Configure S3 buckets, HTTP servers, or custom origins as content sources
* **Cache Behaviors**: Set up caching rules, compression, and content optimization
* **Security**: Configure SSL/TLS certificates, geographic restrictions, and access controls
* **Invalidations**: Clear cached content and force fresh delivery
* **Monitoring**: Enable CloudFront access logging and real-time metrics

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Auth

* Uses AWS provider credentials configured via monk cluster provider add -p aws

## Links

* Provider docs: [https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html)

## Getting Started

1. Ensure AWS provider is added:

```bash theme={null}
monk cluster provider add -p aws
```

2. Define a distribution (save as cloudfront.yaml):

```yaml theme={null}
namespace: aws-cloudfront-examples

basic-s3-distribution:
  defines: aws-cloudfront/distribution
  region: us-east-1
  enabled: true
  default_root_object: index.html
  origins:
    - id: s3-origin
      domain_name: my-website-bucket.s3.amazonaws.com
      s3_origin_config:
        origin_access_identity: ""
  default_cache_behavior:
    target_origin_id: s3-origin
    viewer_protocol_policy: redirect-to-https
    allowed_methods: [GET, HEAD]
    cached_methods: [GET, HEAD]
```

3. Create/update:

```bash theme={null}
monk update aws-cloudfront-examples/basic-s3-distribution
monk describe aws-cloudfront-examples/basic-s3-distribution
```


# Amazon Cognito
Source: https://docs.monk.io/integrations/aws-cognito

Identity and access management for web and mobile apps.

## What is this integration?

Amazon Cognito simplifies adding authentication, authorization, and user management to applications.

## What Monk manages

* User Pool, Identity Provider, Identity Pool, User Pool Client, User Pool Domain

## What the Agent can do and how to use it

* **User Pool Management**: Create and configure user pools for authentication
* **Identity Providers**: Set up social sign-in (Google, Facebook, etc.) and SAML/OIDC providers
* **Identity Pools**: Configure federated identities for temporary AWS credentials
* **User Pool Clients**: Create applications and configure OAuth flows
* **User Management**: Enable self-service sign-up, password policies, and account recovery
* **Custom Domains**: Set up custom authentication domains with SSL certificates
* **User Groups**: Create and manage user groups with role-based permissions

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Auth

* Uses AWS provider credentials configured via monk cluster provider add -p aws

## Links

* Provider docs: [https://docs.aws.amazon.com/cognito/](https://docs.aws.amazon.com/cognito/)


# Amazon DynamoDB
Source: https://docs.monk.io/integrations/aws-dynamo-db

Fully managed NoSQL key-value and document database.

## What is this integration?

Amazon DynamoDB is a fast, flexible NoSQL database service for any scale.

## What Monk manages

* Table: create, update, delete

## What the Agent can do and how to use it

* **Table Management**: Create, update, and delete DynamoDB tables with custom schemas
* **Global Tables**: Configure multi-region replication for global applications
* **Backup & Restore**: Enable point-in-time recovery and on-demand backups
* **Scaling**: Configure auto-scaling for read/write capacity (provisioned mode)
* **Streams**: Enable DynamoDB Streams for change data capture
* **TTL**: Configure time-to-live settings for automatic item expiration
* **Indexes**: Create and manage global secondary indexes (GSI) and local secondary indexes (LSI)

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Auth

* Uses AWS provider credentials configured via monk cluster provider add -p aws

## Links

* Provider docs: [https://docs.aws.amazon.com/amazondynamodb/](https://docs.aws.amazon.com/amazondynamodb/)

## Getting Started

1. Ensure AWS provider is added:

```bash theme={null}
monk cluster provider add -p aws
```

2. Define a table (save as dynamodb.yaml):

```yaml theme={null}
namespace: aws-dynamo-db-example

simple-table:
  defines: aws-dynamo-db/dynamo-db-table
  region: us-east-1
  table_name: simple-example-table
  attribute_definitions:
    - AttributeName: id
      AttributeType: S
  key_schema:
    - AttributeName: id
      KeyType: HASH
  billing_mode: PAY_PER_REQUEST
```

3. Create/update:

```bash theme={null}
monk update aws-dynamo-db-example/simple-table
monk describe aws-dynamo-db-example/simple-table
```

## Backup & Restore Actions

DynamoDB supports **Point-in-Time Recovery (PITR)** with 35-day continuous backups and **On-Demand Backups** that are retained indefinitely.

| Action               | Description                         |
| -------------------- | ----------------------------------- |
| `get-backup-info`    | View PITR status and recent backups |
| `create-snapshot`    | Create an on-demand backup          |
| `list-snapshots`     | List available backups              |
| `describe-snapshot`  | Get detailed backup info            |
| `delete-snapshot`    | Delete an on-demand backup          |
| `restore`            | Restore to a new table              |
| `get-restore-status` | Check restore progress              |

```bash theme={null}
# View backup configuration
monk do my-app/my-table/get-backup-info

# Create an on-demand backup
monk do my-app/my-table/create-snapshot backup_name="pre-migration"

# List available backups
monk do my-app/my-table/list-snapshots

# Restore from backup to new table
monk do my-app/my-table/restore backup_arn="arn:aws:dynamodb:..." target_table="restored-table"

# Point-in-time restore (latest)
monk do my-app/my-table/restore use_latest="true" target_table="restored-table"

# Check restore status
monk do my-app/my-table/get-restore-status target_table="restored-table"
```

**Note:** DynamoDB restore always creates a **new table** - it does not overwrite the source.

### Enable PITR in Definition

```yaml theme={null}
my-table:
  defines: aws-dynamo-db/dynamo-db-table
  region: us-east-1
  table_name: production-table
  point_in_time_recovery_enabled: true  # Enable 35-day continuous backup
  deletion_protection_enabled: true
  # ... key schema ...
```


# Amazon EC2
Source: https://docs.monk.io/integrations/aws-ec2

Compute capacity in the AWS cloud.

## What is this integration?

Amazon EC2 provides secure, resizable compute capacity.

## What Monk manages

* VPC, Subnet, Security Group

## What the Agent can do and how to use it

* **VPC Management**: Create, configure, and delete Virtual Private Clouds
* **Subnet Configuration**: Set up public, private, and isolated subnets across availability zones
* **Security Groups**: Define inbound/outbound traffic rules and network access controls
* **Internet Gateways**: Configure internet connectivity and routing
* **Route Tables**: Manage routing between subnets and external networks
* **Network ACLs**: Set up stateless network access control lists
* **NAT Gateways**: Enable private subnet internet access for updates and external APIs
* **VPC Endpoints**: Create private connections to AWS services without internet gateways

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Auth

* Uses AWS provider credentials configured via monk cluster provider add -p aws

## Getting Started

1. Ensure AWS provider is added:

```bash theme={null}
monk cluster provider add -p aws
```

2. Define networking primitives (save as ec2.yaml):

```yaml theme={null}
namespace: aws-ec2-examples

vpc:
  defines: aws-ec2/vpc
  region: us-east-1
  cidr_block: 10.1.0.0/16

subnet:
  defines: aws-ec2/subnet
  region: us-east-1
  vpc_id: \<- connection-target("vpc") entity-state get-member("vpc_id")
  cidr_block: 10.1.1.0/24

sg:
  defines: aws-ec2/security-group
  region: us-east-1
  vpc_id: \<- connection-target("vpc") entity-state get-member("vpc_id")
  group_name: demo-sg
  description: Demo security group
```

3. Create/update:

```bash theme={null}
monk update aws-ec2-examples/vpc
monk update aws-ec2-examples/subnet
monk update aws-ec2-examples/sg
```


# AWS IAM
Source: https://docs.monk.io/integrations/aws-iam

Identity and access management for AWS accounts and services.

## What is this integration?

AWS Identity and Access Management (IAM) enables you to manage access to AWS services and resources securely.

## What Monk manages

* IAM Policy, IAM Role, IAM User

## What the Agent can do and how to use it

* **User Management**: Create, update, and delete IAM users with access keys and passwords
* **Role Creation**: Define IAM roles with trust policies and managed policies
* **Policy Management**: Create custom policies with JSON policy documents and attach to users/roles
* **Group Administration**: Organize users into groups and manage group permissions
* **Access Key Rotation**: Generate and manage access keys with rotation capabilities
* **Policy Validation**: Validate policy syntax and check for overly permissive permissions
* **Service Accounts**: Create service accounts for application authentication
* **Cross-Account Access**: Configure roles for cross-account resource access

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Auth

* Uses AWS provider credentials configured via monk cluster provider add -p aws

## Getting Started

1. Ensure AWS provider is added:

```bash theme={null}
monk cluster provider add -p aws
```

2. Define a simple policy (save as iam.yaml):

```yaml theme={null}
namespace: iam-examples

s3-readonly-policy:
  defines: aws/iam/iam-policy
  region: us-east-1
  policy_name: S3ReadOnlyAccess
  policy_document:
    Version: "2012-10-17"
    Statement:
      - Effect: Allow
        Action:
          - s3:GetObject
          - s3:ListBucket
        Resource:
          - "arn:aws:s3:::my-application-bucket/*"
          - "arn:aws:s3:::my-application-bucket"
```

3. Create/update:

```bash theme={null}
monk update iam-examples/s3-readonly-policy
monk describe iam-examples/s3-readonly-policy
```


# AWS Lambda
Source: https://docs.monk.io/integrations/aws-lambda

Serverless compute to run code without provisioning servers.

## What is this integration?

AWS Lambda lets you run code without provisioning or managing servers.

## What Monk manages

* Lambda Function and related configuration

## What the Agent can do and how to use it

* **Function Management**: Create, update, and delete Lambda functions
* **Runtime Configuration**: Set runtime environments (Node.js, Python, Java, Go, etc.)
* **Memory & CPU**: Configure memory allocation and CPU settings
* **Environment Variables**: Manage function environment variables and secrets
* **Triggers**: Configure event source mappings (S3, SNS, SQS, DynamoDB streams)
* **Permissions**: Set up IAM roles and execution policies
* **Versions & Aliases**: Manage function versions and create aliases for deployment
* **Concurrency**: Configure reserved and provisioned concurrency settings

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Auth

* Uses AWS provider credentials configured via monk cluster provider add -p aws

## Getting Started

1. Ensure AWS provider is added:

```bash theme={null}
monk cluster provider add -p aws
```

2. Define a Lambda function (save as lambda.yaml):

```yaml theme={null}
namespace: aws-lambda-examples

hello-world:
  defines: aws-lambda/lambda-function
  region: us-east-1
  blob_name: hello-world-code
  function_name: hello-world-function
  runtime: nodejs20.x
  role: arn:aws:iam::123456789012:role/lambda-execution-role
  handler: index.handler
```

3. Create/update:

```bash theme={null}
monk update aws-lambda-examples/hello-world
monk describe aws-lambda-examples/hello-world
```


# Amazon RDS
Source: https://docs.monk.io/integrations/aws-rds

Managed relational databases (MySQL, Postgres, and more).

## What is this integration?

Amazon RDS makes it easy to set up, operate, and scale relational databases in the cloud.

## What Monk manages

* DB instance, subnet group, security group

## What the Agent can do and how to use it

* **Database Creation**: Provision MySQL, PostgreSQL, MariaDB, Oracle, and SQL Server instances
* **Backup & Recovery**: Configure automated backups, point-in-time recovery, and manual snapshots
* **Scaling**: Modify instance types, storage, and enable read replicas for scaling
* **High Availability**: Set up Multi-AZ deployments for automatic failover
* **Security**: Configure VPC isolation, security groups, and encryption at rest
* **Maintenance**: Schedule and manage automated maintenance windows
* **Monitoring**: Enable Enhanced Monitoring and Performance Insights
* **Parameter Groups**: Customize database engine parameters and configurations

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Obtaining AWS Credentials

AWS RDS uses your AWS account credentials. You'll need AWS access keys with appropriate permissions.

### What You'll Need

* **AWS Access Key ID**
* **AWS Secret Access Key**
* **Optional:** Default region (e.g., `us-east-1`)

### Step-by-Step

1. **Log into AWS Console** at [https://console.aws.amazon.com](https://console.aws.amazon.com)
2. Navigate to **IAM** → **Users**
3. Select your IAM user or **Create user** for Monk
4. Go to **Security credentials** tab
5. Click **Create access key**
6. Choose use case: **"Third-party service"**
7. Click **Next** → **Create access key**
8. **Copy Access Key ID** and **Secret Access Key**
9. Save them securely - secret key shown only once

### Required IAM Permissions

Attach these AWS managed policies to the user:

* `AmazonRDSFullAccess` - For RDS management
* `AmazonEC2FullAccess` - For VPC and security groups
* `IAMReadOnlyAccess` - For verification

Or create a custom policy with: RDS, EC2 (VPC, security groups), and IAM read access.

### Providing to Monk

When deploying with AWS RDS, ask Monk:

```
deploy to AWS with RDS for PostgreSQL
```

```
use AWS RDS MySQL database
```

Monk will request AWS credentials if not already configured.

### Security Best Practices

✅ **Use IAM user for Monk** - Not your personal admin account
✅ **Enable MFA** on the account managing the IAM user
✅ **Rotate keys every 90 days**
✅ **Monitor with CloudTrail** - Track API usage
✅ **Use minimal permissions** - Only grant what Monk needs

## Auth

* Uses AWS provider credentials (Access Key ID and Secret Access Key)

## Getting Started

1. Provide AWS credentials to Monk when deploying:

```
deploy with AWS RDS
```

### CLI Reference (Advanced)

For manual provider configuration:

```bash theme={null}
monk cluster provider add -p aws
```

2. Define an RDS instance (save as rds.yaml):

```yaml theme={null}
namespace: my-app

my-mysql-db:
  defines: aws-rds/rds-instance
  region: us-east-1
  db_instance_identifier: my-mysql-instance
  db_instance_class: db.t3.micro
  engine: mysql
  master_username: admin
  password_secret_ref: my-mysql-db-password
```

3. Create/update:

```bash theme={null}
monk update my-app/my-mysql-db
monk describe my-app/my-mysql-db
```

## Backup & Snapshot Actions

| Action               | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `get-backup-info`    | View backup retention, window, and automated backup status |
| `create-snapshot`    | Create an on-demand manual snapshot                        |
| `list-snapshots`     | List available snapshots (manual and automated)            |
| `describe-snapshot`  | Get detailed information about a specific snapshot         |
| `delete-snapshot`    | Delete a manual snapshot                                   |
| `restore`            | Restore to a new RDS instance from a snapshot              |
| `get-restore-status` | Check status of a restored instance                        |

```bash theme={null}
# View backup configuration
monk do my-app/my-mysql-db/get-backup-info

# Create a snapshot before maintenance
monk do my-app/my-mysql-db/create-snapshot snapshot_id="pre-upgrade"

# List available snapshots
monk do my-app/my-mysql-db/list-snapshots

# Restore to a new instance
monk do my-app/my-mysql-db/restore snapshot_id="pre-upgrade" target_id="restored-db"

# Check status of restored instance
monk do my-app/my-mysql-db/get-restore-status instance_id="restored-db"
```


# Amazon S3
Source: https://docs.monk.io/integrations/aws-s3

Scalable object storage for any amount of data with built-in security, compliance, and performance features.

# Amazon S3 Integration

Seamlessly manage AWS S3 buckets, objects, and storage configurations directly through Monk.

## Why Amazon S3?

**Amazon S3** is the gold standard for cloud object storage, offering:

* **Virtually unlimited scalability** - Store anything from a few files to exabytes of data
* **99.999999999% durability** - Your data is safe with 11 9's of durability
* **Global accessibility** - Serve content worldwide with edge locations
* **Built-in security** - Encryption at rest and in transit, access controls, and compliance features
* **Cost-effective** - Pay only for what you use with multiple storage tiers

**Perfect for:**

* File storage and media hosting
* Data lakes and analytics
* Backup and disaster recovery
* Static website hosting
* Application data storage

## What Monk Manages

Monk handles the complete lifecycle of your S3 resources:

* **Buckets**: Create, configure, update, and delete storage buckets
* **Bucket policies**: Manage access permissions and security policies
* **Versioning**: Enable/disable object versioning for data protection
* **Lifecycle rules**: Automate data transitions between storage classes
* **CORS configuration**: Set up cross-origin resource sharing
* **Encryption**: Configure server-side encryption settings
* **Public access**: Control public read/write permissions

## Step-by-Step Integration Guide

### Step 1: Set Up AWS Provider

First, ensure your AWS credentials are configured:

```bash theme={null}
# Add AWS as a provider (Monk will prompt for credentials)
monk cluster provider add -p aws

# Verify the provider is configured
monk cluster providers
```

### Step 2: Create Your First S3 Bucket

Create a file named `s3-storage.yaml`:

```yaml theme={null}
namespace: my-app-storage

# Production-ready bucket with security best practices
app-data-bucket:
  defines: aws-s3/s3-bucket
  region: us-east-1
  bucket_name: my-app-production-data-2024
  versioning: true
  block_public_access: true

  # Lifecycle rules for cost optimization
  lifecycle_rules:
    - id: transition-to-ia
      status: enabled
      filter:
        prefix: "archives/"
      transitions:
        - days: 30
          storage_class: STANDARD_IA
        - days: 90
          storage_class: GLACIER

  # Server-side encryption
  server_side_encryption:
    enabled: true
    kms_key_id: null  # Use S3-managed keys

# Static assets bucket for a website
website-assets:
  defines: aws-s3/s3-bucket
  region: us-east-1
  bucket_name: my-app-static-assets
  block_public_access: false

  # CORS configuration for web access
  cors_configuration:
    cors_rules:
      - allowed_headers: ["*"]
        allowed_methods: ["GET", "HEAD"]
        allowed_origins: ["https://myapp.com", "https://www.myapp.com"]
        max_age_seconds: 3600

  # Website hosting configuration
  website_configuration:
    index_document: "index.html"
    error_document: "error.html"
```

### Step 3: Deploy and Manage

Deploy your S3 resources:

```bash theme={null}
# Create/update the buckets
monk update my-app-storage/app-data-bucket
monk update my-app-storage/website-assets

# Check the status
monk describe my-app-storage/app-data-bucket

# List all S3 resources
monk ps -a | grep s3
```

### Step 4: Upload and Access Files

Once deployed, you can interact with your S3 buckets:

```bash theme={null}
# Upload files to your bucket
aws s3 cp myfile.txt s3://my-app-production-data-2024/

# List objects
aws s3 ls s3://my-app-production-data-2024/

# Enable public read access for website assets
aws s3 cp index.html s3://my-app-static-assets/ --acl public-read
```

## Advanced Configuration Examples

### Multi-Region Setup

```yaml theme={null}
namespace: global-storage

us-east-bucket:
  defines: aws-s3/s3-bucket
  region: us-east-1
  bucket_name: my-app-east-data

us-west-bucket:
  defines: aws-s3/s3-bucket
  region: us-west-2
  bucket_name: my-app-west-data
  replication_configuration:
    role_arn: "arn:aws:iam::ACCOUNT:role/s3-replication-role"
    rules:
      - id: replicate-everything
        status: enabled
        destination:
          bucket: "arn:aws:s3:::my-app-west-data"
```

### Data Lake Configuration

```yaml theme={null}
namespace: data-lake

analytics-bucket:
  defines: aws-s3/s3-bucket
  region: us-east-1
  bucket_name: my-company-data-lake

  # Partitioning for analytics
  tags:
    Environment: "production"
    Purpose: "data-lake"
    DataClassification: "internal"

  # Access logging for compliance
  logging:
    destination_bucket_name: my-company-logs
    log_file_prefix: "s3-access-logs/"

  # Intelligent tiering for cost optimization
  intelligent_tiering:
    configurations:
      - id: auto-tiering
        status: enabled
        tierings:
          - days: 0
            access_tier: INTELLIGENT_TIERING
```

## Troubleshooting & Tips

### Common Issues

**Bucket already exists error:**

```bash theme={null}
# Check if bucket exists and import it instead
monk describe my-bucket  # If it exists, use import instead of create
```

**Access denied errors:**

```bash theme={null}
# Verify AWS credentials and permissions
aws sts get-caller-identity
monk cluster providers  # Check provider status
```

**High costs:**

* Enable lifecycle rules to move old data to cheaper storage classes
* Use S3 Analytics to identify infrequently accessed data
* Consider S3 Intelligent-Tiering for automatic cost optimization

### Best Practices

1. **Security First**: Always enable encryption and block public access by default
2. **Naming Convention**: Use consistent, descriptive bucket names
3. **Lifecycle Management**: Set up automatic data transitions to save costs
4. **Cross-Region Replication**: For global applications, replicate critical data
5. **Monitoring**: Enable S3 access logging and CloudTrail for audit trails

### Cost Optimization

```yaml theme={null}
# Example of cost-optimized bucket configuration
cost-effective-bucket:
  defines: aws-s3/s3-bucket
  region: us-east-1
  bucket_name: my-app-cost-optimized

  lifecycle_rules:
    - id: move-to-ia-after-30-days
      status: enabled
      transitions:
        - days: 30
          storage_class: STANDARD_IA
    - id: move-to-glacier-after-90-days
      status: enabled
      transitions:
        - days: 90
          storage_class: GLACIER
    - id: delete-after-7-years
      status: enabled
      expiration:
        days: 2555  # 7 years
```

## Real-World Use Cases

### E-commerce Platform

Store product images, user uploads, and order data with automatic lifecycle management for old orders.

### Media & Entertainment

Host videos, images, and streaming content with CloudFront integration for global delivery.

### SaaS Application

Store user files, application data, and backups with encryption and compliance features.

### Data Analytics

Build data lakes with partitioned storage and analytics integration for business intelligence.

## Integration with Other Services

S3 works seamlessly with other AWS services:

* **CloudFront**: Global content delivery network
* **Lambda**: Serverless compute for data processing
* **Athena**: Query data directly in S3
* **Redshift**: Data warehousing with S3 as the data lake
* **EC2**: Mount S3 buckets as file systems

## Support & Resources

* **AWS Documentation**: [S3 Developer Guide](https://docs.aws.amazon.com/s3/)
* **Pricing Calculator**: [AWS S3 Pricing](https://calculator.aws/)
* **Best Practices**: [S3 Performance Optimization](https://aws.amazon.com/blogs/aws/amazon-s3-performance-tips-tricks/)

Need help? Check the [Monk Community](https://community.monk.io) or [AWS Support](https://aws.amazon.com/support).


# Amazon SQS
Source: https://docs.monk.io/integrations/aws-sqs

Fully managed message queuing service.

## What is this integration?

Amazon SQS offers a reliable, scalable message queue for decoupling microservices.

## What Monk manages

* Queue: create, update, delete

## What the Agent can do and how to use it

* **Queue Management**: Create, configure, and delete message queues
* **Message Operations**: Send, receive, and delete messages with visibility timeouts
* **Queue Types**: Standard queues (at-least-once delivery) and FIFO queues (exactly-once, ordered)
* **Dead Letter Queues**: Configure DLQs for failed message handling
* **Batching**: Send and receive messages in batches for efficiency
* **Attributes**: Set message attributes, timers, and priority levels
* **Polling**: Configure long/short polling for message retrieval
* **Redrive Policies**: Set up automatic redrive from DLQ back to source queue

Steps:

1. Ensure AWS provider is added: monk cluster provider add -p aws
2. monk update \<namespace>/\<name>

## Auth

* Uses AWS provider credentials configured via monk cluster provider add -p aws

## Getting Started

1. Ensure AWS provider is added:

```bash theme={null}
monk cluster provider add -p aws
```

2. Define a queue (save as sqs.yaml):

```yaml theme={null}
namespace: aws-sqs-examples

standard-queue:
  defines: aws-sqs/sqs-queue
  region: us-east-1
  queue_name: standard-example-queue
```

3. Create/update:

```bash theme={null}
monk update aws-sqs-examples/standard-queue
monk describe aws-sqs-examples/standard-queue
```


# Azure Cosmos DB
Source: https://docs.monk.io/integrations/azure-cosmosdb

Globally distributed, multi-model database service.

## What is this integration?

Azure Cosmos DB is a globally distributed, multi-model database service that supports NoSQL, MongoDB, and other APIs with guaranteed low latency at any scale.

## What Monk manages

* Database Account (with geo-replication, consistency policies, backup configuration)
* Database (with throughput provisioning)
* Access List (VNet service endpoints)

## What the Agent can do and how to use it

* **Account Management**: Create and manage Cosmos DB accounts with multiple APIs (NoSQL, MongoDB)
* **Global Distribution**: Configure multi-region replication with automatic failover
* **Consistency Levels**: Set consistency from Strong to Eventual based on requirements
* **Backup & Recovery**: Configure continuous or periodic backup, point-in-time restore
* **Throughput**: Provision manual or autoscale throughput for databases
* **Security**: Configure VNet access rules, private endpoints, and authentication

Steps:

1. Ensure Azure credentials are configured (az login or service principal)
2. monk update \<namespace>/\<name>

## Auth

* Uses Azure credentials configured via:
  * Azure CLI (`az login`)
  * Service Principal (AZURE\_CLIENT\_ID, AZURE\_CLIENT\_SECRET, AZURE\_TENANT\_ID)
  * Managed Identity (when running on Azure)

## Getting Started

1. Define a Cosmos DB account (save as cosmos.yaml):

```yaml theme={null}
namespace: my-app

cosmos-account:
  defines: azure-cosmosdb/database-account
  subscription_id: "your-subscription-id"
  resource_group_name: "my-resource-group"
  account_name: "my-cosmos-account"
  locations:
    - location_name: "East US"
      failover_priority: 0
  consistency_policy:
    default_consistency_level: "Session"
  backup_policy:
    backup_type: "Continuous"
    continuous_tier: "Continuous7Days"

cosmos-database:
  defines: azure-cosmosdb/database
  subscription_id: "your-subscription-id"
  resource_group_name: "my-resource-group"
  database_account_name: "my-cosmos-account"
  database_id: "my-database"
  manual_throughput: 400
  connections:
    account:
      runnable: my-app/cosmos-account
      service: data
  depends:
    wait-for:
      runnables:
        - my-app/cosmos-account
      timeout: 300
```

2. Create/update:

```bash theme={null}
monk update my-app/cosmos-account
monk update my-app/cosmos-database
monk describe my-app/cosmos-account
```

## Multi-Region High Availability

For production workloads requiring global distribution:

```yaml theme={null}
ha-cosmos-account:
  defines: azure-cosmosdb/database-account
  subscription_id: "your-subscription-id"
  resource_group_name: "production-rg"
  account_name: "prod-cosmos-global"
  locations:
    - location_name: "East US"
      failover_priority: 0
      is_zone_redundant: true
    - location_name: "West Europe"
      failover_priority: 1
    - location_name: "Southeast Asia"
      failover_priority: 2
  enable_automatic_failover: true
  enable_multiple_write_locations: true
  consistency_policy:
    default_consistency_level: "BoundedStaleness"
    max_staleness_prefix: 100000
    max_interval_in_seconds: 300
```

## Backup & Restore Actions

| Action                       | Description                                    |
| ---------------------------- | ---------------------------------------------- |
| `get-backup-info`            | View backup policy and earliest restore time   |
| `list-restorable-accounts`   | List accounts available for restore            |
| `list-restorable-databases`  | List databases that can be restored            |
| `list-restorable-containers` | List containers that can be restored           |
| `restore`                    | Create a new account from point-in-time backup |

```bash theme={null}
# View backup configuration
monk do my-app/cosmos-account/get-backup-info

# List restorable accounts
monk do my-app/cosmos-account/list-restorable-accounts

# List restorable databases
monk do my-app/cosmos-account/list-restorable-databases \
  source_id="<instance-id>" location="East US"

# Restore to a new account
monk do my-app/cosmos-account/restore \
  target_id="restored-cosmos" \
  source_id="<instance-id>" \
  location="East US" \
  restore_timestamp="2024-12-01T10:00:00Z"
```

**Note:** Continuous backup enables self-service point-in-time restore. Periodic backup restore requires an Azure Support ticket.


# Cloudflare DNS and Tunnel
Source: https://docs.monk.io/integrations/cloudflare

Managed DNS and Cloudflare Tunnel for secure connectivity.

## What is this integration?

Cloudflare provides globally distributed DNS, CDN, and edge services.

## What Monk manages

* DNS Zone and DNS Record
* Cloudflare Tunnel
* Cloudflare Tunnel Application

## Credentials

* `cloudflare-api-token`: Cloudflare API token with account/tunnel and DNS edit permissions
* `cloudflare-account-id`: Account tag/UUID from the dashboard URL (`/accounts/\<ACCOUNT_ID>`)
* `cloudflare-tunnel-token`: Tunnel token created by `cloudflare/cloudflare-tunnel` on first run (distinct from API token)

## Links

* Provider docs: [https://developers.cloudflare.com/dns/](https://developers.cloudflare.com/dns/)
* Tunnel API docs: [https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel-api/](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel-api/)

## Templates

### DNS record template

Save as `example-record.yaml` (see `src/cloudflare/example-record.yaml`):

```yaml theme={null}
namespace: cloudflare-examples

nginx:
  defines: runnable
  inherits: nginx/node-proxy

example-record:
  defines: cloudflare/cloudflare-dns-record
  zone_name: example.com
  name: www
  record_type: CNAME
  content: <- connection-domain-name("nginx")
  ttl: 1
  proxied: true
  services:
    data:
      protocol: custom
  connections:
    nginx:
      runnable: cloudflare-examples/nginx
      service: nginx
  depends:
    wait-for:
      runnables:
        - cloudflare-examples/nginx
      timeout: 60

stack:
  defines: group
  members:
    - cloudflare-examples/nginx
    - cloudflare-examples/example-record
```

### Tunnel: single app

Save as `example-tunnel.yaml` (see `src/cloudflare/example-tunnel.yaml`):

```yaml theme={null}
namespace: cloudflare-tunnel-example

app:
  defines: runnable
  containers:
    app:
      image: nginx:latest
  services:
    http:
      container: app
      port: 80
      protocol: tcp

tunnel:
  defines: cloudflare/cloudflare-tunnel
  account_id: <- secret("cloudflare-account-id")
  name: "example-tunnel"
  token_secret_ref: cloudflare-tunnel-token
  permitted-secrets:
    cloudflare-api-token: true
    cloudflare-tunnel-token: true
    cloudflare-account-id: true
  services:
    data:
      protocol: custom

# cloudflare-tunnel-token is created by the tunnel entity on first run (distinct from cloudflare-api-token)

tunnel-app:
  defines: cloudflare/cloudflare-tunnel-application
  account_id: <- secret("cloudflare-account-id")
  tunnel_id: <- connection-target("tunnel") entity-state get-member("id")
  zone_name: example.com
  hostname: app.example.com # use "@" for apex domain
  service: <- "http://" connection-ip("app") ":" connection-port("app") concat-all
  permitted-secrets:
    cloudflare-api-token: true
    cloudflare-account-id: true
  connections:
    tunnel:
      runnable: cloudflare-tunnel-example/tunnel
      service: data
    app:
      runnable: cloudflare-tunnel-example/app
      service: http
  depends:
    wait-for:
      runnables:
        - cloudflare-tunnel-example/tunnel
      timeout: 60

cloudflared:
  defines: runnable
  inherits: cloudflare/cloudflared
  connections:
    app:
      runnable: cloudflare-tunnel-example/app
      service: http
  depends:
    wait-for:
      runnables:
        - cloudflare-tunnel-example/tunnel
        - cloudflare-tunnel-example/app
      timeout: 60

stack:
  defines: group
  members:
    - cloudflare-tunnel-example/app
    - cloudflare-tunnel-example/tunnel
    - cloudflare-tunnel-example/tunnel-app
    - cloudflare-tunnel-example/cloudflared
```

### Tunnel: multiple apps through one tunnel

```yaml theme={null}
namespace: cloudflare-multi-app

tunnel:
  defines: cloudflare/cloudflare-tunnel
  account_id: <- secret("cloudflare-account-id")
  name: "multi-app-tunnel"
  token_secret_ref: cloudflare-tunnel-token
  permitted-secrets:
    cloudflare-api-token: true
    cloudflare-tunnel-token: true
    cloudflare-account-id: true
  services:
    data:
      protocol: custom

frontend:
  defines: runnable
  containers:
    app:
      image: nginx:latest
  services:
    http:
      container: app
      port: 3000
      protocol: tcp

frontend-tunnel:
  defines: cloudflare/cloudflare-tunnel-application
  account_id: <- secret("cloudflare-account-id")
  tunnel_id: <- connection-target("tunnel") entity-state get-member("id")
  zone_name: example.com
  hostname: app.example.com
  service: <- "http://" connection-ip("frontend") ":" connection-port("frontend") concat-all
  permitted-secrets:
    cloudflare-api-token: true
    cloudflare-account-id: true
  connections:
    tunnel:
      runnable: cloudflare-multi-app/tunnel
      service: data
    app:
      runnable: cloudflare-multi-app/frontend
      service: http

api:
  defines: runnable
  containers:
    app:
      image: nginx:latest
  services:
    http:
      container: app
      port: 8000
      protocol: tcp

api-tunnel:
  defines: cloudflare/cloudflare-tunnel-application
  account_id: <- secret("cloudflare-account-id")
  tunnel_id: <- connection-target("tunnel") entity-state get-member("id")
  zone_name: example.com
  hostname: api.example.com
  service: <- "http://" connection-ip("api") ":" connection-port("api") concat-all
  permitted-secrets:
    cloudflare-api-token: true
    cloudflare-account-id: true
  connections:
    tunnel:
      runnable: cloudflare-multi-app/tunnel
      service: data
    app:
      runnable: cloudflare-multi-app/api
      service: http

cloudflared:
  defines: runnable
  inherits: cloudflare/cloudflared
  connections:
    frontend:
      runnable: cloudflare-multi-app/frontend
      service: http
    api:
      runnable: cloudflare-multi-app/api
      service: http
  depends:
    wait-for:
      runnables:
        - cloudflare-multi-app/tunnel
      timeout: 60

stack:
  defines: group
  members:
    - cloudflare-multi-app/tunnel
    - cloudflare-multi-app/frontend
    - cloudflare-multi-app/frontend-tunnel
    - cloudflare-multi-app/api
    - cloudflare-multi-app/api-tunnel
    - cloudflare-multi-app/cloudflared
```

### Tunnel: cloudflared only (tunnel connector already exists)

Use this when you already have a tunnel token (in this case it's in global secret cloudflare-tunnel-token) and just need to run cloudflared. You must create the tunnel and DNS records manually in Cloudflare for the hostname(s) in your ingress. Each hostname should have a CNAME record pointing to `\<tunnel-id>.cfargotunnel.com`. For a full setup that creates tunnels and DNS records, use the `cloudflare/cloudflare-tunnel` and `cloudflare/cloudflare-tunnel-application` entities instead.

```yaml theme={null}
namespace: example

app:
  defines: runnable
  containers:
    app:
      image: nginx:latest
  services:
    http:
      container: app
      protocol: tcp
      port: 3000

cloudflare-tunnel:
  defines: runnable
  inherits: cloudflare/cloudflared
  files:
    config:
      container: cloudflared
      path: /etc/cloudflared/config.yml
      mode: 0644
      contents: |
        ingress:
          - hostname: mysite.example.com
            service: {{ v "app-url" }}
          - service: http_status:404
  connections:
    app:
      runnable: example/app
      service: http
  depends:
    wait-for:
      runnables:
        - example/app
      timeout: 60
  variables:
    token_secret_ref:
      type: string
      value: cloudflare-tunnel-token
    command_options:
      type: string
      value: --config /etc/cloudflared/config.yml --no-autoupdate # options after "tunnel"
    subcommand_options:
      type: string
      value: "" # options after "run" (e.g., --cred-file)
    app-host:
      type: string
      value: <- connection-ip("app")
    app-port:
      type: int
      value: <- connection-port("app")
    app-url:
      type: string
      value: <- "http://" $app-host ":" $app-port concat-all
  permitted-secrets:
    cloudflare-tunnel-token: true

stack:
  defines: group
  members:
    - example/app
    - example/cloudflare-tunnel
```

## Advanced Configuration Examples

### DNS Zone Management

```yaml theme={null}
namespace: cloudflare-dns-management

# Create a new DNS zone
my-zone:
  defines: cloudflare/cloudflare-dns-zone
  zone_name: myapp.com
  plan: free  # free, pro, business, enterprise

# Add multiple DNS records
www-record:
  defines: cloudflare/cloudflare-dns-record
  zone_name: myapp.com
  name: www
  record_type: CNAME
  content: myapp.com
  ttl: 1
  proxied: true

api-record:
  defines: cloudflare/cloudflare-dns-record
  zone_name: myapp.com
  name: api
  record_type: A
  content: 192.168.1.100
  ttl: 1
  proxied: false

# MX record for email
mx-record:
  defines: cloudflare/cloudflare-dns-record
  zone_name: myapp.com
  name: "@"
  record_type: MX
  content: mail.myapp.com
  priority: 10
  ttl: 1
```

### Page Rules for CDN Optimization

```yaml theme={null}
namespace: cloudflare-cdn

# Page rule for caching static assets
static-assets-rule:
  defines: cloudflare/cloudflare-page-rule
  zone_name: myapp.com
  target: "*myapp.com/static/*"
  actions:
    - id: cache_level
      value: cache_everything
    - id: browser_cache_ttl
      value: 31536000  # 1 year

# Page rule for API endpoints (no caching)
api-rule:
  defines: cloudflare/cloudflare-page-rule
  zone_name: myapp.com
  target: "*myapp.com/api/*"
  actions:
    - id: cache_level
      value: bypass
```

### Firewall Rules

```yaml theme={null}
namespace: cloudflare-security

# Block traffic from specific countries
geo-block-rule:
  defines: cloudflare/cloudflare-firewall-rule
  zone_name: myapp.com
  action: block
  filter:
    expression: "(ip.geoip.country in {\"CN\" \"RU\"})"

# Rate limiting for login endpoints
rate-limit-rule:
  defines: cloudflare/cloudflare-firewall-rule
  zone_name: myapp.com
  action: challenge
  filter:
    expression: "(http.request.uri.path contains \"/login\")"
  rate_limit:
    requests_per_period: 10
    period: 60
    action: challenge
```

## Troubleshooting

### Common Issues

**API token permission errors:**

```bash theme={null}
# Verify token has correct permissions in Cloudflare dashboard
# Ensure token has Zone:DNS:Edit and Zone:Page Rules:Edit permissions
```

**Zone not found errors:**

```bash theme={null}
# Check zone name spelling and that it exists in your Cloudflare account
# Verify the API token has access to the specified zone
```

**DNS propagation delays:**

* DNS changes can take up to 24 hours to propagate globally
* Use Cloudflare's development mode for testing to bypass cache

### Best Practices

1. **API Token Security**: Use restricted API tokens with minimal required permissions
2. **Zone Organization**: Group related DNS records in logical namespaces
3. **CDN Optimization**: Use page rules to optimize caching for different content types
4. **Security First**: Enable firewall rules and rate limiting for sensitive endpoints
5. **Monitoring**: Enable Cloudflare Analytics to monitor traffic patterns

## Integration with Other Services

Cloudflare works seamlessly with:

* **Monk Applications**: Proxy traffic through Cloudflare's global network
* **Load Balancers**: Distribute traffic across multiple origins
* **CDNs**: Combine with other CDNs for multi-layer caching
* **Security Tools**: Integrate with WAF and DDoS protection services
* **Analytics**: Feed traffic data into monitoring dashboards

## Support & Resources

* **Cloudflare Documentation**: [DNS API Reference](https://developers.cloudflare.com/dns/)
* **API Documentation**: [Cloudflare API v4](https://developers.cloudflare.com/api/)
* **Community**: [Cloudflare Community](https://community.cloudflare.com/)
* **Status Page**: [Cloudflare Status](https://www.cloudflarestatus.com/)


# DigitalOcean GenAI Agent
Source: https://docs.monk.io/integrations/digitalocean-agent

Create and manage GenAI agents, deployments, and API keys.

## What is this integration?

Manage DigitalOcean GenAI Agents and related resources (deployments, keys).

## What Monk manages

* Agent, API Keys, Deployment

## What the Agent can do and how to use it

* **Agent Creation**: Create and configure GenAI agents with custom models and settings
* **Model Selection**: Choose from various AI models (GPT, Claude, etc.) and configure parameters
* **API Key Management**: Generate and manage API keys for agent access
* **Deployment Configuration**: Set up agent deployments with scaling and resource allocation
* **Environment Variables**: Configure agent environment variables and secrets
* **Monitoring**: Enable logging and performance monitoring for agents
* **Version Management**: Track and manage agent versions and updates

Steps:

1. Ensure DigitalOcean provider is added (PAT)
2. Define and update namespace/name

## Auth

* Uses DigitalOcean provider credentials

## Getting Started

1. Add DO provider (PAT configured in provider)

2. Define an agent (save as do-agent.yaml):

```yaml theme={null}
namespace: do-agent-example

agent:
  defines: digitalocean-agent/agent
  name: api-create
  instruction: "be a weather reporter"
  model_id: "openai-gpt-oss-120b"
  region: "tor1"
  publish: true
  services:
    data:
      protocol: custom
```

3. Create/update and check state:

```bash theme={null}
monk update do-agent-example/agent
monk describe do-agent-example/agent
```


# DigitalOcean Container Registry
Source: https://docs.monk.io/integrations/digitalocean-container-registry

Private Docker registries on DigitalOcean.

## What is this integration?

Host private container registries with regional options and tiers.

## What Monk manages

* Registry lifecycle and configuration

## Getting Started

1. Add DO provider (PAT configured in provider)

2. Define a registry (save as do-registry.yaml):

```yaml theme={null}
namespace: digitalocean-container-registry-example

my-basic-registry:
  defines: digitalocean-container-registry/registry
  name: monk-docker-registry-fra
  region: fra1
  subscription_tier: basic
```

3. Create/update:

```bash theme={null}
monk update digitalocean-container-registry-example/my-basic-registry
```


# DigitalOcean Databases
Source: https://docs.monk.io/integrations/digitalocean-database

Managed Postgres, MySQL, MongoDB, Valkey, Kafka, and OpenSearch.

## What is this integration?

Provision and manage DigitalOcean managed databases.

## Supported Engines

| Engine       | Slug         | Versions               |
| ------------ | ------------ | ---------------------- |
| PostgreSQL   | `pg`         | 11, 12, 13, 14, 15, 16 |
| MySQL        | `mysql`      | 5.7, 8.0               |
| Valkey       | `valkey`     | 7, 8                   |
| MongoDB      | `mongodb`    | 4.4, 5.0, 6.0, 7.0     |
| Apache Kafka | `kafka`      | 3.5                    |
| OpenSearch   | `opensearch` | 1.x, 2.x               |

> **Note:** Redis has been replaced by Valkey on DigitalOcean. If you want to use Redis, use `valkey` as the engine instead. For backwards compatibility, specifying `engine: redis` will automatically be mapped to `valkey`.

## What Monk manages

* Database clusters and configuration

## Obtaining DigitalOcean Credentials

To use DigitalOcean Managed Databases with Monk, you'll need a DigitalOcean API token.

### What You'll Need

* **Personal Access Token** - DigitalOcean API token with read/write access
* **Optional:** Default region (e.g., `nyc1`)

### Step-by-Step

1. **Log into DigitalOcean** at [https://cloud.digitalocean.com](https://cloud.digitalocean.com)
2. Click **API** in the left sidebar
3. Go to **Tokens/Keys** tab
4. Click **Generate New Token**
5. **Token name:** "Monk Deployment"
6. **Scopes:** Check both **Read** and **Write**
7. Click **Generate Token**
8. **Copy the token immediately** - it's shown only once
9. Save it securely

### Providing to Monk

When deploying to DigitalOcean, ask Monk:

```
deploy to DigitalOcean
```

```
use DigitalOcean managed MongoDB
```

Monk will request your DigitalOcean credentials if not already configured.

### Security Best Practices

✅ **Rotate tokens regularly** - Generate new tokens every 90 days
✅ **Revoke unused tokens** - Remove old tokens from DigitalOcean
✅ **Use minimal scopes** - Read + Write is sufficient for Monk
✅ **Monitor usage** - Check DigitalOcean activity logs

## Getting Started

1. Provide DigitalOcean credentials to Monk when prompted

2. Define a PostgreSQL cluster (save as do-db.yaml):

```yaml theme={null}
namespace: digitalocean-database-example

my-postgres-db:
  defines: digitalocean-database/database
  name: my-postgres-cluster
  engine: pg
  version: "16"
  num_nodes: 1
  region: nyc1
  size: db-s-1vcpu-1gb
```

3. Create/update:

```bash theme={null}
monk update digitalocean-database-example/my-postgres-db
```

## Backup & Restore Actions

DigitalOcean managed databases include automatic daily backups with 7-day retention.

| Action               | Description                        | Key Parameters                          |
| -------------------- | ---------------------------------- | --------------------------------------- |
| `get-backup-info`    | Show backup config and PITR status | -                                       |
| `list-backups`       | List available backup points       | -                                       |
| `describe-backup`    | Get backup details                 | `backup_created_at`                     |
| `restore`            | Fork new cluster from backup       | `new_cluster_name`, `backup_created_at` |
| `get-restore-status` | Check fork progress                | `cluster_id`                            |

### Restore Example

```bash theme={null}
# List available backups
monk do digitalocean-database-example/my-postgres-db/list-backups

# Restore to new cluster
monk do digitalocean-database-example/my-postgres-db/restore \
  --new_cluster_name=restored-db \
  --backup_created_at=2024-01-15T00:00:00Z
```

**Note:** Restore creates a NEW independent cluster (no in-place restore). PITR is supported for PostgreSQL and MySQL only.

## Composing with Other Entities

Use `connection-target` to wire your app to a DigitalOcean managed database and read connection details from its state:

```yaml theme={null}
namespace: my-infra

my-postgres-db:
  defines: digitalocean-database/database
  name: my-app-db
  engine: pg
  version: "16"
  num_nodes: 1
  region: nyc1
  size: db-s-1vcpu-1gb

my-app:
  defines: runnable
  variables:
    db-host:
      type: string
      value: <- connection-target("database") entity-state get-member("connection_host")
      env: DB_HOST
    db-port:
      type: string
      value: <- connection-target("database") entity-state get-member("connection_port")
      env: DB_PORT
    db-user:
      type: string
      value: <- connection-target("database") entity-state get-member("connection_user")
      env: DB_USER
    db-password:
      type: string
      value: <- connection-target("database") entity-state get-member("connection_password")
      env: DB_PASSWORD
    db-name:
      type: string
      value: <- connection-target("database") entity-state get-member("connection_database")
      env: DB_NAME
  connections:
    database:
      runnable: my-infra/my-postgres-db
      service: data
  depends:
    wait-for:
      runnables:
        - my-infra/my-postgres-db
      timeout: 120
```


# DigitalOcean Domains
Source: https://docs.monk.io/integrations/digitalocean-domains

Managed DNS zones and records via DigitalOcean.

## What is this integration?

Manage DNS zones and basic records through DigitalOcean.

## What Monk manages

* Domain and A/CNAME records

## Getting Started

1. Add DO provider (PAT configured in provider)

2. Define a domain (save as do-domains.yaml):

```yaml theme={null}
namespace: do-domains-example

domain-with-ip:
  defines: digitalocean-domains/domain
  name: example.com
  ip_address: 192.168.1.1
  ttl: 3600
```

3. Create/update:

```bash theme={null}
monk update do-domains-example/domain-with-ip
```


# DigitalOcean Monitoring
Source: https://docs.monk.io/integrations/digitalocean-monitoring

Alerts for droplets, load balancers, and databases.

## What is this integration?

Configure monitoring alerts across DigitalOcean resources.

## What Monk manages

* Monitoring alert policies

## Getting Started

1. Add DO provider (PAT configured in provider)

2. Define an alert (save as do-monitoring.yaml):

```yaml theme={null}
namespace: digitalocean-monitoring-example

monk-cpu-alert:
  defines: digitalocean-monitoring/monitoring
  name: monk-cpu-high-alert
  metric_type: v1/insights/droplet/cpu
  compare: GreaterThan
  value: 80
  window: 10m
  enabled: true
  create_when_missing: true
```

3. Create/update:

```bash theme={null}
monk update digitalocean-monitoring-example/monk-cpu-alert
```


# DigitalOcean Spaces
Source: https://docs.monk.io/integrations/digitalocean-spaces

S3-compatible object storage on DigitalOcean.

## What is this integration?

Spaces provides S3-compatible object storage.

## What Monk manages

* Spaces access keys and buckets

## Getting Started

1. Add DO provider (PAT configured in provider)

2. Create keys and a bucket (save as do-spaces.yaml):

```yaml theme={null}
namespace: do-spaces-example

spaces-keys:
  defines: digitalocean-spaces/spaces-keys
  permitted-secrets:
    do-spaces-access-key: true
    do-spaces-secret-key: true

space:
  defines: digitalocean-spaces/spaces-bucket
  region: nyc3
  bucket_name: my-unique-bucket
  permitted-secrets:
    do-spaces-access-key: true
    do-spaces-secret-key: true
```

3. Create/update:

```bash theme={null}
monk update do-spaces-example/spaces-keys
monk update do-spaces-example/space
```


# Google Cloud Platform
Source: https://docs.monk.io/integrations/gcp

Managed cloud databases and storage (Cloud SQL, Firestore, BigQuery, Cloud Storage, Memorystore).

## What is this integration?

Google Cloud Platform (GCP) provides fully managed cloud services including relational databases (Cloud SQL), NoSQL document databases (Firestore), and serverless data warehouses (BigQuery).

## What Monk manages

* Cloud SQL instances, databases, and users
* Firestore databases with PITR and backup support
* BigQuery datasets and table snapshots
* Memorystore for Redis instances with export/import support
* Cloud Storage buckets
* Cloud Storage HMAC keys for S3-compatible access
* Service accounts and IAM bindings
* API enablement via Service Usage

## What the Agent can do and how to use it

* **Database Creation**: Provision Cloud SQL, Firestore, BigQuery, and Memorystore for Redis
* **Backup & Recovery**: Automated backups, on-demand snapshots, export/import, and restore operations
* **Scaling**: Modify instance tiers, storage, and enable high availability
* **Security**: Configure authorized networks, SSL, and IAM permissions
* **Monitoring**: Access instance status and connection information

Steps:

1. Ensure GCP provider is added: `monk cluster provider add -p gcp`
2. monk update \<namespace>/\<name>

## Required IAM Permissions

The principal whose credentials are configured via `monk cluster provider add -p gcp` (a service account or user) needs IAM roles on the target project covering the entities you intend to manage.

### Quick start (broad roles)

Grants enough permission to manage every entity in this package:

* `roles/editor` — create/update/delete most resources
* `roles/resourcemanager.projectIamAdmin` — required because `roles/editor` cannot modify IAM (used by `gcp/service-account`, `gcp/project-iam-binding`, `gcp/resource-iam-binding`)
* `roles/serviceusage.serviceUsageAdmin` — enable APIs via `gcp/service-usage`

### Least-privilege roles

Grant only the roles for the entities your stack uses:

| Entity area                                                                          | Role                                                                |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| API enablement (`gcp/service-usage`)                                                 | `roles/serviceusage.serviceUsageAdmin`                              |
| Cloud SQL (`cloud-sql-instance`, `cloud-sql-database`, `cloud-sql-user`)             | `roles/cloudsql.admin`                                              |
| Firestore (`firestore-database`)                                                     | `roles/datastore.owner`                                             |
| BigQuery (`bigquery-dataset`)                                                        | `roles/bigquery.admin`                                              |
| Memorystore Redis (`memorystore-redis`)                                              | `roles/redis.admin`                                                 |
| Cloud Storage (`cloud-storage`, `cloud-storage-hmac-keys`)                           | `roles/storage.admin`                                               |
| Pub/Sub (`pubsub-topic`, `pubsub-subscription`)                                      | `roles/pubsub.admin`                                                |
| Cloud Run (`cloud-run-service`, `cloud-run-job`)                                     | `roles/run.admin`                                                   |
| Cloud DNS (`cloud-dns-zone`, `cloud-dns-record-set`)                                 | `roles/dns.admin`                                                   |
| Artifact Registry (`artifact-registry-repository`)                                   | `roles/artifactregistry.admin`                                      |
| Cloud CDN / load balancing (`cloud-cdn-backend-bucket`, `cloud-cdn-backend-service`) | `roles/compute.loadBalancerAdmin`                                   |
| Cloud Tasks (`cloud-tasks-queue`)                                                    | `roles/cloudtasks.admin`                                            |
| Cloud Armor (`cloud-armor-security-policy`)                                          | `roles/compute.securityAdmin`                                       |
| Service accounts (`gcp/service-account`, `service-account-key`)                      | `roles/iam.serviceAccountAdmin`, `roles/iam.serviceAccountKeyAdmin` |
| Project IAM bindings (`project-iam-binding`, `resource-iam-binding`)                 | `roles/resourcemanager.projectIamAdmin`                             |
| IAP (`iap-settings`, `iap-access-policy`, `iap-oauth-client`)                        | `roles/iap.admin`                                                   |
| Identity Platform (`identity-platform-*`)                                            | `roles/identityplatform.admin`                                      |
| Cost estimation (`get-cost-estimate`, `costs` actions)                               | `roles/monitoring.viewer`                                           |

For per-entity permission lists at the API-method level, see `src/gcp/README.md`.

## Auth

* Uses GCP provider credentials configured via `monk cluster provider add -p gcp`
* GCP credentials are automatically injected into the GCP client

## Getting Started

1. Ensure GCP provider is added:

```bash theme={null}
monk cluster provider add -p gcp
```

2. Define a Cloud SQL instance (save as gcp-stack.yaml):

```yaml theme={null}
namespace: my-app

enable-apis:
  defines: gcp/service-usage
  apis:
    - sqladmin.googleapis.com

my-postgres:
  defines: gcp/cloud-sql-instance
  name: my-app-db
  database_version: POSTGRES_14
  tier: db-f1-micro
  region: us-central1
  backup_start_time: "03:00"              # Enable automated backups
  point_in_time_recovery_enabled: true    # Enable PITR
  depends:
    wait-for:
      runnables:
        - my-app/enable-apis
      timeout: 300
```

3. Create/update:

```bash theme={null}
monk load gcp-stack.yaml
monk update my-app/my-postgres
monk describe my-app/my-postgres
```

***

## S3-Compatible Cloud Storage Access (HMAC)

Create HMAC keys to access Cloud Storage using S3-compatible clients.
Make sure `storage.googleapis.com` is enabled via `gcp/service-usage`, and
use a service account from `gcp/service-account`:

```yaml theme={null}
storage-hmac-keys:
  defines: gcp/cloud-storage-hmac-keys
  service_account_email: <- connection-target("sa") entity-state get-member("email")
  access_key_secret_ref: gcs-hmac-access-key
  secret_key_secret_ref: gcs-hmac-secret-key
  permitted-secrets:
    gcs-hmac-access-key: true
    gcs-hmac-secret-key: true
  connections:
    sa:
      runnable: gcp/service-account/my-sa
      service: service-account
```

Use `https://storage.googleapis.com` as the S3 endpoint and the secrets
`gcs-hmac-access-key` / `gcs-hmac-secret-key` as credentials.

***

## Cloud SQL Backup & Restore Actions

| Action               | Description                                      |
| -------------------- | ------------------------------------------------ |
| `get-backup-info`    | View backup configuration and PITR status        |
| `create-backup`      | Create an on-demand backup                       |
| `list-backups`       | List available backups (automated and on-demand) |
| `describe-backup`    | Get detailed information about a specific backup |
| `delete-backup`      | Delete a backup                                  |
| `restore`            | Restore from backup (overwrites instance)        |
| `get-restore-status` | Check status of restore operation                |

```bash theme={null}
# View backup configuration
monk do my-app/my-postgres/get-backup-info

# Create a backup before maintenance
monk do my-app/my-postgres/create-backup description="Pre-upgrade backup"

# List available backups
monk do my-app/my-postgres/list-backups

# Restore from backup (WARNING: overwrites instance!)
monk do my-app/my-postgres/restore backup_id="1765968494026"

# Check restore progress
monk do my-app/my-postgres/get-restore-status operation_name="operations/abc123"
```

***

## Firestore Backup & Restore Actions

| Action               | Description                           |
| -------------------- | ------------------------------------- |
| `get-backup-info`    | View PITR status and configuration    |
| `export-documents`   | Export database to Cloud Storage      |
| `import-documents`   | Import from Cloud Storage export      |
| `list-backups`       | List scheduled backups in a location  |
| `describe-backup`    | Get backup details                    |
| `delete-backup`      | Delete a scheduled backup             |
| `restore`            | Restore to a new database from backup |
| `get-restore-status` | Check restore operation progress      |

```bash theme={null}
# View backup configuration
monk do my-app/my-firestore/get-backup-info

# Export database to Cloud Storage
monk do my-app/my-firestore/export-documents output_uri_prefix="gs://my-bucket/backup"

# Import from Cloud Storage
monk do my-app/my-firestore/import-documents input_uri_prefix="gs://my-bucket/backup"

# List scheduled backups
monk do my-app/my-firestore/list-backups location="us-central1"

# Restore to a new database
monk do my-app/my-firestore/restore backup_name="projects/.../backups/..." target_database="restored-db"
```

**Note:** Firestore PITR enables reading historical document versions (7 days), not database-level restore. Use `export-documents` for full database backups.

***

## BigQuery Backup & Restore Actions

| Action              | Description                                 |
| ------------------- | ------------------------------------------- |
| `get-backup-info`   | View time travel settings and storage model |
| `create-snapshot`   | Create a table snapshot                     |
| `list-snapshots`    | List tables/snapshots in dataset            |
| `describe-snapshot` | Get table/snapshot details                  |
| `delete-snapshot`   | Delete a snapshot table                     |
| `restore`           | Create new table from snapshot              |

```bash theme={null}
# View backup configuration
monk do my-app/my-dataset/get-backup-info

# Create a snapshot of a table
monk do my-app/my-dataset/create-snapshot source_table="events"

# Create snapshot at a specific point in time (time travel)
monk do my-app/my-dataset/create-snapshot source_table="events" snapshot_time="2024-12-16T10:00:00Z"

# List all tables/snapshots
monk do my-app/my-dataset/list-snapshots

# Restore by creating a new table from snapshot
monk do my-app/my-dataset/restore snapshot_table="events_backup" target_table="events_restored"
```

**Time Travel:** BigQuery provides built-in time travel (2-7 days) for querying historical data without creating snapshots:

```sql theme={null}
SELECT * FROM `project.dataset.table`
FOR SYSTEM_TIME AS OF TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
```

***

## Restore Behavior Summary

| Database  | Restore Target | Warning                             |
| --------- | -------------- | ----------------------------------- |
| Cloud SQL | Same instance  | ⚠️ **OVERWRITES** existing instance |
| Firestore | New database   | ✅ Safe - creates new database       |
| BigQuery  | New table      | ✅ Safe - creates new table (clone)  |


# Hetzner Storage Box
Source: https://docs.monk.io/integrations/hetzner-storage-box

Managed Hetzner Storage Box for persistent file storage via SFTP, WebDAV, Samba, and rsync.

## What is this integration?

Hetzner Storage Box is a managed network storage product that provides persistent file storage accessible via SFTP, SCP, Samba/CIFS, WebDAV, and rsync. It is separate from Hetzner Cloud servers and managed through the Hetzner Robot API.

## What Monk manages

* Storage Box lifecycle (create, update, delete)
* Access protocol settings (SSH/SFTP, Samba, WebDAV, external reachability)
* Sub-accounts with isolated home directories
* Snapshots

## Credentials

* `hetzner-robot-token`: Hetzner Robot API token. Generate one in the [Robot panel](https://robot.hetzner.com/preferences/index) under **Settings → API token**.

> Storage Boxes use the Robot API (`api.hetzner.com`), not the Cloud API (`api.hetzner.cloud`). Configure the Monk Hetzner provider with your Robot credentials.

## Links

* Provider docs: [https://docs.hetzner.com/storage/storage-box/](https://docs.hetzner.com/storage/storage-box/)
* Robot API reference: [https://docs.hetzner.com/robot/storage-box/api/storage-box-api/](https://docs.hetzner.com/robot/storage-box/api/storage-box-api/)
* Storage box types and pricing: [https://www.hetzner.com/storage/storage-box](https://www.hetzner.com/storage/storage-box)

## Template

```yaml theme={null}
namespace: my-storage

box:
  defines: hetzner-storage-box/storage-box
  name: my-backup-box
  storage_box_type: bx11
  location: fsn1
  password: ChangeMe123!
  ssh: true
  samba: false
  webdav: false
  services:
    data:
      protocol: custom
```

Run:

```bash theme={null}
monk load dist/hetzner-storage-box/MANIFEST
monk load src/hetzner-storage-box/example.yaml
monk run -l hetzner-storage-box-example/my-box
monk do  hetzner-storage-box-example/my-box/info
```


# MariaDB
Source: https://docs.monk.io/integrations/mariadb

Ready-to-run MariaDB container template you can run directly or inherit to integrate a relational database into your stack.

## Overview

This template provides a production‑ready MariaDB instance as a Monk runnable. You can:

* Run it directly to get a managed MariaDB container with sensible defaults
* Inherit it in your own runnable to seamlessly add a relational database to your stack

It exposes MariaDB on port 3306, persists data to a host volume, and can optionally create an application user and database on first start.

## What this template manages

* MariaDB container (`mariadb` image, configurable tag)
* Network service on port 3306
* Persistent volumes for data and configuration
* Optional initialization of database, user, and passwords

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run MariaDB with defaults

```bash theme={null}
monk run mariadb/mariadb
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `mariadb/mariadb.yaml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:3306` (or the runnable hostname inside Monk networks) using the configured credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  mariadb-image: "latest"         # container image tag
  mysql-root-password: "..."      # ROOT password (env: MYSQL_ROOT_PASSWORD)
  mysql-database: "mariadb"       # optional app DB to create (env: MYSQL_DATABASE)
  mysql-user: "mariadbuser"       # optional app user (env: MYSQL_USER)
  mysql-password: "..."           # optional app user password (env: MYSQL_PASSWORD)
```

Data is persisted under `${monk-volume-path}/mariadb` on the host. Custom MySQL config snippets are mounted from `${monk-volume-path}/mariadb-conf:/etc/mysql/conf.d`.

## Use by inheritance (recommended for apps)

Inherit the MariaDB runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp

db:
  defines: runnable
  inherits: mariadb/mariadb

api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: mariadb
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-user:
      value: <- secret("mysql-user")
    database-password:
      value: <- secret("mysql-password")
    database-name:
      value: <- secret("mysql-database")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g mysql-user="appuser"
monk secrets add -g mysql-password="STRONG_USER_PASSWORD"
monk secrets add -g mysql-database="appdb"
monk secrets add -g mysql-root-password="STRONG_ROOT_PASSWORD"

monk run myapp/api
```

## Ports and connectivity

* Service: `mariadb` on TCP port `3306`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence and configuration

* Data path: `${monk-volume-path}/mariadb:/var/lib/mysql/`
* Config path: `${monk-volume-path}/mariadb-conf:/etc/mysql/conf.d`
* You can drop additional `.cnf` files into the config path to tune MariaDB.

## Related templates

* High‑availability cluster: see the `mariadb-ha/` template in this repository for a leader + followers setup.

## Troubleshooting

* If you changed `mysql-root-password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside the DB to match.
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f local/mariadb/mariadb
```


# MongoDB Atlas
Source: https://docs.monk.io/integrations/mongodb-atlas

Managed MongoDB clusters, projects, and users.

## What is this integration?

Manage MongoDB Atlas projects, clusters, and users with Monk.

## What Monk manages

* Project, Cluster, User

## Obtaining Atlas Credentials

Before using MongoDB Atlas with Monk, you'll need to create an Organization API Key in MongoDB Atlas.

### What You'll Need

* **Organization Name** - Your MongoDB Atlas organization name or ID
* **Service Account Client ID** - Atlas API Public Key
* **Service Account Client Secret** - Atlas API Private Key

### Step-by-Step

1. **Log into MongoDB Atlas** at [https://cloud.mongodb.com](https://cloud.mongodb.com)
2. Click your **organization name** in the top left
3. Go to **Organization Settings** (gear icon)
4. Navigate to **Access Manager** → **API Keys** tab
5. Click **Create API Key**
6. Enter description: "Monk Deployment"
7. **Set Organization Permissions:**
   * `Organization Project Creator`
   * `Project Cluster Manager`
   * `Project User Admin`
8. Click **Next**
9. **Copy the Public Key** (Client ID) - save this
10. **Copy the Private Key** (Client Secret) - **shown only once, save it now!**
11. Click **Done**
12. **Note your Organization Name** from Organization Settings main page

### Required Access Scope

Monk needs these specific permissions:

* **Organization Project Creator** - To create Atlas projects for your deployments
* **Project Cluster Manager** - To provision and manage database clusters
* **Project User Admin** - To create database users for your applications

**Monk cannot:**

* Access existing projects or data outside what it creates
* Modify organization-level settings
* Access billing information

This is the minimal scope required for Monk to manage Atlas resources.

### Security Best Practices

✅ **Rotate keys periodically** - Update API keys every 90 days
✅ **Use project-specific keys when possible** - If you only deploy to one project
✅ **Monitor API key usage** - Check Atlas Access Tracking logs
✅ **Revoke unused keys** - Remove old keys when no longer needed

## Auth

* Uses a Monk secret for API token (e.g., mongodb-atlas-token) and password secret for users

## Getting Started

1. Set secrets:

```bash theme={null}
monk secrets add -g mongodb-atlas-token="mdb_xxx"
monk secrets add -g mongodb-user-password="strong-password"
```

2. Define resources (save as mongodb-atlas.yaml):

```yaml theme={null}
namespace: my-mongodb

my-project:
  defines: mongodb-atlas/project
  name: my-application-project
  organization: my-organization
  secret_ref: mongodb-atlas-token
  permitted-secrets:
    mongodb-atlas-token: true

my-cluster:
  defines: mongodb-atlas/cluster
  name: my-application-cluster
  project_id: \<- connection-target("project") entity-state get-member("id")
  provider: AWS
  region: US_EAST_1
  instance_size: M0
  secret_ref: mongodb-atlas-token
  connections:
    project:
      runnable: my-mongodb/my-project
      service: data
  depends:
    wait-for:
      runnables:
        - my-mongodb/my-project
      timeout: 120

my-user:
  defines: mongodb-atlas/user
  name: app-user
  role: readWrite
  project_id: \<- connection-target("project") entity-state get-member("id")
  secret_ref: mongodb-atlas-token
  password_secret_ref: mongodb-user-password
  connections:
    project:
      runnable: my-mongodb/my-project
      service: data
  depends:
    wait-for:
      runnables:
        - my-mongodb/my-project
      timeout: 120
```

3. Create/update:

```bash theme={null}
monk update my-mongodb/my-project
monk update my-mongodb/my-cluster
monk update my-mongodb/my-user
```

## Backup & Snapshot Actions (M10+ Clusters)

MongoDB Atlas provides comprehensive backup and restore capabilities for **M10 and higher dedicated clusters**.

<Note type="warning">
  **M0 free tier does not support backup API.** M2 and M5 shared tiers also
  lack backup support. For production deployments requiring backups, use M10+
  dedicated clusters which include automated daily backups and point-in-time
  restore capabilities.
</Note>

| Action               | Description                                 |
| -------------------- | ------------------------------------------- |
| `get-backup-info`    | View backup configuration and status        |
| `create-snapshot`    | Create an on-demand backup snapshot         |
| `list-snapshots`     | List available snapshots                    |
| `describe-snapshot`  | Get detailed info about a specific snapshot |
| `delete-snapshot`    | Delete a backup snapshot                    |
| `restore`            | Restore from snapshot or point-in-time      |
| `get-restore-status` | Check restore job progress                  |
| `list-restore-jobs`  | View all restore jobs                       |

### Using Backups with Monk

**Ask Monk to manage backups:**

```
back up my MongoDB database
```

```
show me available backups
```

```
restore from latest backup
```

Monk translates these natural language requests to the appropriate Atlas API calls.

### CLI Reference (Advanced)

For direct CLI usage:

```bash theme={null}
# View backup configuration
monk do my-mongodb/my-cluster/get-backup-info

# Create a snapshot before migration
monk do my-mongodb/my-cluster/create-snapshot description="Pre-migration"

# List available snapshots
monk do my-mongodb/my-cluster/list-snapshots

# Restore from snapshot (WARNING: overwrites data!)
monk do my-mongodb/my-cluster/restore snapshot_id="xxx"

# Point-in-time restore
monk do my-mongodb/my-cluster/restore restore_timestamp="2024-12-01T10:00:00Z"

# Check restore progress
monk do my-mongodb/my-cluster/get-restore-status job_id="xxx"

# Get details about a specific snapshot
monk do my-mongodb/my-cluster/describe-snapshot snapshot_id="xxx"

# Delete a snapshot
monk do my-mongodb/my-cluster/delete-snapshot snapshot_id="xxx"
```


# Aerospike
Source: https://docs.monk.io/integrations/monk-aerospike

Ready-to-run Aerospike container template you can run directly or inherit to integrate a high-performance NoSQL database into your stack.

## Overview

This template provides a production‑ready Aerospike instance as a Monk runnable. You can:

* Run it directly to get a managed Aerospike container with sensible defaults
* Inherit it in your own runnable to seamlessly add a high-performance NoSQL database to your stack

It exposes Aerospike on port 3000, persists data to a host volume, and is optimized for use cases that require low latency and high throughput such as real-time bidding, fraud detection, and recommendation engines.

## What this template manages

* Aerospike container (`aerospike` image, configurable tag)
* Network service on port 3000
* Persistent volume for data storage
* Hybrid memory architecture combining DRAM and flash memory for optimal performance

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Aerospike with defaults

```bash theme={null}
monk run aerospike/aerospike
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. To customize, you can either:

* Preferred: inherit and override variables as shown below.
* Alternative: fork/clone and edit the `variables` in `aerospike.yml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:3000` (or the runnable hostname inside Monk networks) to access the Aerospike service.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  image_tag: "ce-6.2.0.7_1"    # container image tag
  service_port: 3000            # service port (env: SERVICE_PORT)
```

Data is persisted under `${monk-volume-path}/aerospike:/opt/aerospike/data` on the host.

## Use by inheritance (recommended for apps)

Inherit the Aerospike runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
db:
  defines: runnable
  inherits: aerospike/aerospike
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: base-svc
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-port:
      value: "3000"
```

Then run your app:

```bash theme={null}
monk run myapp/api
```

## Ports and connectivity

* Service: `base-svc` on TCP port `3000`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence

* Data path: `${monk-volume-path}/aerospike:/opt/aerospike/data`
* All data is automatically persisted to the host volume, ensuring data durability across container restarts.

## Key features

* **High Performance**: Optimized for low latency and high throughput operations
* **Distributed Architecture**: Built-in support for data replication and automatic data distribution
* **Fault Tolerance**: Automatic failover in case of node failure
* **Hybrid Memory**: Combines DRAM and flash memory to maximize performance and minimize cost
* **Key-Value Model**: Supports key-value pairs with complex data types (lists, maps, sets)

## Use cases

Aerospike is particularly well-suited for:

* Real-time bidding platforms
* Fraud detection systems
* Recommendation engines
* E-commerce applications
* Ad tech solutions
* Financial services
* Any application requiring fast data access with high throughput

## Troubleshooting

* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f aerospike/aerospike
```

* Verify the service is listening on the expected port:

```bash theme={null}
monk describe aerospike/aerospike
```

## Related tools

* **Aerospike Query Language (ASQL)**: SQL-like query language for Aerospike
* **Aerospike Management Console (AMC)**: Web-based interface for monitoring and managing Aerospike clusters


# Apache Airflow
Source: https://docs.monk.io/integrations/monk-airflow

Ready-to-run Apache Airflow container template for workflow orchestration and data pipeline management.

## Overview

This template provides a production‑ready Apache Airflow instance as a Monk runnable. You can:

* Run it directly to get a managed workflow orchestration platform
* Inherit it in your own data engineering infrastructure to schedule and monitor workflows

Apache Airflow is a platform to programmatically author, schedule, and monitor workflows. It allows you to define workflows as Directed Acyclic Graphs (DAGs) of tasks, with rich scheduling and monitoring capabilities.

## What this template manages

* Airflow webserver and scheduler
* PostgreSQL metadata database
* Redis for Celery executor
* Worker nodes for task execution
* Triggerer for deferrable operators
* Web UI on port 8080
* DAG management and execution

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Airflow stack

```bash theme={null}
monk run airflow/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `stack.yml`, then `monk load MANIFEST` and run.

Once started, access Airflow UI at `http://localhost:8080`.

Default credentials: `airflow` / `airflow` (change immediately in production!)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Airflow credentials
  airflow_username: "airflow"         # Web UI username
  airflow_password: "..."             # Web UI password
  webserver_port: 8080                # Web UI port
  
  # Database
  database_user: "airflow"            # PostgreSQL user
  database_password: "..."            # PostgreSQL password
  database_name: "airflow"            # PostgreSQL database name
```

DAGs and logs are persisted under `${monk-volume-path}/airflow` on the host.

## Use by inheritance (recommended for data pipelines)

Inherit the Airflow stack in your application for workflow orchestration. Example:

```yaml theme={null}
namespace: myapp
orchestrator:
  defines: process-group
  inherits: airflow/stack
  variables:
    airflow_username:
      value: <- secret("airflow-username")
    airflow_password:
      value: <- secret("airflow-password")
    database_password:
      value: <- secret("airflow-db-password")
data-pipeline:
  defines: runnable
  containers:
    pipeline:
      image: myorg/data-pipeline
  connections:
    airflow:
      runnable: orchestrator/airflow-webserver
      service: webserver
```

Then set the secrets once and run your orchestrator:

```bash theme={null}
monk secrets add -g airflow-username="admin"
monk secrets add -g airflow-password="STRONG_PASSWORD"
monk secrets add -g airflow-db-password="STRONG_DB_PASSWORD"
monk run myapp/orchestrator
```

## Ports and connectivity

* Service: `webserver` on TCP port `8080`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Airflow host.

## Persistence and configuration

* DAGs: `${monk-volume-path}/airflow/dags:/opt/airflow/dags`
* Logs: `${monk-volume-path}/airflow/logs:/opt/airflow/logs`
* Plugins: `${monk-volume-path}/airflow/plugins:/opt/airflow/plugins`
* You can drop DAG files into the `dags` path to deploy workflows.

## Features

* **DAG-based Workflows**: Define workflows as Python code
* **Rich Scheduling**: Cron-based, interval-based, and event-based triggers
* **Monitoring**: Web UI with DAG visualization and execution history
* **Extensible**: 200+ operators and sensors (Spark, Kubernetes, AWS, GCP, etc.)
* **Task Dependencies**: Complex task graphs with branching and conditions
* **Retry Logic**: Automatic retry with exponential backoff
* **SLA Monitoring**: Track and alert on SLA violations
* **Connection Management**: Secure credential storage
* **CeleryExecutor**: Distributed task execution across worker nodes

## Creating DAGs

Example DAG:

```python theme={null}
from airflow import DAG
from airflow.operators.bash import BashOperator
from datetime import datetime, timedelta

default_args = {
    'owner': 'airflow',
    'depends_on_past': False,
    'start_date': datetime(2024, 1, 1),
    'retries': 1,
    'retry_delay': timedelta(minutes=5),
}

dag = DAG(
    'example_dag',
    default_args=default_args,
    schedule_interval='@daily',
)

task1 = BashOperator(
    task_id='print_date',
    bash_command='date',
    dag=dag,
)

task2 = BashOperator(
    task_id='process_data',
    bash_command='echo "Processing data"',
    dag=dag,
)

task1 >> task2  # task1 must complete before task2
```

## Use cases

Airflow excels at:

* ETL/ELT pipelines
* Data warehouse management
* ML model training pipelines
* Report generation
* Data quality checks
* Multi-cloud orchestration

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools for observability
* Integrate with your application stack as needed

## Troubleshooting

* If you changed `airflow_password` after initial setup, you may need to reset data volumes or update the user inside Airflow.
* Ensure PostgreSQL and Redis are running before starting Airflow components.
* Generate Fernet key for encrypting secrets:

```bash theme={null}
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f airflow/airflow-webserver
monk logs -l 500 -f airflow/airflow-scheduler
```

* For task failures, check task logs in the Airflow UI
* Monitor worker health in the UI: Admin → Workers


# JFrog Artifactory
Source: https://docs.monk.io/integrations/monk-artifactory

Ready-to-run JFrog Artifactory container template for universal artifact repository manager and DevOps platform.

## Overview

This template provides a production‑ready JFrog Artifactory instance as a Monk runnable. You can:

* Run it directly to get a managed universal artifact repository
* Inherit it in your own CI/CD infrastructure to manage binaries, containers, and packages

JFrog Artifactory is the universal artifact repository manager. It supports all major package formats and integrates with your CI/CD tools to manage the full lifecycle of your binaries from development through production.

## What this template manages

* Artifactory container (OSS, Pro, or Enterprise editions, configurable tag)
* PostgreSQL database container (for metadata storage)
* Network service on port 8082
* Persistent volumes for artifacts and database
* Web UI and REST API
* Repository management and Docker registry
* Security and access control

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Artifactory with defaults

```bash theme={null}
monk run artifactory/artifactory
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in the manifest, then `monk load MANIFEST` and run.

Once started, access Artifactory at `http://localhost:8082` using the configured credentials.

Default credentials: `admin` / `password` (change immediately!)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Artifactory
  artifactory-image-tag: "latest"     # Artifactory image tag
  artifactory-port: "8082"            # web UI and API port
  artifactory-edition: "oss"          # oss, pro, or enterprise
  
  # Database
  db-type: "postgresql"               # database type
  postgres-password: "..."            # PostgreSQL password
  postgres-user: "artifactory"        # database user
  postgres-db: "artifactory"          # database name
  
  # Storage
  max-heap-size: "2g"                 # JVM max heap
```

Data is persisted under `${monk-volume-path}/artifactory` on the host. PostgreSQL data is stored under `${monk-volume-path}/postgres`.

## Use by inheritance (recommended for DevOps)

Inherit the Artifactory runnable in your DevOps infrastructure and declare a connection. Example:

```yaml theme={null}
namespace: devops
artifacts:
  defines: runnable
  inherits: artifactory/artifactory
  variables:
    postgres-password: <- secret("artifactory-db-password")
ci:
  defines: runnable
  containers:
    ci:
      image: myorg/ci-runner
      environment:
        - ARTIFACTORY_URL=http://artifacts:8082
        - ARTIFACTORY_USER=<- secret("artifactory-user")
        - ARTIFACTORY_PASSWORD=<- secret("artifactory-password")
  connections:
    repo:
      runnable: artifacts
      service: artifactory
```

Then set the secrets once and run your DevOps group:

```bash theme={null}
monk secrets add -g artifactory-db-password="STRONG_PASSWORD"
monk secrets add -g artifactory-user="ci-user"
monk secrets add -g artifactory-password="STRONG_PASSWORD"
monk run devops/ci
```

## Ports and connectivity

* Service: Web UI/API on TCP port `8082`
* From CI/CD tools, use `http://\<host>:8082` for repository access
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Artifactory host.

## Persistence and configuration

* Artifactory data: `${monk-volume-path}/artifactory:/var/opt/jfrog/artifactory`
* PostgreSQL data: `${monk-volume-path}/postgres:/var/lib/postgresql/data`
* You can mount additional configuration files to customize Artifactory behavior.

## Features

* **Universal Repository**: Support for 30+ package types
* **Docker Registry**: Private Docker image registry
* **High Availability**: Clustering and replication (Pro/Enterprise)
* **Security**: Vulnerability scanning (Xray integration)
* **Access Control**: RBAC, LDAP, SSO integration
* **Replication**: Multi-site replication
* **Build Integration**: Jenkins, Bamboo, TeamCity, Azure DevOps
* **REST API**: Comprehensive automation API

## Supported Package Types

* **Containers**: Docker, Helm, OCI
* **Java**: Maven, Gradle, Ivy, SBT
* **JavaScript**: npm, Bower, Yarn
* **Python**: PyPI, Conda
* **.NET**: NuGet
* **.NET Core**: .NET CLI
* **Ruby**: RubyGems
* **Go**: Go modules
* **PHP**: Composer
* **Rust**: Cargo
* **C/C++**: Conan
* **And 20+ more...**

## Repository Types

* **Local**: Host internal artifacts
* **Remote**: Proxy external repositories (Maven Central, npm, etc.)
* **Virtual**: Aggregate multiple repositories

## Docker Registry

Use Artifactory as Docker registry:

```bash theme={null}
# Login
docker login artifactory.example.com

# Tag image
docker tag myimage:latest artifactory.example.com/docker-local/myimage:latest

# Push
docker push artifactory.example.com/docker-local/myimage:latest

# Pull
docker pull artifactory.example.com/docker-local/myimage:latest
```

## Maven Integration

Configure Maven in `~/.m2/settings.xml`:

```xml theme={null}
<mirrors>
  <mirror>
    <id>artifactory</id>
    <mirrorOf>*</mirrorOf>
    <url>http://localhost:8082/artifactory/libs-release</url>
  </mirror>
</mirrors>
```

## npm Integration

```bash theme={null}
# Set registry
npm config set registry http://localhost:8082/artifactory/api/npm/npm-virtual/

# Authenticate
npm login --registry=http://localhost:8082/artifactory/api/npm/npm-virtual/
```

## Use cases

Artifactory excels at:

* Universal artifact management
* Private Docker registry
* Dependency caching and proxying
* Build artifact versioning
* Security and compliance
* Multi-site distribution
* CI/CD pipeline integration

## Related templates

* High‑availability setup: see the Artifactory HA template for clustered deployment.
* Alternative artifact repository: see the `nexus/` template for Sonatype Nexus.
* Integrate with CI/CD: combine with Jenkins, GitLab CI, or GitHub Actions templates.

## Troubleshooting

* Access Artifactory UI at `http://localhost:8082`
* Check system health: Administration → System Health
* View logs: Administration → System Logs
* Check container logs:

```bash theme={null}
monk logs -l 500 -f artifactory/artifactory
```

* If Artifactory startup is slow, note that it requires 2-5 minutes on first launch
* If you experience memory issues, increase the `max-heap-size` variable
* If database connection fails, verify PostgreSQL is running and credentials are correct
* For Docker registry issues, ensure proper reverse proxy configuration with SSL
* Monitor disk space for artifact storage and use cleanup policies to manage it
* Ensure the host volumes are writable by the container user


# BIRD Internet Routing Daemon
Source: https://docs.monk.io/integrations/monk-bird

Ready-to-run BIRD container template for BGP and dynamic routing protocol daemon.

## Overview

This template provides a production‑ready BIRD routing daemon instance as a Monk runnable. You can:

* Run it directly to get a managed dynamic routing daemon with sensible defaults
* Inherit it in your own runnable to seamlessly add BGP, OSPF, RIP, and other routing protocols to your network infrastructure

BIRD (BIRD Internet Routing Daemon) is a fully functional dynamic IP routing daemon for Unix-like systems. It supports IPv4 and IPv6 with all major routing protocols including BGP, OSPF, RIP, and static routes, making it ideal for ISP, datacenter, and enterprise networking.

## What this template manages

* BIRD routing daemon container (configurable image tag)
* Network service with routing protocols
* Persistent volumes for configuration and state
* IPv4 and IPv6 routing support
* Protocol debugging and logging

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run BIRD with defaults

```bash theme={null}
monk run bird/bird
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. For production use:

* Preferred: inherit and customize variables with your own configuration as shown below.
* Alternative: fork/clone and edit the `variables` in `bird/bird.yaml`, then `monk load MANIFEST` and run.

Once started, BIRD will load configuration and establish routing sessions. Interact with it using `birdc` commands.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  bird-image-tag: "latest"            # container image tag
  router-id: "1.1.1.1"                # router ID (usually loopback IP)
  bird-config: "..."                  # custom BIRD configuration
```

Configuration is persisted under `${monk-volume-path}/bird` on the host. State files are stored in `${monk-volume-path}/bird/var:/var/run/bird`.

## Use by inheritance (recommended for network infrastructure)

Inherit the BIRD runnable in your network infrastructure and customize the routing configuration. Example:

```yaml theme={null}
namespace: mynetwork
router:
  defines: runnable
  inherits: bird/bird
  variables:
    router-id: "10.0.0.1"
  files:
    bird-config:
      container: bird
      path: /etc/bird/bird.conf
      contents: |
        router id 10.0.0.1;
        
        protocol device {
        }
        
        protocol kernel {
          ipv4 {
            import none;
            export all;
          };
        }
        
        protocol bgp peer1 {
          local as 65001;
          neighbor 10.0.0.2 as 65002;
          ipv4 {
            import all;
            export all;
          };
        }
```

Then run your network infrastructure:

```bash theme={null}
monk run mynetwork/router
```

## Persistence and configuration

* Config path: `${monk-volume-path}/bird/etc:/etc/bird`
* State path: `${monk-volume-path}/bird/var:/var/run/bird`
* You can mount custom BIRD configuration files into the config path to tune routing behavior.

## Features

* **Multi-Protocol**: BGP-4, OSPFv2, OSPFv3, RIPv2, RIPng
* **IPv6 Support**: Full IPv4 and IPv6 routing
* **BGP Features**: Route reflection, confederations, graceful restart
* **Filtering**: Powerful route filtering language
* **Multiple RIBs**: Support for multiple routing tables
* **Fast Convergence**: Efficient route updates
* **Scripting**: Extensive configuration language

## BGP Configuration

Example BGP peering:

```
protocol bgp peer_upstream {
  description "Upstream ISP";
  local as 65001;
  neighbor 203.0.113.1 as 65000;
  
  ipv4 {
    import filter {
      # Accept default route
      if net = 0.0.0.0/0 then accept;
      reject;
    };
    export filter {
      # Export our networks
      if net ~ [ 198.51.100.0/24 ] then accept;
      reject;
    };
  };
}
```

## OSPF Configuration

Example OSPF:

```
protocol ospf v2 ospf_internal {
  ipv4 {
    import all;
    export all;
  };
  
  area 0.0.0.0 {
    interface "eth0" {
      hello 10;
      dead 40;
      type broadcast;
    };
  };
}
```

## Static Routes

```
protocol static {
  ipv4;
  
  route 0.0.0.0/0 via 10.0.0.1;
  route 192.168.1.0/24 via 10.0.1.1;
}
```

## BIRD Control

Interact with BIRD using `birdc`:

```bash theme={null}
# Check BIRD status
birdc show status

# Show routes
birdc show route

# Show protocols
birdc show protocols

# Show BGP details
birdc show protocol all bgp_peer1

# Reload configuration
birdc configure
```

## Use cases

BIRD excels at:

* ISP and datacenter routing
* BGP peering and internet exchange points (IXP)
* Enterprise OSPF networks
* Route servers
* Anycast routing
* Software-defined networking (SDN)

## Related templates

* Combine with monitoring tools for network observability
* See other networking templates in this repository for complementary services

## Troubleshooting

* If routing protocols are not establishing sessions, verify neighbor IPs are reachable and firewall rules allow routing traffic (TCP 179 for BGP).
* Ensure configuration syntax is correct by testing with `birdc configure` after changes.
* Check logs:

```bash theme={null}
monk logs -l 500 -f bird/bird
```

* Verify BIRD status:

```bash theme={null}
birdc show status
```

* View protocol states:

```bash theme={null}
birdc show protocols
```

* Debug specific protocol by adding `debug all;` to the protocol configuration in bird.conf
* For BGP session issues:
  * Verify neighbor IP is reachable
  * Check AS numbers match configuration
  * Verify firewall allows TCP 179
* For OSPF issues, check interface configurations and area settings
* Use `birdc show route` to inspect routing table entries


# Apache Cassandra
Source: https://docs.monk.io/integrations/monk-cassandra

Ready-to-run Apache Cassandra container template you can run directly or inherit to integrate a distributed NoSQL database into your stack.

## Overview

This template provides a production‑ready Apache Cassandra instance as a Monk runnable. You can:

* Run it directly to get a managed Cassandra container with sensible defaults
* Inherit it in your own runnable to seamlessly add a distributed wide-column NoSQL database to your stack

Apache Cassandra is a highly scalable, distributed NoSQL database designed to handle large amounts of data across many commodity servers, providing high availability with no single point of failure.

## What this template manages

* Cassandra container (`cassandra` image, configurable tag)
* Network service on port 9042 (CQL native transport)
* Persistent volumes for data storage
* Authentication configuration

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Cassandra with defaults

```bash theme={null}
monk run cassandra/cassandra
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `cassandra/cassandra.yml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:9042` (or the runnable hostname inside Monk networks) using CQL.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  cassandra-image: "latest"              # container image tag
  cassandra-password: "monk"             # Cassandra password (env: CASSANDRA_PASSWORD)
```

Data is persisted under `${monk-volume-path}/cassandra` on the host.

## Use by inheritance (recommended for apps)

Inherit the Cassandra runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
db:
  defines: runnable
  inherits: cassandra/cassandra
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: cassandra
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-password:
      value: <- secret("cassandra-password")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g cassandra-password="STRONG_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `cassandra` on TCP port `9042` (CQL native transport)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence and configuration

* Data path: `${monk-volume-path}/cassandra:/var/lib/cassandra`
* Cassandra stores all keyspaces, tables, and data in this directory

## Related templates

* Cassandra cluster: see the `cassandra-cluster/` template in this repository for a multi-node cluster setup with seed nodes
* Combine with `spark/` for analytics workloads
* Use with `prometheus-grafana/` for monitoring and metrics

## Troubleshooting

* Cassandra may take several minutes to start, especially on first launch
* If you changed `cassandra-password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside Cassandra to match.
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f local/cassandra/cassandra
```


# Chatwoot
Source: https://docs.monk.io/integrations/monk-chatwoot

Ready-to-run Chatwoot container stack you can run directly or inherit to integrate a customer engagement platform into your infrastructure.

## Overview

This template provides a production‑ready Chatwoot stack as a Monk runnable. You can:

* Run it directly to get a managed Chatwoot deployment with all necessary components
* Inherit it in your own stack to seamlessly add customer engagement and support chat capabilities

Chatwoot is an open-source customer engagement platform that allows you to manage conversations across multiple channels including website chat, email, Facebook, Twitter, WhatsApp, and more. It provides automated responses, chatbots, real-time analytics, and multi-channel support to help businesses improve customer experience.

## What this template manages

* Chatwoot Rails application (web interface and API)
* Chatwoot Sidekiq (background job processing)
* PostgreSQL database (data storage)
* Redis (caching and background jobs)
* Database initialization and migration
* Network services and internal connectivity

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Chatwoot stack with defaults

```bash theme={null}
monk run chatwoot/stack
```

3. Setup database

After the stack is running, initialize the database:

```bash theme={null}
monk do chatwoot/chatwoot-rails/prepare-db
```

4. Access the web interface

Once the database is prepared, access the Chatwoot web interface at `http://localhost:3000` and complete the initial setup wizard to create your admin account.

5. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `stack.yml`, then `monk load MANIFEST` and run.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Application settings
  chatwoot_secret_key: "replace_with_lengthy_secure_hex"
  chatwoot_frontend_url: "http://0.0.0.0:3000"
  chatwoot_helpcenter_url: "http://0.0.0.0:3000"
  chatwoot_default_locale: "en"
  chatwoot_force_ssl: false
  chatwoot_enable_account: false  # Enable public signup

  # Database settings
  chatwoot_database: "monk"
  chatwoot_database_user: "monk"
  chatwoot_database_password: "monk"

  # Redis settings
  chatwoot_redis_password: ""

  # Email/SMTP settings
  chatwoot_mail_sender: "Chatwoot <accounts@monk.io>"
  chatwoot_smtp_domain: "monk.io"
  chatwoot_smtp_address: "mailhog"
  chatwoot_smtp_user: ""
  chatwoot_smtp_password: ""
  chatwoot_smtp_authentication: ""

  # Storage settings
  chatwoot_active_storage_service: "local"  # or "amazon" for S3
  chatwoot_s3_bucket_name: ""
  chatwoot_aws_access_key_id: ""
  chatwoot_aws_secret_access_key: ""
  chatwoot_aws_region: ""

  # Social media integrations (optional)
  chatwoot_fb_app_id: ""
  chatwoot_fb_app_secret: ""
  chatwoot_twitter_consumer_key: ""
  chatwoot_twitter_consumer_secret: ""
  chatwoot_slack_client_id: ""
  chatwoot_slack_client_secret: ""
```

**Important:** Change `chatwoot_secret_key` to a secure random string (64+ hex characters) before production use.

## Stack components

The Chatwoot stack includes the following runnables:

* `chatwoot-rails` - Rails application server (port 3000)
* `chatwoot-sidekiq` - Background job processor
* `chatwoot-db` - PostgreSQL database server
* `chatwoot-rds` - Redis cache and job queue

## Ports and connectivity

* Web interface and API: port `3000`
* PostgreSQL: internal only (port 5432)
* Redis: internal only (port 6379)

From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve service hosts.

## Use by inheritance (recommended for apps)

Inherit the Chatwoot stack in your customer engagement infrastructure and configure with secrets. Example:

```yaml theme={null}
namespace: myapp

support:
  defines: process-group
  runnable-list:
    - myapp/chatwoot-custom

chatwoot-custom:
  defines: runnable
  inherits: chatwoot/stack
  variables:
    chatwoot_secret_key:
      value: <- secret("chatwoot-secret-key")
    chatwoot_frontend_url:
      value: <- secret("chatwoot-frontend-url")
    chatwoot_database_password:
      value: <- secret("chatwoot-db-password")
    chatwoot_smtp_address:
      value: <- secret("smtp-address")
    chatwoot_smtp_user:
      value: <- secret("smtp-user")
    chatwoot_smtp_password:
      value: <- secret("smtp-password")
```

Then set the secrets once and run your stack:

```bash theme={null}
# Generate a secure secret key (64 hex characters)
monk secrets add -g chatwoot-secret-key="$(openssl rand -hex 32)"
monk secrets add -g chatwoot-frontend-url="https://chat.yourdomain.com"
monk secrets add -g chatwoot-db-password="STRONG_DB_PASSWORD"
monk secrets add -g smtp-address="smtp.sendgrid.net"
monk secrets add -g smtp-user="apikey"
monk secrets add -g smtp-password="YOUR_SENDGRID_API_KEY"

# Run the stack
monk run myapp/support

# Initialize the database
monk do myapp/chatwoot-custom/chatwoot-rails/prepare-db
```

## Database setup

After deploying the stack, you **must** run the database preparation action:

```bash theme={null}
monk do chatwoot/chatwoot-rails/prepare-db
```

This action will:

* Create the database schema
* Run all migrations
* Set up initial data structures
* Prepare the application for first use

**Note:** This step is required only once during initial setup. Subsequent deployments will use the existing database.

## Email configuration

For production use, configure SMTP settings to enable:

* User invitations and password resets
* Email notifications
* Email channel support

Common SMTP providers:

* **SendGrid:** `smtp.sendgrid.net` (port 587, TLS)
* **AWS SES:** `email-smtp.REGION.amazonaws.com`
* **Mailgun:** `smtp.mailgun.org`
* **Gmail:** `smtp.gmail.com` (use App Password)

## Storage configuration

By default, Chatwoot stores attachments locally. For production, configure S3-compatible storage:

```yaml theme={null}
chatwoot_active_storage_service: "amazon"
chatwoot_s3_bucket_name: "your-chatwoot-bucket"
chatwoot_aws_access_key_id: "<- secret('aws-access-key')"
chatwoot_aws_secret_access_key: "<- secret('aws-secret-key')"
chatwoot_aws_region: "us-east-1"
```

## Social media integrations

Configure social media channels by setting the appropriate API credentials:

**Facebook/Instagram:**

```yaml theme={null}
chatwoot_fb_app_id: "YOUR_FB_APP_ID"
chatwoot_fb_app_secret: "YOUR_FB_APP_SECRET"
chatwoot_fb_verify_token: "YOUR_VERIFY_TOKEN"
chatwoot_ig_verify_token: "YOUR_IG_VERIFY_TOKEN"
```

**Twitter:**

```yaml theme={null}
chatwoot_twitter_consumer_key: "YOUR_CONSUMER_KEY"
chatwoot_twitter_consumer_secret: "YOUR_CONSUMER_SECRET"
```

**Slack:**

```yaml theme={null}
chatwoot_slack_client_id: "YOUR_CLIENT_ID"
chatwoot_slack_client_secret: "YOUR_CLIENT_SECRET"
```

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Integrate with reverse proxy (`nginx/`) for SSL termination
* Add email service (`mailhog/`) for development testing

## Troubleshooting

* **Database connection errors:** Ensure PostgreSQL is running and accepting connections. Check that `chatwoot_database_password` matches between the stack and database variables.

* **Redis connection errors:** Verify Redis is running and accessible. If using Redis password authentication, ensure `chatwoot_redis_password` is correctly set.

* **Missing `prepare-db` action:** Make sure to run the database preparation action after first deployment:

```bash theme={null}
monk do chatwoot/chatwoot-rails/prepare-db
```

* **Port conflicts:** Ensure port 3000 is available on your host. Change the `host-port` in `chatwoot-rails` if needed.

* **Check logs** for any component:

```bash theme={null}
monk logs -l 500 -f chatwoot/stack
monk logs -l 500 -f chatwoot/chatwoot-rails
monk logs -l 500 -f chatwoot/chatwoot-sidekiq
monk logs -l 500 -f chatwoot/chatwoot-db
```

* **Initialization issues:** If you encounter problems during setup, try purging and restarting:

```bash theme={null}
monk purge chatwoot
monk run chatwoot/stack
monk do chatwoot/chatwoot-rails/prepare-db
```

* **Background jobs not processing:** Check that Sidekiq is running properly:

```bash theme={null}
monk logs -l 500 -f chatwoot/chatwoot-sidekiq
```

* **Email not working:** Verify SMTP settings are correct and the SMTP server is reachable from your Monk cluster. Test with a simple email notification from Chatwoot.

* **Startup order:** The stack ensures proper startup order with dependencies. PostgreSQL and Redis start before the Rails application and Sidekiq workers.


# CoreDNS
Source: https://docs.monk.io/integrations/monk-coredns

Ready-to-run CoreDNS container template you can run directly or inherit to integrate a flexible DNS server into your infrastructure.

## Overview

This template provides a production‑ready CoreDNS instance as a Monk runnable. You can:

* Run it directly to get a managed CoreDNS container with sensible defaults
* Inherit it in your own runnable to seamlessly add a flexible, extensible DNS server to your infrastructure

CoreDNS is a fast and flexible DNS server written in Go. It chains plugins to implement DNS functionality. Each plugin performs a DNS function, such as Kubernetes service discovery, Prometheus metrics, rewriting queries, or just serving from zone files.

## What this template manages

* CoreDNS container (`coredns/coredns` image, configurable tag)
* DNS service on port 53 (UDP)
* Custom CoreDNS configuration (Corefile)
* Plugin-based DNS functionality
* Persistent volume for zone files and configuration

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run CoreDNS with a custom zone domain

```bash theme={null}
monk run coredns/coredns -v zone-domain=example.local
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. For production use, it's recommended to inherit this runnable and customize the configuration.

* Preferred: inherit and override variables as shown below.
* Alternative: fork/clone and edit the `variables` in `coredns/coredns.yaml`, then `monk load MANIFEST` and run.

Once started, CoreDNS will be available on port 53 for DNS queries. The default configuration forwards all queries to upstream DNS servers (8.8.8.8 and 9.9.9.9) and serves a custom zone from a file.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  image-tag: "1.11.3"                   # CoreDNS container image tag
  config-dir: "${monk-volume-path}/coredns"  # host path for zone files
  zone-domain: "example.local"          # domain name for your custom zone (required)
```

Zone files are persisted under `${monk-volume-path}/coredns` on the host. Place your zone database files (e.g., `example.local.db`) in this directory.

The default Corefile configuration includes:

* A catch-all zone (`.`) that forwards queries to upstream DNS servers
* A custom zone configured via `zone-domain` variable that serves from a zone file
* Logging and error reporting enabled
* 5-second reload interval for zone file changes

## Use by inheritance (recommended for infrastructure)

Inherit the CoreDNS runnable in your networking infrastructure:

```yaml theme={null}
namespace: myapp
dns-server:
  defines: runnable
  inherits: coredns/coredns
  variables:
    zone-domain:
      value: myapp.local
    image-tag:
      value: 1.11.3
  files:
    zone-file:
      container: coredns
      path: /config/myapp.local.db
      contents: |
        $ORIGIN myapp.local.
        @       3600 IN SOA sns.dns.icann.org. noc.dns.icann.org. (
                                2023010101 ; serial
                                7200       ; refresh
                                3600       ; retry
                                1209600    ; expire
                                3600       ; minimum
                                )
        
        @       IN NS    ns1.myapp.local.
        ns1     IN A     10.0.0.1
        api     IN A     10.0.0.10
        db      IN A     10.0.0.11
        web     IN A     10.0.0.12
```

For more advanced custom configurations, you can override the Corefile:

```yaml theme={null}
namespace: myapp
dns-server:
  defines: runnable
  inherits: coredns/coredns
  variables:
    zone-domain:
      value: myapp.local
  files:
    corefile:
      container: coredns
      path: /etc/coredns/Corefile
      contents: |
        .:53 {
          forward . 1.1.1.1 1.0.0.1
          cache 30
          log
          errors
        }
        
        myapp.local:53 {
          file /config/myapp.local.db {
            reload 5s
          }
          log
          errors
        }
```

Then run your infrastructure:

```bash theme={null}
monk run myapp/dns-server
```

## Ports and connectivity

* Service: `dns` on UDP port `53`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DNS server host.

## Plugins

CoreDNS supports a wide range of plugins. The default configuration uses:

* **forward**: Forwarding queries to upstream DNS servers (8.8.8.8, 9.9.9.9)
* **file**: Serving zone data from files
* **log**: Query logging
* **errors**: Error logging

Additional popular plugins you can enable:

* **kubernetes**: Service discovery for Kubernetes
* **cache**: Caching DNS responses
* **prometheus**: Exporting metrics to Prometheus
* **rewrite**: Rewriting queries
* **etcd**: Backend storage in etcd
* **loadbalance**: Load balancing with random selection

## Persistence and configuration

* Zone files path: `${monk-volume-path}/coredns:/config`
* Corefile location: `/etc/coredns/Corefile` (in container)
* You can place additional zone files in the config path and reference them in your Corefile

## Zone file format

Zone files follow standard DNS zone file format (RFC 1035). Example:

```
$ORIGIN example.local.
@       3600 IN SOA ns1.example.local. admin.example.local. (
                        2023010101 ; serial
                        7200       ; refresh
                        3600       ; retry
                        1209600    ; expire
                        3600       ; minimum
                        )

@       IN NS    ns1.example.local.
ns1     IN A     192.168.1.1
www     IN A     192.168.1.10
api     IN A     192.168.1.11
```

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Integrate with your application stack as needed

## Troubleshooting

* Ensure port 53 is available and not blocked by another DNS service
* Verify your Corefile configuration is valid (use `coredns -conf /etc/coredns/Corefile -validate` inside the container)
* Ensure zone files exist in the config directory and have correct permissions
* Check that `zone-domain` variable is set when running the template
* Check logs:

```bash theme={null}
monk logs -l 500 -f coredns/coredns
```

* Test DNS resolution:

```bash theme={null}
dig @localhost example.local
dig @localhost api.example.local
```

* Verify zone file syntax:

```bash theme={null}
# Check if zone file is readable and properly formatted
monk exec coredns/coredns "cat /config/example.local.db"
```

* If queries are not being answered, ensure the zone file matches the `zone-domain` variable (e.g., if `zone-domain=example.local`, the zone file should be named `example.local.db`)


# DokuWiki
Source: https://docs.monk.io/integrations/monk-dokuwiki

Ready-to-run DokuWiki container template for simple, versatile, and standards-compliant wiki software.

## Overview

This template provides a production‑ready DokuWiki instance as a Monk runnable. You can:

* Run it directly to get a managed wiki for documentation and knowledge management
* Inherit it in your own projects to add collaborative documentation capabilities

DokuWiki is a simple to use and highly versatile wiki software that doesn't require a database. It's loved by users for its clean and readable syntax, ease of maintenance, and built-in access controls.

## What this template manages

* DokuWiki container (PHP-based)
* File-based storage (no database required)
* Web server (Apache or Nginx)
* Plugin and template system
* Web UI on port 80

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run DokuWiki with defaults

```bash theme={null}
monk run dokuwiki/dokuwiki
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `dokuwiki/dokuwiki.yaml`, then `monk load MANIFEST` and run.

Once started, access DokuWiki at `http://localhost:80` (or the runnable hostname inside Monk networks) and complete the initial setup.

Default wiki is publicly viewable. Configure access control in the admin panel.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  dokuwiki-image-tag: "latest"        # DokuWiki image tag
  dokuwiki-port: "80"                 # HTTP port
  wiki-title: "My Wiki"               # wiki title
  admin-username: "admin"             # admin username
  admin-password: "..."               # admin password
```

Data is persisted under `${monk-volume-path}/dokuwiki` on the host.

## Use by inheritance (recommended for teams)

Inherit DokuWiki for team documentation. Example:

```yaml theme={null}
namespace: myteam
docs:
  defines: runnable
  inherits: dokuwiki/dokuwiki
  variables:
    wiki-title: "Team Documentation"
    admin-password: <- secret("dokuwiki-admin-password")
```

Then set the secrets once and run:

```bash theme={null}
monk secrets add -g dokuwiki-admin-password="STRONG_PASSWORD"
monk run myteam/docs
```

## Ports and connectivity

* Service: `dokuwiki` on TCP port `80`
* Web UI accessible at `http://\<host>/`
* Admin panel: `http://\<host>/doku.php?do=admin`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the host.

## Persistence and configuration

* Wiki data: `${monk-volume-path}/dokuwiki/data:/dokuwiki/data`
* Config: `${monk-volume-path}/dokuwiki/conf:/dokuwiki/conf`
* Plugins: `${monk-volume-path}/dokuwiki/plugins:/dokuwiki/lib/plugins`
* Templates: `${monk-volume-path}/dokuwiki/templates:/dokuwiki/lib/tpl`

## Features

* **No Database**: File-based storage is simple and portable
* **Clean Syntax**: Easy-to-learn wiki markup
* **Access Control**: Granular permissions per page and namespace
* **Version Control**: Built-in revision history
* **Media Manager**: Upload and organize images and files
* **Extensible**: 1000+ plugins available
* **Search**: Built-in full-text search
* **Namespaces**: Organize pages hierarchically
* **Templates**: Customizable appearance

## Wiki Syntax

DokuWiki uses simple markup:

```
====== Heading 1 ======
===== Heading 2 =====

**bold** //italic// __underlined__

  * Bullet list
  * Another item

  - Numbered list
  - Another item

[[page_link|Link text]]
{{wiki:image.png|Image}}

<code php>
<?php echo "Code block"; ?>
</code>
```

## Popular Plugins

Extend DokuWiki:

* **Markdown**: Write in Markdown instead of wiki syntax
* **TableEdit**: Edit tables visually
* **Discussion**: Add comments to pages
* **Task**: Create todo lists
* **Gallery**: Image galleries
* **Diagram**: Create diagrams with PlantUML, Graphviz

## Access Control

Configure in Admin → Access Control List:

* Set permissions per namespace or page
* Define user groups
* Control read, write, upload, and delete permissions
* Support for LDAP/AD authentication

## Use cases

DokuWiki excels at:

* Technical documentation
* Team knowledge bases
* Project wikis
* API documentation
* Meeting notes and collaboration
* Personal knowledge management
* Software documentation

## Backup and Migration

DokuWiki is easy to backup:

* All data is in flat files
* Simply backup the `/dokuwiki/data` directory
* No database dumps required
* Restore by copying files to new installation

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Integrate with your application stack as needed

## Troubleshooting

* Access admin panel at `http://localhost/doku.php?do=admin`
* First-time setup runs automatically on first access
* Reset admin password by editing `conf/users.auth.php`
* For permission issues, check file permissions on data directory
* For plugin issues, disable in `conf/plugins.local.php`
* Enable debugging in `conf/local.php` for detailed error messages
* Clear cache: Admin → Configuration Settings → Clear cache
* Check logs:

```bash theme={null}
monk logs -l 500 -f local/dokuwiki/dokuwiki
```


# DolphinDB
Source: https://docs.monk.io/integrations/monk-dophindb

Ready-to-run DolphinDB container template you can run directly or inherit to integrate a high-performance time-series database into your stack.

## Overview

This template provides a production‑ready DolphinDB instance as a Monk runnable. You can:

* Run it directly to get a managed DolphinDB container with sensible defaults
* Inherit it in your own runnable to seamlessly add a high-performance time-series database to your stack

DolphinDB is a high-performance distributed time-series database designed for financial and IoT data analytics. It combines in-memory computing with a columnar storage engine to deliver exceptional query performance on massive datasets.

It exposes DolphinDB on port 8848, persists data to a host volume, and provides a web-based interface for database management and queries.

## What this template manages

* DolphinDB container (configurable image tag)
* Network service on port 8848
* Persistent volumes for data storage

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run DolphinDB with defaults

```bash theme={null}
monk run dolphindb/dolphindb
```

3. Customize settings (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `dolphindb.yml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:8848` (or the runnable hostname inside Monk networks) to access the DolphinDB web interface.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  image_tag: "v2.00.9"    # container image tag
  db_port: "8848"         # DolphinDB service port (default: 8848)
```

Data is persisted under `${monk-volume-path}/dolphindb` on the host.

## Use by inheritance (recommended for apps)

Inherit the DolphinDB runnable in your time-series application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
tsdb:
  defines: runnable
  inherits: dolphindb/dolphindb
analytics:
  defines: runnable
  containers:
    app:
      image: myorg/analytics
  connections:
    database:
      runnable: tsdb
      service: dolphindb
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-port:
      value: "8848"
```

Then run your app group:

```bash theme={null}
monk run myapp/analytics
```

## Ports and connectivity

* Service: `dolphindb` on TCP port `8848`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence and configuration

* Data path: `${monk-volume-path}/dolphindb:/data`
* DolphinDB stores all databases and time-series data in this directory

## Use cases

DolphinDB excels at:

* Financial market data analysis
* IoT sensor data processing
* Real-time streaming analytics
* High-frequency trading systems
* Time-series forecasting

## Related templates

* Combine with `grafana/` for time-series visualization
* Integrate with `telegraf/` for metrics collection and monitoring

## Troubleshooting

* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f dolphindb/dolphindb
```


# Apache Druid
Source: https://docs.monk.io/integrations/monk-druid

Ready-to-run Apache Druid container stack you can run directly or inherit to integrate a real-time analytics database into your infrastructure.

## Overview

This template provides a production‑ready Apache Druid stack as a Monk runnable. You can:

* Run it directly to get a managed Druid deployment with all necessary components
* Inherit it in your own stack to seamlessly add real-time analytics capabilities

Apache Druid is a high-performance real-time analytics database designed for workflows where fast queries and ingest really matter. It excels at powering UIs, running operational (ad-hoc) queries, or handling high concurrency workloads.

## What this template manages

* Druid coordinator (cluster management)
* Druid broker (query routing)
* Druid router (HTTP routing)
* Druid historical (segment serving)
* Druid middlemanager (task execution)
* PostgreSQL database (metadata storage)
* ZooKeeper (coordination)

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Druid stack with defaults

```bash theme={null}
monk run druid/stack
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `stack.yml`, then `monk load MANIFEST` and run.

Once started, access the Druid console at `http://localhost:8888` (router) or query the broker at `http://localhost:8082`.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  image_tag: "v2.00.9"                                # Druid container image tag
  java_xmx: "1024m"                                   # Maximum heap size
  java_xms: "1024m"                                   # Initial heap size
  java_max_new_size: "256m"                           # Java max new size
  java_max_direct_memory: "512m"                      # Max direct memory size
  single_node: "micro-quickstart"                     # Single node configuration
  log_level: "debug"                                  # Log level (debug, info, warn, error)
  metadata_storage_type: "postgresql"                 # Metadata storage backend
  metadata_storage_connector_user: "monk"             # Metadata DB user
  metadata_storage_connector_password: "monk"         # Metadata DB password
  droid_storage_type: "local"                         # Storage type (local, s3, etc.)
  droid_storage_directory: "/opt/shared"              # Local storage directory
  druid_processing_num: "2"                           # Number of processing threads
  druid_processing_num_merge: "2"                     # Number of merge buffers
  druid_processing_buffer: "56m"                      # Processing buffer size
  coordinator_balance: "cachingCost"                  # Coordinator balance strategy
```

Data and deep storage are persisted under `${monk-volume-path}/druid` on the host.

## Stack components

The Druid stack includes the following runnables:

* `druid/coordinator` - Cluster management and segment assignment
* `druid/broker` - Query routing and result merging
* `druid/router` - HTTP request routing
* `druid/historical` - Segment storage and querying
* `druid/middlemanager` - Task execution and ingestion
* `druid/db` - PostgreSQL metadata storage
* `druid/dzookeeper` - ZooKeeper coordination

## Use by inheritance (recommended for apps)

Inherit the Druid stack in your application and declare connections. Example:

```yaml theme={null}
namespace: myapp
analytics:
  defines: runnable
  inherits: druid/stack
  variables:
    metadata_storage_connector_password:
      value: <- secret("druid-db-password")
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    druid:
      runnable: analytics
      service: broker
  variables:
    druid-broker-url:
      value: <- connection-hostname("druid") concat-all ":" connection-port("druid")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g druid-db-password="STRONG_DB_PASSWORD"
monk run myapp/api
```

## Features

* **Real-time Ingestion**: Ingest streaming data with exactly-once semantics
* **Fast Queries**: Sub-second queries on large datasets
* **Scalable**: Horizontally scalable architecture
* **Column-oriented**: Efficient storage and query execution
* **Multi-tenant**: Supports multiple tenants and workloads
* **SQL Support**: Query using SQL or native queries

## Ports and connectivity

* Service: `router` on TCP port `8888` (web console)
* Service: `broker` on TCP port `8082` (query API)
* Service: `coordinator` on TCP port `8081`
* Service: `historical` on TCP port `8083`
* Service: `middlemanager` on TCP port `8091`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the service host.

## Persistence and configuration

* Deep storage path: `${monk-volume-path}/druid:/opt/shared`
* PostgreSQL data: `${monk-volume-path}/postgresql:/var/lib/postgresql/data`
* ZooKeeper data: `${monk-volume-path}/zookeeper:/data`
* You can adjust JVM settings and Druid configuration through the template variables.

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Integrate with your application stack as needed

## Troubleshooting

* Ensure all required ports are available (8081-8083, 8088, 8091, 8888)
* Druid requires ZooKeeper and metadata storage (PostgreSQL) to be running first
* If you changed `metadata_storage_connector_password` but the database has existing data, authentication may fail. Either reset the data volume or update the password in PostgreSQL.
* Ensure the host volumes are writable by the container user
* Check logs for any component:

```bash theme={null}
monk logs -l 500 -f local/druid/stack
monk logs -l 500 -f local/druid/broker
```

* Verify JVM settings are appropriate for your workload
* Ensure sufficient memory is available for the configured heap sizes
* For single-node deployments, use `single_node: "micro-quickstart"` or `"small"`


# ELK Stack
Source: https://docs.monk.io/integrations/monk-elk

Ready-to-run ELK Stack (Elasticsearch, Logstash, Kibana) container stack you can run directly or inherit to integrate logging and analytics into your infrastructure.

## Overview

This template provides a production‑ready ELK Stack as a Monk runnable. You can:

* Run it directly to get a managed ELK deployment with all necessary components
* Inherit it in your own stack to seamlessly add logging, search, and analytics capabilities

The ELK Stack (Elasticsearch, Logstash, Kibana) is a powerful combination of tools for searching, analyzing, and visualizing log data in real time. This template includes Nginx as a reverse proxy for secure access to Kibana.

## What this template manages

* Elasticsearch container (search and analytics engine)
* Logstash container (data processing pipeline)
* Kibana container (visualization and management interface)
* Nginx container (reverse proxy)
* Network services on multiple ports
* Persistent volumes for data storage
* Custom configuration files for all components

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run ELK stack with defaults

```bash theme={null}
monk run elk/stack
```

3. Access Kibana

Once started, access Kibana through Nginx at `http://localhost` (default port 80).

Running directly uses the defaults defined in this template's `variables`. To customize settings like ports or JVM options, you should either:

* Preferred: inherit and override variables as shown below
* Alternative: fork/clone and edit the `variables` in `elk/stack.yaml`, then `monk load MANIFEST` and run

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  elasticsearch-image-tag: "8.15.3"         # Elasticsearch container image tag
  elasticsearch-jvm-options: "-Xmx256m -Xms256m"  # JVM heap settings
  elasticsearch-http-port: 9200             # HTTP API port
  elasticsearch-internal-port: 9300         # Internal cluster communication
  kibana-image-tag: "8.15.3"                # Kibana container image tag
  kibana-http-port: 5601                    # Kibana web interface port
  logstash-image-tag: "8.15.3"              # Logstash container image tag
  logstash-jvm-options: "-Xmx256m -Xms256m" # JVM heap settings
  logstash-http-port: 9600                  # Logstash API port
  nginx-listen-port: 80                     # Nginx proxy port (host-exposed)
  nginx-image-tag: "latest"                 # Nginx container image tag
```

Data is persisted under `${monk-volume-path}/elasticsearch/data` and `${monk-volume-path}/kibana/data` on the host.

## Configuration files

You can find configuration files in the `/files` directory:

| Configuration File         | Directory in Container                              | Purpose                                         |
| -------------------------- | --------------------------------------------------- | ----------------------------------------------- |
| **elasticsearch.yml**      | `/usr/share/elasticsearch/config/elasticsearch.yml` | Primary Elasticsearch configuration             |
| **kibana.yml**             | `/usr/share/kibana/config/kibana.yml`               | Kibana server configuration                     |
| **logstash.yml**           | `/usr/share/logstash/config/logstash.yml`           | Logstash execution settings                     |
| **pipeline/logstash.conf** | `/usr/share/logstash/pipeline/logstash.conf`        | Logstash data processing pipeline configuration |

These files are automatically mounted into the containers. You can modify them before loading to customize the stack behavior.

## Use by inheritance (recommended for apps)

Inherit the ELK stack in your logging infrastructure and customize it:

```yaml theme={null}
namespace: myapp

logging:
  defines: process-group
  inherits: elk/stack
  variables:
    nginx-listen-port: 8080
    elasticsearch-jvm-options: "-Xmx2g -Xms2g"
    logstash-jvm-options: "-Xmx1g -Xms1g"

api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    logging:
      runnable: logging/elasticsearch
      service: elasticsearch
  variables:
    elasticsearch-host:
      value: <- connection-hostname("logging")
    elasticsearch-port:
      value: 9200
```

Then run your app group:

```bash theme={null}
monk run myapp/api
```

Your application can now send logs to the Elasticsearch instance and visualize them through Kibana accessible at `http://localhost:8080`.

## Stack components

The ELK stack includes the following runnables:

* `elk/elasticsearch` - Search and analytics engine (ports 9200, 9300)
* `elk/kibana` - Visualization interface (port 5601)
* `elk/logstash` - Data processing pipeline (ports 5044, 50000, 9600)
* `elk/nginx` - Reverse proxy (port 80)

All components are interconnected and start in the correct dependency order.

## Ports and connectivity

* **Nginx proxy**: TCP port `80` (configurable via `nginx-listen-port`)
  * Exposed to host for external access to Kibana
* **Elasticsearch HTTP API**: TCP port `9200`
  * Used by Kibana, Logstash, and applications
* **Elasticsearch internal**: TCP port `9300`
  * Internal cluster communication
* **Kibana**: TCP port `5601`
  * Proxied through Nginx
* **Logstash Beats**: TCP port `5044`
  * For receiving logs from Beats agents
* **Logstash TCP**: TCP port `50000`
  * For receiving logs via TCP
* **Logstash API**: TCP port `9600`
  * Monitoring and management

From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve component hostnames.

## Persistence and configuration

Data paths (persisted to host volumes):

* Elasticsearch data: `${monk-volume-path}/elasticsearch/data:/usr/share/elasticsearch/data`
* Kibana data: `${monk-volume-path}/kibana/data:/usr/share/kibana/data`

These volumes ensure your data persists across container restarts and updates.

## Features

* **Elasticsearch**: Distributed search and analytics engine with single-node configuration by default
* **Logstash**: Flexible data collection and transformation pipeline with customizable filters
* **Kibana**: Rich visualization and exploration interface for your data
* **Nginx**: Secure reverse proxy with customizable configuration for external access
* **Auto-connectivity**: Components are pre-configured to communicate with each other
* **Health monitoring**: Built-in health checks and dependency management

## Logs and shell access

```bash theme={null}
# Show Elasticsearch logs
monk logs -l 1000 -f elk/elasticsearch

# Show Kibana logs
monk logs -l 1000 -f elk/kibana

# Show Logstash logs
monk logs -l 1000 -f elk/logstash

# Show Nginx logs
monk logs -l 1000 -f elk/nginx

# Show all stack logs
monk logs -l 500 -f elk/stack

# Access shell in Elasticsearch container
monk shell elk/elasticsearch

# Access shell in Kibana container
monk shell elk/kibana

# Access shell in Logstash container
monk shell elk/logstash
```

## Related templates

* Integrate with monitoring tools (Prometheus, Grafana)
* Use with alerting systems (PagerDuty, Slack, email)
* Combine with log shippers (`filebeat/`, `metricbeat/`, `fluentbit/`)
* Connect to application stacks for centralized logging

## Troubleshooting

* **Ensure all required ports are available**: Check that ports 80, 5601, 9200, 9300, 5044, 50000, and 9600 are not in use.
* **Verify JVM heap settings are appropriate for your system**: The default 256MB may be too low for production workloads. Increase via `elasticsearch-jvm-options` and `logstash-jvm-options`.
* **Elasticsearch requires sufficient memory**: If Elasticsearch fails to start, check available memory. Production deployments typically need at least 2GB heap.
* **Check that all components start in the correct order**: Dependencies are configured, but network issues can cause timeouts.
* **Ensure host volumes are writable**: Containers run as user `1000`, ensure volume paths have appropriate permissions.

Check logs for any component:

```bash theme={null}
monk logs -l 500 -f elk/stack
```

If you encounter startup issues, try purging and restarting:

```bash theme={null}
monk purge -x elk/stack
monk run elk/stack
```

If Elasticsearch health checks fail, verify the node has sufficient resources and the discovery type is set correctly for your deployment (single-node by default).


# etcd
Source: https://docs.monk.io/integrations/monk-etcd

Ready-to-run etcd container cluster you can run directly or inherit to integrate a distributed key-value store into your infrastructure.

## Overview

This template provides a production‑ready etcd cluster as a Monk runnable. You can:

* Run it directly to get a managed etcd 3-node cluster with sensible defaults
* Inherit it in your own runnable to seamlessly add a distributed key-value store to your infrastructure

etcd is a strongly consistent, distributed key-value store that provides a reliable way to store data that needs to be accessed by a distributed system or cluster of machines. It is used by Kubernetes and many other distributed systems for configuration management, service discovery, and coordinating distributed work.

## What this template manages

* 3-node etcd cluster (high availability)
* Network services on configurable ports
* Persistent volumes for data storage
* Cluster coordination and consensus using Raft algorithm

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run etcd cluster with defaults

```bash theme={null}
monk run etcd/stack
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. For production deployments, we recommend inheriting the template and customizing variables as shown in the next section.

Once started, the etcd cluster will be available on the configured ports (default: 2391, 2392, 2393).

## Configuration

Key variables you can customize in this template (in `stack.yml`):

```yaml theme={null}
variables:
  monk_etcd1_port: "2391"    # etcd node 1 client port
  monk_etcd2_port: "2392"    # etcd node 2 client port
  monk_etcd3_port: "2393"    # etcd node 3 client port
  monk_etcd_debug: "1"       # etcd debug mode (set to "0" for production)
```

Data is persisted under `${monk-volume-path}/etcd` on each node. Internal cluster communication uses port `2380` for peer-to-peer connectivity.

## Stack components

The etcd stack includes the following runnables:

* `etcd/etcd1` - First etcd cluster node (client port 2391, peer port 2380)
* `etcd/etcd2` - Second etcd cluster node (client port 2392, peer port 2380)
* `etcd/etcd3` - Third etcd cluster node (client port 2393, peer port 2380)

## Use by inheritance (recommended for apps)

Inherit the etcd cluster in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
kvstore:
  defines: runnable
  inherits: etcd/stack
  variables:
    monk_etcd_debug: "0"       # disable debug in production
    monk_etcd1_port: "2379"    # use standard etcd port
app:
  defines: runnable
  containers:
    service:
      image: myorg/app
      environment:
        - ETCD_ENDPOINTS=<- connection-hostname("etcd") concat ":2379"
  connections:
    etcd:
      runnable: kvstore
      service: etcd1
```

Then run your application group:

```bash theme={null}
monk run myapp/app
```

## Ports and connectivity

* **Client Communication:**
  * etcd node 1: TCP port `2391` (configurable via `monk_etcd1_port`)
  * etcd node 2: TCP port `2392` (configurable via `monk_etcd2_port`)
  * etcd node 3: TCP port `2393` (configurable via `monk_etcd3_port`)
* **Cluster Communication:**
  * Internal peer-to-peer: TCP port `2380` (fixed)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the etcd cluster endpoint.

## Persistence and data storage

* Data path: `${monk-volume-path}/etcd-X:/etcd-data` (where X is 1, 2, or 3 for each node)
* Each node maintains its own data directory for the Raft log and snapshots
* Data persists across container restarts
* Ensure sufficient disk space for your use case (etcd stores all data in memory and on disk)

## Features

* **Distributed Consensus**: Uses Raft consensus algorithm for strong consistency
* **High Availability**: 3-node cluster tolerates one node failure
* **Watch API**: Monitor key changes in real-time
* **TTL Keys**: Automatic key expiration
* **Secure**: TLS client cert authentication and RBAC support
* **Fast**: Benchmark up to 10,000 writes per second
* **Transactional**: Multi-key transactions with if/then/else semantics

## Use cases

etcd is ideal for:

* **Service discovery and configuration**: Store service endpoints and app config
* **Distributed locking**: Coordinate access to shared resources
* **Leader election**: Ensure only one leader in distributed systems
* **Cluster coordination**: Synchronize distributed workloads
* **Configuration management**: Used by Kubernetes for cluster state
* **Metadata storage**: Store cluster and application metadata

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Integrate with your application stack for service discovery and configuration
* Use with container orchestration systems for state management

## Troubleshooting

* **Cluster won't form**: Ensure all three nodes can communicate on port 2380. Check firewall rules and network connectivity.
* **Port conflicts**: Verify that ports 2391, 2392, 2393, and 2380 are not in use by other services.
* **Performance issues**: Disable debug mode (`monk_etcd_debug: "0"`) and ensure sufficient disk I/O performance.
* **Split brain**: etcd requires a quorum (2 out of 3 nodes). If two nodes fail, the cluster becomes read-only.

Check logs:

```bash theme={null}
monk logs -l 500 -f etcd/stack
monk logs -l 500 -f etcd/etcd1
monk logs -l 500 -f etcd/etcd2
monk logs -l 500 -f etcd/etcd3
```

Verify cluster health:

```bash theme={null}
monk shell etcd/etcd1
etcdctl cluster-health
etcdctl member list
```

Access etcd data:

```bash theme={null}
monk shell etcd/etcd1
etcdctl put mykey "Hello etcd"
etcdctl get mykey
```


# GitLab
Source: https://docs.monk.io/integrations/monk-gitlab

Ready-to-run GitLab container stack you can run directly or inherit to integrate a complete DevOps platform into your infrastructure.

## Overview

This template provides a production‑ready GitLab stack as a Monk runnable. You can:

* Run it directly to get a managed GitLab instance with runner support
* Inherit it in your own stack to seamlessly add a complete DevOps platform

GitLab is a complete DevOps platform delivered as a single application. It provides Git repository management, issue tracking, code review, CI/CD, and more. This template includes both the GitLab server and GitLab Runner for executing CI/CD pipelines.

## What this template manages

* GitLab CE (Community Edition) server
* GitLab Runner (for CI/CD job execution)
* Persistent volumes for repositories, data, logs, and configuration
* SSH and HTTP/HTTPS access
* Container Registry for Docker images

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run GitLab stack with defaults

```bash theme={null}
monk run gitlab/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in the manifest files, then `monk load MANIFEST` and run.

Once started (may take several minutes on first launch), access GitLab at the configured URL.

Default root password: `z123z123` (change this in production!)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  ssh-port: "22"                                    # SSH port for git operations
  gitlab-url: "<- http:// + ip-address-public"     # GitLab instance URL
  gitlab-root-password: "z123z123"                 # Default root password (env: GITLAB_ROOT_PASSWORD)
```

Data is persisted under `${monk-volume-path}/gitlab-data` on the host. Configuration, logs, and repository data are stored in separate subdirectories.

## Stack components

The GitLab stack includes the following runnables:

* `gitlab/server` - GitLab CE server (ports 80, 22, 443, 5050)
* `gitlab/runner` - GitLab Runner for CI/CD

## Register a GitLab Runner

To register a runner with your GitLab instance:

1. Obtain a runner registration token from the GitLab UI (Admin → Runners section)
2. Run the following command:

```bash theme={null}
monk do gitlab/runner/register token=<Token> url=<Your_Gitlab_URL>
```

## Use by inheritance (recommended for production)

Inherit the GitLab stack in your infrastructure and declare connections. Example:

```yaml theme={null}
namespace: mycompany
gitlab:
  defines: process-group
  inherits: gitlab/stack
  variables:
    gitlab-url: "https://gitlab.mycompany.com"
    gitlab-root-password:
      value: <- secret("gitlab-root-password")
    ssh-port: "2222"
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    devops:
      runnable: gitlab
      service: gitlab
  variables:
    gitlab-host:
      value: <- connection-hostname("devops")
```

Then set the secrets once and run your infrastructure:

```bash theme={null}
monk secrets add -g gitlab-root-password="STRONG_ROOT_PASSWORD"
monk run mycompany/gitlab
```

## Ports and connectivity

* HTTP: Service `gitlab` on TCP port `80`
* HTTPS: Service `gitlab` on TCP port `443`
* SSH: TCP port `22` (configurable via `ssh-port` variable)
* Container Registry: TCP port `5050`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the GitLab host.

## Persistence and configuration

* Configuration path: `${monk-volume-path}/gitlab-data/config:/etc/gitlab`
* Data path: `${monk-volume-path}/gitlab-data/data:/var/opt/gitlab`
* Logs path: `${monk-volume-path}/gitlab-data/logs:/var/log/gitlab`

### Persistency with cloud volumes

If you're using any of the clouds available via Monk, you can use volume definition to spin a disk block device to make your GitLab instance independent from the node it's running on. To do so, uncomment the `volume` block in `manifest.yaml`.

## Features

* **Git Repository Management**: Full-featured Git repository hosting
* **CI/CD**: Integrated continuous integration and deployment pipelines
* **Issue Tracking**: Built-in issue and project management
* **Code Review**: Merge requests with inline commenting
* **Container Registry**: Built-in Docker registry
* **Wiki**: Per-project wikis for documentation
* **Snippets**: Code snippets sharing

## Create your own template with multiple runners

You can create your own template and inherit the defaults to add more runners:

```yaml theme={null}
namespace: /gitlab

runner-1:
  defines: runnable
  inherits: /gitlab/runner

runner-2:
  defines: runnable
  inherits: /gitlab/runner

runner-3:
  defines: runnable
  inherits: /gitlab/runner

runner-stack:
  defines: process-group
  runnable-list:
    - /gitlab/runner-1
    - /gitlab/runner-2
    - /gitlab/runner-3
```

## Related templates

* High‑availability setup: consider load balancing multiple GitLab instances for production deployments
* Integrate with artifact repositories: see `nexus/` or `artifactory/` templates for artifact management
* Database backends: MariaDB, PostgreSQL templates for external database configuration

## Troubleshooting

* GitLab may take 5-10 minutes to fully start on first launch.
* Ensure sufficient system resources (minimum 4GB RAM, 8GB recommended for production).
* Check that all required ports are available and not blocked by firewalls.
* Verify SSH access is properly configured and the SSH port is accessible.
* If you changed `gitlab-root-password` after initial setup, you may need to reset it inside GitLab or purge the data volume.
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f gitlab/stack
monk logs -l 500 -f gitlab/server
```

* If you encounter startup issues, try purging and restarting:

```bash theme={null}
monk purge gitlab/server gitlab/runner
monk purge -x gitlab/server gitlab/runner
monk run gitlab/stack
```


# Gost
Source: https://docs.monk.io/integrations/monk-gost

Ready-to-run Gost container template you can run directly or inherit to integrate a tunnel/proxy server into your stack.

## Overview

This template provides a production‑ready Gost instance as a Monk runnable. You can:

* Run it directly to get a managed tunnel/proxy server with sensible defaults
* Inherit it in your own runnable to seamlessly add secure tunneling and forwarding to your stack

Gost (GO Simple Tunnel) is a simple security tunnel written in Golang. It supports multiple protocols (SOCKS5, HTTP/HTTPS, SS, SSR, SNI, TLS, KCP, Quic) and can work as a local/remote port forwarder, SOCKS/HTTP proxy, and more.

## What this template manages

* Gost container (`ginuerzh/gost` image, configurable tag)
* Network service on configured port (default 8080 or 1080)
* Persistent volumes for configuration
* Optional authentication and encryption
* Support for proxy chaining and multiple protocols

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Gost with defaults

```bash theme={null}
monk run gost/gost
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `gost/gost.yaml`, then `monk load MANIFEST` and run.

Once started, Gost will listen on configured ports for proxy connections. Connect to `localhost:8080` (or the runnable hostname inside Monk networks) using the configured protocol and credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  gost-image-tag: "latest"            # container image tag
  listen-port: "8080"                 # main listening port
  proxy-mode: "http"                  # protocol: http, socks5, ss, relay, etc.
  auth-user: "user"                   # authentication username
  auth-password: "..."                # authentication password
  gost-config: "..."                  # optional Gost JSON configuration
```

Configuration is persisted under `${monk-volume-path}/gost` on the host. Custom Gost config files are mounted from `${monk-volume-path}/gost/config:/etc/gost`.

## Use by inheritance (recommended for apps)

Inherit the Gost runnable in your application for secure tunneling. Example:

```yaml theme={null}
namespace: myapp
proxy:
  defines: runnable
  inherits: gost/gost
  variables:
    proxy-mode: "socks5"
    listen-port: "1080"
    auth-user: <- secret("gost-user")
    auth-password: <- secret("gost-password")
backend:
  defines: runnable
  containers:
    app:
      image: myorg/app
  connections:
    tunnel:
      runnable: proxy
      service: gost
  variables:
    proxy-host:
      value: <- connection-hostname("tunnel")
    proxy-port:
      value: "1080"
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g gost-user="proxyuser"
monk secrets add -g gost-password="STRONG_PASSWORD"
monk run myapp/backend
```

## Ports and connectivity

* Service: `gost` on TCP port as configured (default `8080` for HTTP, `1080` for SOCKS5)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the proxy host.

## Persistence and configuration

* Config path: `${monk-volume-path}/gost/config:/etc/gost`
* You can drop additional JSON config files into the config path to configure Gost.

## Features

* **Multiple Protocols**: SOCKS4/5, HTTP/HTTPS, SS, SSR, SNI, TLS, KCP, Quic
* **Port Forwarding**: Local and remote port forwarding
* **Proxy Chain**: Chain multiple proxies together
* **Authentication**: Username/password auth
* **Encryption**: TLS/SSL, Shadowsocks encryption
* **Load Balancing**: Round-robin, random, least-connections
* **Traffic Routing**: Rule-based routing
* **UDP Support**: UDP over TCP tunneling

## Proxy Modes

**HTTP Proxy**:

```bash theme={null}
gost -L=http://user:pass@:8080
```

**SOCKS5 Proxy**:

```bash theme={null}
gost -L=socks5://user:pass@:1080
```

**Port Forwarding**:

```bash theme={null}
# Forward local 8080 to remote 80
gost -L=tcp://:8080/remote-host:80
```

**Reverse Proxy**:

```bash theme={null}
# Forward remote port to local
gost -L=rtcp://:8080/:8080 -F=relay://server:1234
```

**Shadowsocks**:

```bash theme={null}
gost -L=ss://aes-256-cfb:password@:8338
```

## Configuration File

Example JSON config (`config.json`):

```json theme={null}
{
  "Debug": true,
  "ServeNodes": [
    "http://user:pass@:8080",
    "socks5://user:pass@:1080"
  ],
  "ChainNodes": [
    "http://upstream-proxy:8080"
  ]
}
```

## Proxy Chaining

Chain multiple proxies for enhanced security or routing:

```bash theme={null}
gost -L=:8080 -F=http://proxy1:8080 -F=socks5://proxy2:1080
```

Request flow: Client → Gost → proxy1 → proxy2 → Destination

## Client Configuration

Configure clients to use Gost:

**Browser (SOCKS5)**:

* Proxy: `localhost`
* Port: `1080`
* SOCKS v5

**curl**:

```bash theme={null}
# HTTP proxy
curl -x http://user:pass@localhost:8080 https://example.com

# SOCKS5 proxy
curl -x socks5://user:pass@localhost:1080 https://example.com
```

**SSH through proxy**:

```bash theme={null}
ssh -o ProxyCommand="nc -X 5 -x localhost:1080 %h %p" user@remote-host
```

## Use cases

Gost excels at:

* Secure HTTP/SOCKS proxy for applications
* Port forwarding and tunneling
* Bypassing network restrictions
* Secure remote access
* Load balancing across multiple proxies
* Traffic routing and redirection
* Development and testing proxies

## Related templates

* High-availability proxy cluster: see other templates in this repository for clustered setups.
* Combine with monitoring tools for observability.

## Troubleshooting

* Test proxy connection:

```bash theme={null}
# HTTP proxy
curl -x http://user:pass@localhost:8080 https://ifconfig.me

# SOCKS5 proxy
curl -x socks5://user:pass@localhost:1080 https://ifconfig.me
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f gost/gost
```

* Enable debug mode in config for verbose logging.
* For connection issues:
  * Verify firewall allows the proxy port
  * Check authentication credentials match
  * Test without proxy chain first
  * Ensure the container is running and listening
* For performance issues, try different protocols (KCP for UDP, Quic for modern encryption).
* Monitor bandwidth usage for proxy traffic to detect issues.


# Graphite
Source: https://docs.monk.io/integrations/monk-graphite

Ready-to-run Graphite container template you can run directly or inherit to integrate a time-series monitoring and graphing system into your infrastructure.

## Overview

This template provides a production‑ready Graphite instance as a Monk runnable. You can:

* Run it directly to get a managed Graphite container with sensible defaults
* Inherit it in your own runnable to seamlessly add time-series metrics storage and visualization to your stack

It exposes Graphite's web UI on port 80, the Carbon plaintext protocol on port 2003 for metrics ingestion, and StatsD management interface on port 8126. The template uses an all-in-one container that includes Carbon (metric collection), Whisper (storage), and Graphite-Web (visualization).

## What this template manages

* Graphite container (`graphiteapp/graphite-statsd` image, configurable tag)
* Network services:
  * Web UI on port 80
  * Carbon plaintext protocol on port 2003
  * StatsD management on port 8126
* Time-series data storage and visualization

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Graphite with defaults

```bash theme={null}
monk run graphite/db
```

3. Customize port (optional)

Running directly uses the defaults defined in this template's `variables`.

* Preferred: inherit and customize variables as shown below.
* Alternative: fork/clone and edit the `variables` in `graphite.yml`, then `monk load MANIFEST` and run.

Once started, access the web UI at `http://localhost:80` (or the configured `gui_port`) and send metrics to port 2003.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  image: "1.1.10-4"       # container image tag
  gui_port: 80            # web UI host port
```

## Use by inheritance (recommended for apps)

Inherit the Graphite runnable in your application to add metrics collection. Example:

```yaml theme={null}
namespace: myapp
metrics:
  defines: runnable
  inherits: graphite/db
  variables:
    gui_port:
      value: 8080
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
      environment:
        - GRAPHITE_HOST=<- connection-hostname("metrics-connection")
        - GRAPHITE_PORT=2003
  connections:
    metrics-connection:
      runnable: metrics
      service: plaintext-svc
```

Then run your app group:

```bash theme={null}
monk run myapp/api
```

## Ports and connectivity

* Service: `gui-svc` on TCP port `80` (web UI, configurable via `gui_port`)
* Service: `plaintext-svc` on TCP port `2003` (Carbon plaintext protocol for metrics ingestion)
* Service: `management-svc` on TCP port `8126` (StatsD management interface)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Graphite host.

## Sending metrics to Graphite

You can send metrics using the plaintext protocol on port 2003:

```bash theme={null}
echo "test.metric 42 $(date +%s)" | nc localhost 2003
```

Or use one of the many Graphite client libraries available for various languages.

## Features

* Time-series data storage with Whisper database
* Real-time graphing and visualization
* Multiple data retention policies
* Carbon plaintext and pickle protocols
* Built-in StatsD daemon
* HTTP API for data queries
* Dashboard creation and sharing
* Graphite Query Language (GQL) for data manipulation

## Related templates

* Combine with `grafana/` for advanced visualization and dashboards
* Integrate with `telegraf/` for comprehensive metrics collection
* Use with `prometheus/` for additional monitoring capabilities

## Troubleshooting

* If the web UI is not accessible, verify that the `gui_port` is not already in use and check firewall rules.
* Ensure metrics are being sent to the correct port (2003 for plaintext protocol).
* Check logs:

```bash theme={null}
monk logs -l 500 -f graphite/db
```

* To verify metrics are being received, check the web UI's "Composer" view or query the API directly.


# GridDB
Source: https://docs.monk.io/integrations/monk-griddb

Ready-to-run GridDB container template you can run directly or inherit to integrate a scalable time-series database optimized for IoT and big data into your stack.

## Overview

This template provides a production‑ready GridDB instance as a Monk runnable. You can:

* Run it directly to get a managed GridDB container with sensible defaults
* Inherit it in your own runnable to seamlessly add a high-performance time-series database to your stack

It exposes GridDB on port 31999, persists data to a host volume, and can be configured with cluster settings for distributed deployments.

## What this template manages

* GridDB container (`griddb/griddb` image, configurable tag)
* Network service on port 31999
* Persistent volumes for data storage
* Optional cluster configuration and authentication

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run GridDB with defaults

```bash theme={null}
monk run griddb/griddb
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `griddb.yml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:31999` (or the runnable hostname inside Monk networks) using the configured credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  image_tag: "4.6.1-focal"         # container image tag
  cluster_name: "monk"             # cluster name (env: GRIDDB_CLUSTER_NAME)
  password: "monk"                 # admin password (env: GRIDDB_PASSWORD)
  notif_member: "1"                # notification member count (env: NOTIFICATION_MEMBER)
  notif_address: "239.0.0.1"       # multicast address (env: NOTIFICATION_ADDRESS)
```

Data is persisted using GridDB's internal storage mechanisms. The database uses a hybrid in-memory and on-disk architecture for optimal performance.

## Use by inheritance (recommended for apps)

Inherit the GridDB runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
tsdb:
  defines: runnable
  inherits: griddb/griddb
api:
  defines: runnable
  containers:
    api:
      image: myorg/iot-api
  connections:
    timeseries-db:
      runnable: tsdb
      service: db-svc
  variables:
    griddb-host:
      value: <- connection-hostname("timeseries-db")
    griddb-port:
      value: <- connection-port("timeseries-db")
    griddb-cluster:
      value: <- secret("griddb-cluster-name")
    griddb-password:
      value: <- secret("griddb-password")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g griddb-cluster-name="production-cluster"
monk secrets add -g griddb-password="STRONG_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `db-svc` on TCP port `31999`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the GridDB host.

## Persistence and configuration

* GridDB uses an internal hybrid storage architecture combining in-memory and on-disk persistence
* Data is automatically persisted according to GridDB's configuration
* For cluster deployments, configure the `notif_member` and `notif_address` variables appropriately

## Features

* In-memory and on-disk hybrid architecture
* Time-series data optimization
* High-speed data ingestion
* SQL-like query language (TQL)
* ACID transaction support
* Horizontal scalability with multi-node clusters
* Multi-master replication support

## Related templates

* Combine with `grafana/` for time-series visualization
* Integrate with `telegraf/` for metrics collection
* Use with IoT data ingestion pipelines

## Troubleshooting

* If you changed the `password` but the container has existing data, authentication may fail. Either reset the data volume or update the password configuration.
* For cluster deployments, ensure all nodes can communicate on the configured multicast address.
* Check logs:

```bash theme={null}
monk logs -l 500 -f griddb/griddb
```


# Apache Hadoop
Source: https://docs.monk.io/integrations/monk-hadoop

Ready-to-run Apache Hadoop container stack you can run directly or inherit to integrate distributed data processing into your infrastructure.

## Overview

This template provides a production‑ready Apache Hadoop stack as a Monk runnable. You can:

* Run it directly to get a managed Hadoop cluster with sensible defaults
* Inherit it in your own runnable to seamlessly add distributed data processing and storage to your stack

Apache Hadoop is an open-source framework for distributed storage and processing of large datasets using the MapReduce programming model. It includes HDFS (Hadoop Distributed File System) for storage and YARN for resource management.

## What this template manages

* Hadoop NameNode (HDFS master) with HTTP interface on port 9870
* Hadoop DataNode (HDFS storage) on port 9864
* Resource Manager (YARN) on port 8088
* NodeManager (YARN compute)
* History Server for job tracking on port 8188
* Persistent volumes for NameNode, DataNode, and HistoryServer data

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Hadoop stack

```bash theme={null}
monk run hadoop/stack
```

3. Customize configuration (optional)

Running directly uses the defaults defined in this template's `variables`. To customize:

* Preferred: inherit and override variables as shown below.
* Alternative: fork/clone and edit the `variables` in `stack.yml`, then `monk load MANIFEST` and run.

Once started, access the web interfaces:

* NameNode: `http://localhost:9870`
* ResourceManager: `http://localhost:8088`
* HistoryServer: `http://localhost:8188`

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  image_tag: "3.2.1-hadoop3.2.1-java8"    # Hadoop version/image tag
  cluster_name: "Monk SuperCluster"        # HDFS cluster name
```

Additional configuration through environment variables (defined in hadoop-common):

* HDFS settings: WebHDFS enabled, permissions, replication
* YARN settings: Resource limits, memory, CPU cores
* MapReduce settings: Memory allocation, compression codecs

Data is persisted under `${monk-volume-path}/hadoop-1` on the host:

* `/namenode` - NameNode metadata
* `/datanode` - HDFS data blocks
* `/historyserver` - Job history and logs

## Use by inheritance (recommended for apps)

Inherit the Hadoop stack in your application and declare connections. Example for a data processing application:

```yaml theme={null}
namespace: myapp
hadoop-cluster:
  defines: process-group
  inherits: hadoop/stack
  variables:
    cluster_name:
      value: <- secret("hadoop-cluster-name") default("MyApp Cluster")

data-processor:
  defines: runnable
  containers:
    processor:
      image: myorg/data-processor
      environment:
        - <- `HADOOP_NAMENODE=${hdfs_namenode_host}`
        - <- `YARN_RESOURCEMANAGER=${yarn_rm_host}`
  variables:
    hdfs_namenode_host:
      value: <- connection-hostname("namenode") default("localhost")
    yarn_rm_host:
      value: <- connection-hostname("resourcemanager") default("localhost")

app:
  defines: process-group
  runnable-list:
    - myapp/hadoop-cluster
    - myapp/data-processor
```

Then run your app:

```bash theme={null}
monk secrets add -g hadoop-cluster-name="Production Cluster"
monk run myapp/app
```

## Ports and connectivity

The Hadoop stack exposes the following services:

* **NameNode HTTP**: TCP `9870` - Web UI and REST API
* **NameNode RPC**: TCP `9000` - HDFS client connections
* **DataNode**: TCP `9864` - Data transfer and HTTP
* **ResourceManager**: TCP `8088` - YARN web UI and REST API
* **HistoryServer**: TCP `8188` - Job history web UI

From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve service hosts.

## Persistence and configuration

* **NameNode data**: `${monk-volume-path}/hadoop-1/namenode:/hadoop/dfs/name`
* **DataNode data**: `${monk-volume-path}/hadoop-1/datanode:/hadoop/dfs/data`
* **HistoryServer data**: `${monk-volume-path}/hadoop-1/historyserver:/hadoop/yarn/timeline`

All data is persisted to the host volumes and will survive container restarts. Ensure the host volumes are writable by the container user (typically UID 1000).

## Features

* Distributed file system (HDFS) with configurable replication
* MapReduce processing framework
* YARN resource management with configurable memory and CPU limits
* Scalable and fault-tolerant architecture
* Supports batch processing workloads
* WebHDFS REST API enabled by default
* Job history tracking and log aggregation

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Integrate with Apache Spark, Hive, or other Hadoop ecosystem tools
* Use with object storage (MinIO) for backup and archival

## Troubleshooting

* **If NameNode fails to start**: Check that the volume path is writable and that port 9870 and 9000 are not in use.
* **If DataNode cannot connect to NameNode**: Verify network connectivity and that the NameNode is fully started (check logs).
* **If jobs fail with memory errors**: Adjust YARN memory settings in the configuration variables (`yarn_conf_nodemanager_resource_memory_mb`, `mapred_conf_map_memory_mb`, etc.).
* **If changing cluster\_name on existing data**: This may cause NameNode to reject DataNodes. Either reset volumes or keep the same cluster name.

Check logs for detailed error messages:

```bash theme={null}
monk logs -l 500 -f hadoop/stack
```

View logs for individual components:

```bash theme={null}
monk logs -l 500 -f hadoop/hadoop-name-node
monk logs -l 500 -f hadoop/hadoop-data-node
monk logs -l 500 -f hadoop/hadoop-resource-manager-node
```


# HAProxy
Source: https://docs.monk.io/integrations/monk-haproxy

Ready-to-run HAProxy container template you can run directly or inherit to integrate a high-performance load balancer and proxy into your infrastructure.

## Overview

This template provides a production‑ready HAProxy instance as a Monk runnable. You can:

* Run it directly to get a managed HAProxy load balancer with sensible defaults
* Inherit it in your own runnable to seamlessly add load balancing and high availability to your services

HAProxy is a free, very fast and reliable solution offering high availability, load balancing, and proxying for TCP and HTTP-based applications. It is particularly suited for high traffic web sites and can handle 100K+ concurrent connections.

## What this template manages

* HAProxy container (`haproxy` image, configurable tag)
* Network service on port 8080 (configurable)
* Custom HAProxy configuration file
* Backend server routing and health checking
* Connection timeouts and load balancing algorithms

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run HAProxy with defaults

```bash theme={null}
monk run haproxy/haproxy
```

3. Customize backend servers (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. To point HAProxy at your own backend servers:

* Preferred: inherit and override variables with your backend configuration as shown below.
* Alternative: fork/clone and edit the `variables` in `haproxy.yml`, then `monk load MANIFEST` and run.

Once started, HAProxy will listen on port 8080 (or the configured `host-port-number`) and forward traffic to the configured backend servers.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  haproxy-image: "2.7.1"          # container image tag
  haproxy-port-number: 8080       # internal service port
  host-port-number: 8080          # host-exposed port
  backend-hostname: "1.1.1.1"     # backend server address
  backend-port: "443"             # backend server port
```

The HAProxy configuration file (`haproxy.cfg`) is located in the `files/` directory and can be customized before running. The template uses Monk's variable substitution (`{{ v "variable-name" }}`) to inject runtime configuration.

## Use by inheritance (recommended for apps)

Inherit the HAProxy runnable in your application to add load balancing. Example:

```yaml theme={null}
namespace: myapp
loadbalancer:
  defines: runnable
  inherits: haproxy/haproxy
  variables:
    backend-hostname: <- connection-hostname("backend")
    backend-port: "8080"
backend:
  defines: runnable
  containers:
    app:
      image: myorg/app
  services:
    api:
      container: app
      port: 8080
      protocol: tcp
  connections:
    proxy:
      runnable: loadbalancer
      service: haproxy
```

Then run your app group:

```bash theme={null}
monk run myapp/backend
```

For multiple backends or advanced routing, customize the `haproxy.cfg` file to define multiple backend servers, health checks, and routing rules.

## Ports and connectivity

* Service: `haproxy` on TCP port `8080` (configurable via `haproxy-port-number`)
* Host exposure: Port `8080` (configurable via `host-port-number`)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the load balancer.

## Persistence and configuration

* Configuration file: `files/haproxy.cfg` - mounted to `/usr/local/etc/haproxy/haproxy.cfg` in the container
* The configuration supports Monk variable interpolation for dynamic backend configuration
* No persistent data storage required (HAProxy is stateless)

## Features

* Layer 4 (TCP) and Layer 7 (HTTP) load balancing
* SSL/TLS termination
* Health checking with automatic failover
* Sticky sessions (session affinity)
* Advanced routing and URL rewriting
* ACL-based traffic rules
* High performance (100K+ concurrent connections)
* Built-in DNS resolution for dynamic backends

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Use with application servers (`nginx/`, `apache/`) for complete web stack
* Integrate with your application stack as needed

## Troubleshooting

* Check logs:

```bash theme={null}
monk logs -l 500 -f haproxy/haproxy
```

* If backend servers are not responding, verify the `backend-hostname` and `backend-port` values match your backend configuration.
* Ensure backend servers are reachable from the HAProxy container's network.
* For custom configurations, validate your `haproxy.cfg` syntax before running.


# Hazelcast
Source: https://docs.monk.io/integrations/monk-hazelcast

Ready-to-run Hazelcast container templates you can run directly or inherit to integrate an in-memory data grid into your applications.

## Overview

This template provides production‑ready Hazelcast instances as Monk runnables. You can:

* Run it directly to get a managed Hazelcast container with sensible defaults
* Inherit it in your own runnable to seamlessly add distributed in-memory data grid capabilities to your stack
* Deploy as a single instance or multi-node cluster with optional management center

Hazelcast is an open-source distributed in-memory data grid (IMDG) that provides highly scalable and fault-tolerant data processing capabilities. It enables distributed caching, distributed computing, event processing, and real-time stream processing for applications requiring high-performance data operations.

## What this template manages

* Hazelcast container (`hazelcast/hazelcast` image, configurable tag)
* Network service on port 5701 (cluster communication)
* Cluster coordination and automatic member discovery
* Optional Management Center UI on port 8080
* Custom configuration via YAML file mounting

## Available templates

* **hazelcast/hazelcast** - Single Hazelcast instance
* **hazelcast/hazelcast-management** - Management Center dashboard
* **hazelcast/stack** - Single instance + Management Center
* **hazelcast-cluster/hazelcast-1/2/3** - Individual cluster nodes
* **hazelcast-cluster/hazelcast-management** - Cluster management dashboard
* **hazelcast-cluster/stack** - 3-node cluster + Management Center

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Hazelcast

```bash theme={null}
# Single instance only
monk run hazelcast/hazelcast

# Single instance with Management Center
monk run hazelcast/stack

# Or 3-node cluster with Management Center
monk run hazelcast-cluster/stack
```

3. Access Management Center

Once started with a stack, access the Management Center at `http://localhost:8080` to monitor your cluster, view statistics, and manage data structures.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  hazelcast-image-tag: "5.2.1"           # Hazelcast container image tag
  hazelcast-management-image-tag: "latest" # Management Center image tag
  cluster-name: "local-cluster"          # Cluster name (env: HZ_CLUSTERNAME)
```

The Hazelcast configuration is managed through a custom YAML file mounted at `/opt/hazelcast/config/hazelcast-config.yml`. You can modify `files/hazelcast-config.yml` in the template directory to customize cluster settings, networking, data structures, and more.

## Use by inheritance (recommended for apps)

Inherit the Hazelcast runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp

cache:
  defines: runnable
  inherits: hazelcast/hazelcast
  variables:
    cluster-name: myapp-cache-cluster

api:
  defines: runnable
  containers:
    api:
      image: myorg/api
      environment:
        - HAZELCAST_HOST=<- connection-hostname("hazelcast-cache")
        - HAZELCAST_PORT=5701
        - HAZELCAST_CLUSTER=<- $cache-cluster-name
  connections:
    hazelcast-cache:
      runnable: cache
      service: hazelcast
  variables:
    cache-cluster-name:
      value: myapp-cache-cluster
      type: string
```

Then run your app group:

```bash theme={null}
monk run myapp/api
```

Your application will automatically resolve the Hazelcast hostname via the connection and can connect using the Hazelcast client library.

## Using the cluster template

For production environments requiring high availability and better performance, inherit from the cluster template:

```yaml theme={null}
namespace: myapp

cache-cluster:
  defines: process-group
  runnable-list:
    - myapp/cache-node-1
    - myapp/cache-node-2
    - myapp/cache-node-3

cache-node-1:
  defines: runnable
  inherits: hazelcast-cluster/hazelcast-common
  variables:
    cluster-name: myapp-production

cache-node-2:
  defines: runnable
  inherits: hazelcast-cluster/hazelcast-common
  variables:
    cluster-name: myapp-production

cache-node-3:
  defines: runnable
  inherits: hazelcast-cluster/hazelcast-common
  variables:
    cluster-name: myapp-production
```

## Ports and connectivity

* Service: `hazelcast` on TCP port `5701` (cluster member communication)
* Management Center: `hazelcast-management` on TCP port `8080` (HTTP UI)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Hazelcast host.

## Configuration customization

The template includes a pre-configured `hazelcast-config.yml` file that you can customize for your needs. The configuration file supports:

* Network settings and member discovery
* Data structure configurations (maps, queues, topics, etc.)
* Serialization settings
* Security configurations
* Persistence options
* WAN replication settings

To customize, edit `files/hazelcast-config.yml` in the template directory before loading.

## Features

* **Distributed caching**: Store data across multiple nodes with automatic partitioning
* **In-memory computing**: Execute distributed tasks and aggregations
* **Event-driven architecture**: Pub/sub messaging with topics and reliable queues
* **CP and AP modes**: Choose between consistency or availability based on your needs
* **Client-server topology**: Connect multiple applications to the same cluster
* **Automatic data partitioning**: Data is automatically distributed across cluster members
* **Fault tolerance**: Data replication ensures availability during node failures
* **Dynamic scaling**: Add or remove nodes without downtime

## Management Center features

The included Management Center provides:

* Real-time cluster monitoring and health checks
* Performance metrics and statistics
* Data structure browser and management
* Query console for map entries
* Member management and monitoring
* WAN replication monitoring
* Configuration management

## Related templates

* Combine with `redis/` for complementary caching strategies
* Use with `prometheus-grafana/` for advanced metrics and observability
* Integrate with `kafka/` for event streaming pipelines

## Troubleshooting

* If cluster members aren't discovering each other, verify the `cluster-name` is identical across all nodes and check network connectivity.
* For connection issues from client applications, ensure the service port 5701 is accessible and the Hazelcast client library version is compatible with the server version.
* Management Center connection issues: verify the cluster name matches and member hostnames are resolvable.
* Check logs for detailed error messages:

```bash theme={null}
# Single instance
monk logs -l 500 -f hazelcast/hazelcast

# Cluster nodes
monk logs -l 500 -f hazelcast-cluster/hazelcast-1
monk logs -l 500 -f hazelcast-cluster/hazelcast-2
monk logs -l 500 -f hazelcast-cluster/hazelcast-3

# Management Center
monk logs -l 500 -f hazelcast/hazelcast-management
```

* For performance tuning, adjust JVM options via the `JAVA_OPTS` environment variable in the template configuration.


# Apache HTTP Server
Source: https://docs.monk.io/integrations/monk-httpd

Ready-to-run Apache HTTP Server container template you can run directly or inherit to integrate a web server into your infrastructure.

## Overview

This template provides a production‑ready Apache HTTP Server instance as a Monk runnable. You can:

* Run it directly to get a managed Apache web server with sensible defaults
* Inherit it in your own runnable to seamlessly add a web server to your stack

It exposes Apache on configurable HTTP/HTTPS ports, supports custom configuration files and virtual hosts, and can serve static content or act as a reverse proxy for your applications.

## What this template manages

* Apache HTTP Server container (`httpd` image, configurable tag)
* Network service on configurable ports (default HTTP: 80, HTTPS: 443)
* Custom Apache configuration files
* Virtual host configurations
* Volume mounts for static content and logs

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Apache with defaults

```bash theme={null}
monk run apache/apache
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. For production use with custom configurations:

* Preferred: inherit and customize variables as shown below.
* Alternative: fork/clone and edit the `variables` in `apache.yml`, then `monk load MANIFEST` and run.

Once started, access the web server at `http://localhost:8080` (or the configured port).

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  apache-image-tag: "latest"    # Apache container image tag
  http-port: "8080"             # HTTP port to expose
  https-port: "8443"            # HTTPS port to expose (if SSL enabled)
  server-name: "localhost"      # ServerName directive
  server-admin: "admin@localhost" # ServerAdmin email
```

Configuration files can be customized by mounting your own files from the `/files` directory:

* `httpd.conf` - Main Apache configuration
* `vhost.conf` - Virtual host configuration

## Use by inheritance (recommended for apps)

Inherit the Apache runnable in your application to serve static content or proxy to backend services. Example:

```yaml theme={null}
namespace: myapp
webserver:
  defines: runnable
  inherits: apache/apache
  variables:
    http-port: "80"
    server-name: "myapp.example.com"
backend:
  defines: runnable
  containers:
    api:
      image: myorg/api
      ports:
        - 3000:3000
  connections:
    webserver:
      runnable: webserver
      service: apache
```

For reverse proxy setup, customize the virtual host configuration:

```bash theme={null}
monk run myapp/webserver
```

## Ports and connectivity

* Service: `apache` on TCP ports `80` (HTTP) and `443` (HTTPS) by default
* Configurable via `http-port` and `https-port` variables
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the web server host.

## Persistence and configuration

* Config files: Mount custom configurations from the `files/` directory
* Logs: Container logs accessible via `monk logs` command
* Static content: Mount your web root directory as needed in inherited runnables
* You can override any Apache configuration by providing custom `.conf` files

## Features

* Static file serving with high performance
* Reverse proxy capabilities with mod\_proxy
* SSL/TLS support (mod\_ssl)
* URL rewriting (mod\_rewrite)
* Load balancing across multiple backends
* Virtual hosts for multi-site hosting
* Security modules (mod\_security compatible)

## Related templates

* Combine with application backends (Node.js, Python, PHP, Go)
* Use `certbot/` or `traefik/` for automated SSL/TLS certificates
* Integrate with `prometheus-grafana/` for monitoring and metrics
* Pair with `redis/` or `memcached/` for caching

## Troubleshooting

* If configuration changes don't take effect, ensure the container has restarted after updating config files.
* For SSL/TLS issues, verify certificate paths and permissions.
* Check logs for detailed error messages:

```bash theme={null}
monk logs -l 500 -f apache/apache
```

* To test configuration syntax before running:

```bash theme={null}
monk shell apache/apache
apachectl configtest
```


# Jitsu
Source: https://docs.monk.io/integrations/monk-jitsu

Ready-to-run Jitsu container template for open-source customer data platform and event collection.

## Overview

This template provides a production‑ready Jitsu instance as a Monk runnable. You can:

* Run it directly to get a managed customer data platform
* Inherit it in your own infrastructure to collect, transform, and route event data

Jitsu is an open-source data ingestion and event collection engine. It's a self-hosted alternative to Segment, capturing events from websites and apps, transforming them, and sending to data warehouses and analytics tools.

## What this template manages

* Jitsu server for event collection
* Jitsu configurator UI (optional)
* PostgreSQL for configuration storage
* Redis for event queuing
* Web UI and API
* Event transformation engine

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Jitsu stack

```bash theme={null}
monk run jitsu/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in the template files, then `monk load MANIFEST` and run.

Once started:

* Events API: `http://localhost:8001`
* Configurator UI: `http://localhost:7000`

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Jitsu Server
  jitsu-image-tag: "latest"           # Jitsu image tag
  jitsu-port: "8001"                  # events API port
  jitsu-admin-token: "..."            # admin API token
  
  # Configurator
  configurator-port: "7000"           # UI port
  configurator-user: "admin"          # UI username
  configurator-password: "..."        # UI password
  
  # Database
  postgres-password: "..."            # PostgreSQL password
  redis-password: "..."               # Redis password
```

Data is persisted under `${monk-volume-path}/jitsu` on the host.

## Use by inheritance (recommended for analytics)

Inherit Jitsu for event collection and routing. Example:

```yaml theme={null}
namespace: myapp
events:
  defines: runnable
  inherits: jitsu/stack
  variables:
    jitsu-admin-token: <- secret("jitsu-token")
    configurator-password: <- secret("jitsu-ui-password")
webapp:
  defines: runnable
  containers:
    app:
      image: myorg/webapp
      environment:
        - JITSU_WRITE_KEY=<- secret("jitsu-write-key")
        - JITSU_HOST=http://events:8001
  connections:
    analytics:
      runnable: events
      service: jitsu
```

Set secrets and run:

```bash theme={null}
monk secrets add -g jitsu-token="<admin-token>"
monk secrets add -g jitsu-ui-password="STRONG_PASSWORD"
monk secrets add -g jitsu-write-key="<api-key>"
monk run myapp/webapp
```

## Ports and connectivity

* Service: `jitsu` on TCP port `8001` (Events API)
* Service: `configurator` on TCP port `7000` (UI)
* From web/mobile apps, send events to `http://\<host>:8001/api/v1/event`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Jitsu host.

## Persistence and configuration

* Jitsu config: `${monk-volume-path}/jitsu/data:/home/eventnative/data`
* PostgreSQL data: `${monk-volume-path}/postgres:/var/lib/postgresql/data`
* Redis data: `${monk-volume-path}/redis:/data`

## Features

* **Event Collection**: JavaScript SDK, HTTP API, and server-side libraries
* **Transformations**: Transform events with JavaScript functions
* **Destinations**: Send to 20+ destinations (BigQuery, Redshift, Snowflake, etc.)
* **Schema Mapping**: Map events to destination schemas
* **Real-Time**: Stream events to destinations in real-time
* **Batching**: Batch events for efficiency
* **User Identification**: Merge anonymous and identified users
* **Privacy**: GDPR-compliant, self-hosted data

## Event Collection

JavaScript SDK example:

```javascript theme={null}
<script src="https://cdn.jitsu.com/lib.js"></script>
<script>
  jitsu.init({
    key: "your-write-key",
    tracking_host: "http://localhost:8001"
  });
  
  // Track page view
  jitsu.track('page_view', {
    page: window.location.pathname
  });
  
  // Identify user
  jitsu.identify('user-123', {
    email: 'user@example.com',
    name: 'John Doe'
  });
</script>
```

## Destinations

Jitsu supports:

* **Data Warehouses**: BigQuery, Redshift, Snowflake, ClickHouse
* **Databases**: PostgreSQL, MySQL
* **Analytics**: Google Analytics, Amplitude, Mixpanel
* **Marketing**: Facebook Ads, Google Ads
* **Webhooks**: Custom HTTP endpoints

## Use cases

Jitsu excels at:

* Product analytics data collection
* Customer data platform (CDP)
* Event streaming to data warehouses
* Multi-destination event routing
* Privacy-compliant analytics
* Segment replacement for self-hosted needs

## Related templates

* Combine with monitoring tools (e.g., `prometheus-grafana/`) for observability
* See other templates in this repository for complementary services

## Troubleshooting

* Access configurator UI at `http://localhost:7000`
* Test event ingestion:

```bash theme={null}
curl -X POST http://localhost:8001/api/v1/event \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: your-write-key" \
  -d '{
    "event_type": "test",
    "user_id": "test-user"
  }'
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f local/jitsu/server
```

* For missing events, check Redis queue and destination configs
* Verify destination credentials in configurator UI
* Monitor PostgreSQL for configuration issues
* Check transformation functions for errors
* Ensure host volumes are writable by container users


# Apache Kafka
Source: https://docs.monk.io/integrations/monk-kafka

Ready-to-run Apache Kafka container stack you can run directly or inherit to integrate a distributed event streaming platform into your infrastructure.

## Overview

This template provides a production‑ready Apache Kafka stack as a Monk runnable. You can:

* Run it directly to get a managed Kafka cluster with ZooKeeper coordination
* Inherit it in your own runnable to seamlessly add event streaming capabilities to your stack

Apache Kafka is a distributed event streaming platform used by thousands of companies for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications.

## What this template manages

* Kafka broker containers (`confluentinc/cp-kafka` image, configurable tag)
* ZooKeeper ensemble for cluster coordination (`confluentinc/cp-zookeeper` image, configurable tag)
* Network services on ports 9092 (Kafka) and 2181 (ZooKeeper)
* Persistent volumes for Kafka data and ZooKeeper state
* Cluster configuration and topic management

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Kafka stack with defaults

```bash theme={null}
monk run kafka/stack
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. For production use, inherit and configure:

* Preferred: inherit and set variables as shown below
* Alternative: fork/clone and edit the `variables` in `kafka.yaml` and `stack.yaml`, then `monk load MANIFEST` and run

Once started, connect to `localhost:9092` (or the runnable hostname inside Monk networks) to produce and consume messages.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  kafka-image-tag: "7.2.1"                # Kafka container image tag
  zookeeper-image-tag: "7.2.1"            # ZooKeeper container image tag
  kafka-port: 9092                        # Kafka broker port
  zookeeper-port: 2181                    # ZooKeeper client port
  kafka-advertised-listeners: "..."       # KAFKA_ADVERTISED_LISTENERS
  kafka-broker-id: 1                      # KAFKA_BROKER_ID
  kafka-log-retention-hours: 168          # Log retention (hours)
  kafka-num-partitions: 1                 # Default number of partitions
```

Data is persisted under `${monk-volume-path}/kafka` and `${monk-volume-path}/zookeeper` on the host.

## Use by inheritance (recommended for apps)

Inherit the Kafka stack in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
messaging:
  defines: runnable
  inherits: kafka/stack
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    kafka:
      runnable: messaging
      service: kafka
  variables:
    kafka-host:
      value: <- connection-hostname("kafka")
    kafka-port:
      value: <- connection-port("kafka")
```

Then run your app group:

```bash theme={null}
monk run myapp/api
```

## Ports and connectivity

* Service: `kafka` on TCP port `9092` (broker)
* Service: `zookeeper` on TCP port `2181` (coordination)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Kafka broker host
* External clients can connect via the advertised listeners configuration

## Persistence and configuration

* Kafka data path: `${monk-volume-path}/kafka:/var/lib/kafka/data`
* ZooKeeper data path: `${monk-volume-path}/zookeeper:/var/lib/zookeeper`
* Ensure the host volumes are writable by the container user

## Features

* High-throughput messaging (millions of messages per second)
* Fault-tolerant storage with replication
* Stream processing (Kafka Streams)
* Scalable architecture (horizontal scaling)
* Exactly-once semantics
* Multiple consumer groups
* Built-in partitioning for parallelism

## Related templates

* Use with microservices for async communication
* Combine with stream processing frameworks (Kafka Streams, Flink, Spark Streaming)
* Integrate with monitoring (`prometheus-grafana/`) for metrics and alerting
* Pair with schema registry for data governance

## Troubleshooting

* Ensure ZooKeeper is running before Kafka starts. The stack handles this dependency automatically.
* If connection fails, verify `KAFKA_ADVERTISED_LISTENERS` matches your network configuration
* For external access, ensure firewall rules allow traffic on port 9092
* Check logs:

```bash theme={null}
monk logs -l 500 -f kafka/stack
```

* To check ZooKeeper separately:

```bash theme={null}
monk logs -l 500 -f kafka/zookeeper
```


# LibreNMS
Source: https://docs.monk.io/integrations/monk-librenms

Ready-to-run LibreNMS container template you can run directly or inherit to integrate network monitoring and autodiscovery into your infrastructure.

## Overview

This template provides a production‑ready LibreNMS instance as a Monk runnable. You can:

* Run it directly to get a managed network monitoring platform with sensible defaults
* Inherit it in your own infrastructure to seamlessly add network monitoring to your stack

LibreNMS is a fully featured network monitoring system with automatic discovery, alerting, and graphing. It exposes a web UI on port 8000, persists data to host volumes, and supports a wide range of network hardware and operating systems including Cisco, Linux, FreeBSD, Juniper, and many more.

## What this template manages

* LibreNMS application server container
* MySQL/MariaDB for data storage
* RRDCached for performance graphing
* SNMP polling and discovery
* Web UI and RESTful API on port 8000
* Alerting engine with multiple transports
* Persistent volumes for data, graphs, and database

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run LibreNMS stack with defaults

```bash theme={null}
monk run librenms/librenms
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `librenms/librenms.yaml`, then `monk load MANIFEST` and run.

Once started, access LibreNMS at `http://localhost:8000` (or the runnable hostname inside Monk networks).

Default credentials: `admin` / `admin` (change immediately!)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # LibreNMS
  librenms-image-tag: "latest"        # container image tag
  librenms-port: "8000"               # web UI port (env: exposed as service)
  timezone: "UTC"                     # timezone (env: TZ)
  
  # Database
  db-host: "mysql"                    # database host
  db-name: "librenms"                 # database name (env: MYSQL_DATABASE)
  db-user: "librenms"                 # database user (env: MYSQL_USER)
  db-password: "..."                  # database password (env: MYSQL_PASSWORD)
  db-root-password: "..."             # root password (env: MYSQL_ROOT_PASSWORD)
  
  # Monitoring
  poller-threads: "16"                # number of poller threads
  discovery-threads: "1"              # number of discovery threads
```

Data is persisted under `${monk-volume-path}/librenms` and `${monk-volume-path}/mysql` on the host.

## Use by inheritance (recommended for network ops)

Inherit the LibreNMS runnable in your infrastructure and declare connections. Example:

```yaml theme={null}
namespace: netops
monitoring:
  defines: runnable
  inherits: librenms/librenms
  variables:
    db-password:
      value: <- secret("librenms-db-password")
    db-root-password:
      value: <- secret("mysql-root-password")
    timezone:
      value: "America/New_York"
    poller-threads:
      value: "32"
```

Then set the secrets once and run your infrastructure:

```bash theme={null}
monk secrets add -g librenms-db-password="STRONG_PASSWORD"
monk secrets add -g mysql-root-password="STRONG_ROOT_PASSWORD"
monk run netops/monitoring
```

## Ports and connectivity

* Service: `librenms` on TCP port `8000` (Web UI)
* SNMP traps: UDP port `162` (if enabled)
* Syslog: TCP/UDP port `514` (if enabled)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the LibreNMS host.

## Persistence and configuration

* LibreNMS data: `${monk-volume-path}/librenms/data:/data`
* RRD files: `${monk-volume-path}/librenms/rrd:/data/rrd`
* MySQL data: `${monk-volume-path}/mysql:/var/lib/mysql`
* Ensure the host volumes are writable by the container user.

## Features

* **Auto-Discovery**: Automatically discover network devices
* **SNMP Monitoring**: Poll devices via SNMPv1/v2c/v3
* **Graphing**: Historical performance graphs with RRDtool
* **Alerting**: Flexible alerting with multiple transports (email, Slack, webhooks)
* **Device Support**: 1000+ device types
* **API**: RESTful API for automation
* **Distributed Polling**: Scale with multiple pollers
* **Customizable Dashboards**: Create custom views
* **Billing**: Track bandwidth usage

## Adding Devices

Add devices via:

1. **Web UI**: Devices → Add Device
2. **Auto-discovery**: Settings → Discovery → Discover new devices
3. **API**: Use REST API to add devices programmatically

Example device configuration:

* **Hostname/IP**: 192.168.1.1
* **SNMP Version**: v2c or v3
* **Community**: public (v2c) or credentials (v3)

## Alerting

Configure alerts:

* Set thresholds for metrics (CPU, memory, bandwidth)
* Create alert rules with conditions
* Configure alert transports (email, Slack, PagerDuty, etc.)
* Set maintenance windows

## Device Support

LibreNMS supports:

* **Networking**: Cisco, Juniper, Arista, HP, MikroTik, Ubiquiti
* **Servers**: Linux, Windows, FreeBSD, ESXi
* **Storage**: NetApp, EMC, Synology
* **Appliances**: Firewalls, load balancers, UPS
* **IoT**: Environmental sensors, PDUs

## API Usage

Example API call:

```bash theme={null}
# List devices
curl -H "X-Auth-Token: YOUR_API_TOKEN" \
  http://localhost:8000/api/v0/devices

# Add device
curl -X POST -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"192.168.1.1","community":"public"}' \
  http://localhost:8000/api/v0/devices
```

## Use cases

LibreNMS excels at:

* Network infrastructure monitoring
* Server and service monitoring
* SNMP device monitoring
* Bandwidth accounting
* Environmental monitoring (temperature, humidity)
* Alerting and notifications
* Capacity planning

## Related templates

* Integrate with databases and services for comprehensive monitoring
* Use with alerting systems (PagerDuty, Slack, email)
* Combine with log aggregation tools (`elk/`, `fluentbit/`)
* High‑availability setup: see the `librenms-ha/` template in this repository for distributed polling.

## Troubleshooting

* Access LibreNMS UI at `http://localhost:8000`
* Check poller status: System → Pollers
* Validate installation: `./validate.php` in container
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f librenms/librenms
```

**Common issues:**

* **Device discovery issues:**
  * Verify SNMP connectivity: `snmpwalk -v2c -c public \<device-ip>`
  * Check firewall rules for UDP 161
  * Verify SNMP community string
* **Slow polling:** Increase `poller-threads` variable
* **Graph issues:** Check RRD file permissions in data volume
* **Database performance:** Monitor MySQL performance for large deployments
* **Authentication fails after password change:** Either reset the data volume or update credentials inside the DB to match


# Mastodon
Source: https://docs.monk.io/integrations/monk-mastodon

Ready-to-run Mastodon container template you can run directly or inherit to integrate a decentralized social network into your infrastructure.

## Overview

This template provides a production‑ready Mastodon instance as a Monk runnable. You can:

* Run it directly to host your own decentralized social network instance
* Inherit it in your own runnable to seamlessly add Mastodon to your community infrastructure

Mastodon is free, open-source, decentralized social network software. It's part of the Fediverse, allowing users on different servers to interact. Think of it as self-hosted Twitter/X with no central authority.

## What this template manages

* Mastodon web application (port 3000)
* Mastodon streaming server (port 4000)
* Sidekiq background workers
* PostgreSQL database for data persistence
* Redis for caching and job queues
* Persistent volumes for media and database
* Optional Elasticsearch for full-text search

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Mastodon stack

```bash theme={null}
monk run mastodon/stack
```

3. Create admin user

```bash theme={null}
docker exec -it mastodon-web \
  bin/tootctl accounts create admin \
  --email admin@example.com \
  --confirmed --role Owner
```

4. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `mastodon/stack.yaml`, then `monk load MANIFEST` and run.

Once started, access Mastodon at `http://localhost:3000` (or the runnable hostname inside Monk networks).

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  mastodon-image-tag: "latest"              # container image tag
  web-port: "3000"                          # web UI port
  streaming-port: "4000"                    # streaming API port
  local-domain: "mastodon.example.com"      # your domain (required for federation)
  
  # Secrets (generate with rake secret)
  secret-key-base: "..."                    # Rails secret (env: SECRET_KEY_BASE)
  otp-secret: "..."                         # OTP secret (env: OTP_SECRET)
  vapid-private-key: "..."                  # VAPID private key
  vapid-public-key: "..."                   # VAPID public key
  
  # Database
  postgres-password: "..."                  # PostgreSQL password
  db-name: "mastodon"                       # database name
  db-user: "mastodon"                       # database user
  
  # Redis
  redis-password: "..."                     # Redis password
  
  # Email (required for production)
  smtp-server: "smtp.example.com"           # SMTP server
  smtp-login: "user@example.com"            # SMTP username
  smtp-password: "..."                      # SMTP password
  smtp-from: "notifications@example.com"    # sender address
```

Data is persisted under `${monk-volume-path}/mastodon`, `${monk-volume-path}/postgres`, and `${monk-volume-path}/redis` on the host.

## Use by inheritance (recommended for communities)

Inherit the Mastodon runnable in your community infrastructure. Example:

```yaml theme={null}
namespace: mycommunity
social:
  defines: runnable
  inherits: mastodon/stack
  variables:
    local-domain: "social.mycommunity.org"
    secret-key-base: <- secret("mastodon-secret-key")
    otp-secret: <- secret("mastodon-otp-secret")
    vapid-private-key: <- secret("mastodon-vapid-private")
    vapid-public-key: <- secret("mastodon-vapid-public")
    postgres-password: <- secret("postgres-password")
    redis-password: <- secret("redis-password")
    smtp-server: <- secret("smtp-server")
    smtp-login: <- secret("smtp-login")
    smtp-password: <- secret("smtp-password")
```

Generate required secrets:

```bash theme={null}
# Generate Rails secrets
docker run --rm -it tootsuite/mastodon:latest bundle exec rake secret

# Generate VAPID keys
docker run --rm -it tootsuite/mastodon:latest bundle exec rake mastodon:webpush:generate_vapid_key
```

Then set the secrets once and run your community stack:

```bash theme={null}
monk secrets add -g mastodon-secret-key="<generated-secret>"
monk secrets add -g mastodon-otp-secret="<generated-otp>"
monk secrets add -g mastodon-vapid-private="<generated-vapid-private>"
monk secrets add -g mastodon-vapid-public="<generated-vapid-public>"
monk secrets add -g postgres-password="STRONG_PASSWORD"
monk secrets add -g redis-password="STRONG_PASSWORD"
monk secrets add -g smtp-server="smtp.example.com"
monk secrets add -g smtp-login="notifications@example.com"
monk secrets add -g smtp-password="SMTP_PASSWORD"
monk run mycommunity/social
```

## Ports and connectivity

* Service: `web` on TCP port `3000` (Web UI)
* Service: `streaming` on TCP port `4000` (Streaming API)
* For federation, requires public domain with HTTPS configured
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve services.

## Persistence and configuration

* Media files: `${monk-volume-path}/mastodon/public:/mastodon/public`
* PostgreSQL data: `${monk-volume-path}/postgres:/var/lib/postgresql/data`
* Redis data: `${monk-volume-path}/redis:/data`
* Ensure the host volumes are writable by the container user.

## Production requirements

For production deployment:

* **Domain**: Registered domain with DNS pointing to your server
* **HTTPS**: SSL/TLS certificate (Let's Encrypt recommended)
* **Email**: SMTP server for notifications and confirmations
* **Object Storage**: S3-compatible storage for media (recommended for scalability)
* **CDN**: Content delivery network for media (optional but recommended)
* **Backups**: Regular database and media backups

## Related templates

* High‑availability setup: see the `mastodon-ha/` template in this repository for a clustered deployment.
* Combine with monitoring tools (`prometheus-grafana/`) for observability.

## Troubleshooting

* If you changed secrets but the container has existing data, you may need to regenerate them or update the database.
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f mastodon/web
monk logs -l 500 -f mastodon/sidekiq
monk logs -l 500 -f mastodon/streaming
```

* For federation issues:
  * Verify domain is publicly accessible with HTTPS
  * Test ActivityPub endpoint: `https://yourdomain/.well-known/webfinger`
* For email issues, verify SMTP configuration in admin panel
* For slow performance, scale Sidekiq workers or optimize PostgreSQL
* Run database migrations if needed:

```bash theme={null}
docker exec -it mastodon-web bin/rails db:migrate
```

* Common administration tasks:

```bash theme={null}
# Create user
docker exec -it mastodon-web \
  bin/tootctl accounts create username \
  --email user@example.com --confirmed

# Make admin
docker exec -it mastodon-web \
  bin/tootctl accounts modify username --role Admin

# Clean old media
docker exec -it mastodon-web \
  bin/tootctl media remove --days=7
```


# Memcached
Source: https://docs.monk.io/integrations/monk-memcached

Ready-to-run Memcached container template you can run directly or inherit to integrate a high-performance distributed memory caching system into your stack.

## Overview

This template provides a production‑ready Memcached instance as a Monk runnable. You can:

* Run it directly to get a managed Memcached container with sensible defaults
* Inherit it in your own runnable to seamlessly add a distributed memory cache to your stack

It exposes Memcached on port 11211, supports authentication, and allows fine-tuning of cache size, connections, threads, and item size limits.

## What this template manages

* Memcached container (`bitnamilegacy/memcached` image, configurable tag)
* Network service on port 11211
* Memory allocation and cache management
* Optional authentication with username and password
* Performance tuning via threads, connections, and cache size

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Memcached with defaults

```bash theme={null}
monk run memcached/memcached
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `memcached/memcached.yaml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:11211` (or the runnable hostname inside Monk networks) using the configured credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  memcached-image: "latest"            # container image tag
  memcached_cache_size: 128            # cache size in MB (env: MEMCACHED_CACHE_SIZE)
  memcached_max_connections: 2000      # max simultaneous connections (env: MEMCACHED_MAX_CONNECTIONS)
  memcached_threads: 4                 # number of worker threads (env: MEMCACHED_THREADS)
  memcached_max_item_size: 8388608     # max item size in bytes (env: MEMCACHED_MAX_ITEM_SIZE)
  memcached_username: "monk"           # authentication username (env: MEMCACHED_USERNAME)
  memcached_password: "monk"           # authentication password (env: MEMCACHED_PASSWORD)
  memcached_extra_flags: ""            # additional flags for memcached (env: MEMCACHED_EXTRA_FLAGS)
```

## Use by inheritance (recommended for apps)

Inherit the Memcached runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
cache:
  defines: runnable
  inherits: memcached/memcached
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    cache:
      runnable: cache
      service: memcached
  variables:
    cache-host:
      value: <- connection-hostname("cache")
    cache-user:
      value: <- secret("memcached-user")
    cache-password:
      value: <- secret("memcached-password")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g memcached-user="cacheuser"
monk secrets add -g memcached-password="STRONG_CACHE_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `memcached` on TCP port `11211`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the cache host.

## Features

* Simple key-value storage
* Fast in-memory caching
* Distributed architecture
* Multiple client libraries
* LRU eviction policy
* Configurable cache size and performance tuning
* Optional authentication support

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Integrate with your application stack as needed

## Troubleshooting

* If you changed `memcached_password` after initial setup, ensure your client applications use the updated credentials.
* Adjust `memcached_cache_size` if you're experiencing evictions or have available memory.
* Increase `memcached_max_connections` if you're seeing connection refused errors under high load.
* Check logs:

```bash theme={null}
monk logs -l 500 -f memcached/memcached
```


# MongoDB
Source: https://docs.monk.io/integrations/monk-mongodb

Ready-to-run MongoDB container template you can run directly or inherit to integrate a document-oriented NoSQL database into your stack.

## Overview

This template provides a production‑ready MongoDB instance as a Monk runnable. You can:

* Run it directly to get a managed MongoDB container with sensible defaults
* Inherit it in your own runnable to seamlessly add a document database to your stack

It exposes MongoDB on port 27017, persists data to a host volume, and can optionally create an application user and database on first start.

## What this template manages

* MongoDB container (`mongo` image, configurable tag)
* Network service on port 27017
* Persistent volumes for data storage
* Optional initialization of database, user, and passwords

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run MongoDB with defaults

```bash theme={null}
monk run mongodb/mongodb
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `mongodb/mongodb.yaml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:27017` (or the runnable hostname inside Monk networks) using the configured credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  mongodb-image-tag: "latest"         # container image tag
  mongodb-root-username: "admin"      # admin username (env: MONGO_INITDB_ROOT_USERNAME)
  mongodb-root-password: "..."        # admin password (env: MONGO_INITDB_ROOT_PASSWORD)
  mongodb-database: "mydb"            # optional app DB to create (env: MONGO_INITDB_DATABASE)
  mongodb-username: "myuser"          # optional app user
  mongodb-password: "..."             # optional app user password
```

Data is persisted under `${monk-volume-path}/mongodb` on the host.

## Use by inheritance (recommended for apps)

Inherit the MongoDB runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
db:
  defines: runnable
  inherits: mongodb/mongodb
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: mongodb
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-user:
      value: <- secret("mongodb-username")
    database-password:
      value: <- secret("mongodb-password")
    database-name:
      value: <- secret("mongodb-database")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g mongodb-username="appuser"
monk secrets add -g mongodb-password="STRONG_USER_PASSWORD"
monk secrets add -g mongodb-database="appdb"
monk secrets add -g mongodb-root-password="STRONG_ROOT_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `mongodb` on TCP port `27017`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence

* Data path: `${monk-volume-path}/mongodb:/data/db`
* MongoDB stores all databases and collections in this directory
* Ensure the host volume is writable by the container user

## Features

* Document-oriented storage
* Rich query language
* Indexing and aggregation
* Replication and sharding
* ACID transactions
* Change streams

## Related templates

* For MongoDB replica set cluster, see `mongodb-cluster/` templates
* For sharded deployments, check MongoDB sharding templates
* Combine with `mongo-express/` for web-based administration

## Troubleshooting

* If you changed `mongodb-root-password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside the DB to match.
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f mongodb/mongodb
```


# Eclipse Mosquitto
Source: https://docs.monk.io/integrations/monk-mosquitto

Ready-to-run Eclipse Mosquitto container template you can run directly or inherit to integrate an MQTT message broker into your IoT infrastructure.

## Overview

This template provides a production‑ready Eclipse Mosquitto instance as a Monk runnable. You can:

* Run it directly to get a managed MQTT broker with sensible defaults
* Inherit it in your own runnable to seamlessly add MQTT messaging to your IoT infrastructure

It exposes MQTT on port 1883, WebSocket on port 9001, persists data to a host volume, and supports full MQTT v3.1, v3.1.1, and v5.0 protocols. Eclipse Mosquitto is an open-source message broker that is lightweight and suitable for use on all devices from low-power single board computers to full servers.

## What this template manages

* Mosquitto MQTT broker container (`eclipse-mosquitto` image, configurable tag)
* Network service on port 1883 (MQTT)
* Network service on port 9001 (WebSocket)
* Persistent volumes for data storage
* Auto-generated configuration file with customizable settings

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Mosquitto with defaults

```bash theme={null}
monk run mosquitto/mosquitto-broker
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. To customize settings, you can:

* Preferred: inherit and override variables as shown below.
* Alternative: fork/clone and edit the `variables` in `mosquitto.yml`, then `monk load MANIFEST` and run.

Once started, connect MQTT clients to `localhost:1883` (or the runnable hostname inside Monk networks) and WebSocket clients to `localhost:9001`.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  mqtt-port: 1883                    # MQTT TCP port
  websocket-port: 9001               # WebSocket port for MQTT over WS
  allow-anonymous: true              # Allow connections without authentication
  max-connections: -1                # Maximum concurrent connections (-1 = unlimited)
  persistence: true                  # Enable message persistence
  retain-available: true             # Allow retained messages
  log-level: "information"           # Logging level
  websocket-enabled: true            # Enable WebSocket listener
```

Data is persisted under `${monk-volume-path}/mosquitto/data` on the host. The configuration file is auto-generated from the template at `/mosquitto/config/mosquitto.conf`.

## Use by inheritance (recommended for apps)

Inherit the Mosquitto runnable in your IoT application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
mqtt:
  defines: runnable
  inherits: mosquitto/mosquitto-broker
  variables:
    allow-anonymous:
      value: false
    max-connections:
      value: 1000
sensor-api:
  defines: runnable
  containers:
    api:
      image: myorg/iot-api
  connections:
    message-broker:
      runnable: mqtt
      service: mqtt
  variables:
    mqtt-host:
      value: <- connection-hostname("message-broker")
    mqtt-port:
      value: <- connection-port("message-broker")
```

Then run your app group:

```bash theme={null}
monk run myapp/sensor-api
```

## Ports and connectivity

* Service: `mqtt` on TCP port `1883` (default)
* Service: `websocket` on TCP port `9001` (default)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the broker host.

## Persistence and configuration

* Data path: `${monk-volume-path}/mosquitto/data:/mosquitto/data`
* Configuration is auto-generated from template variables and mounted at `/mosquitto/config/mosquitto.conf`
* Supports message persistence, retained messages, and persistent sessions

## Features

* MQTT v3.1, v3.1.1, and v5.0 support
* QoS levels 0, 1, and 2
* Retained messages
* Last Will and Testament
* WebSocket support for browser-based clients
* Message persistence
* Configurable connection limits
* Flexible logging

## Related templates

* Use with microservices for async communication
* Combine with stream processing (Kafka Streams, Flink)
* Integrate with monitoring (`prometheus-grafana/`)
* Pair with Node-RED for IoT workflow automation

## Troubleshooting

* If you changed `allow-anonymous` to `false`, ensure you have configured authentication (password file or auth plugin) in a custom configuration.
* Ensure the host volumes are writable by the container user.
* For production use, consider setting `allow-anonymous: false` and configuring proper authentication.
* Check logs:

```bash theme={null}
monk logs -l 500 -f mosquitto/mosquitto-broker
```


# Microsoft SQL Server
Source: https://docs.monk.io/integrations/monk-mssql

Ready-to-run Microsoft SQL Server container template you can run directly or inherit to integrate a relational database into your stack.

## Overview

This template provides a production‑ready Microsoft SQL Server instance as a Monk runnable. You can:

* Run it directly to get a managed SQL Server container with sensible defaults
* Inherit it in your own runnable to seamlessly add a relational database to your stack

It exposes SQL Server on port 1433, persists data to a host volume, and includes SA (system administrator) authentication.

## What this template manages

* SQL Server container (`mcr.microsoft.com/mssql/server` image, configurable tag)
* Network service on port 1433
* Persistent volumes for data storage
* SA authentication and EULA acceptance

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run SQL Server with defaults

```bash theme={null}
monk run mssql/db
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `mssql.yml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:1433` (or the runnable hostname inside Monk networks) using the configured SA credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  monk_mssql_accept_eula: "Y"          # EULA acceptance (required, env: ACCEPT_EULA)
  monk_mssql_sa_password: "P@ssw0rd"   # SA password (env: SA_PASSWORD)
```

**Note:** The default SA password is `P@ssw0rd`. Always change this in production environments.

Data is persisted under `${monk-volume-path}/mssql` on the host, mapped to `/var/opt/mssql` in the container.

## Use by inheritance (recommended for apps)

Inherit the SQL Server runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
db:
  defines: runnable
  inherits: mssql/db
  variables:
    monk_mssql_sa_password:
      value: <- secret("mssql-sa-password")
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: mssql-svc
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-user:
      value: "sa"
    database-password:
      value: <- secret("mssql-sa-password")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g mssql-sa-password="STRONG_SA_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `mssql-svc` on TCP port `1433`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence and configuration

* Data path: `${monk-volume-path}/mssql:/var/opt/mssql`
* This volume contains all SQL Server data files, logs, and system databases.

## Features

* Full T-SQL support
* ACID transactions
* Stored procedures and triggers
* Full-text search
* Replication and high availability
* Integration with Azure
* Business intelligence capabilities

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools for observability
* Integrate with your application stack as needed

## Troubleshooting

* If you changed `monk_mssql_sa_password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside the DB to match.
* Ensure the host volumes are writable by the container user.
* The SA password must meet Microsoft's complexity requirements (uppercase, lowercase, numbers, and special characters).
* Check logs:

```bash theme={null}
monk logs -l 500 -f mssql/db
```


# Nginx
Source: https://docs.monk.io/integrations/monk-nginx

Ready-to-run Nginx container template you can run directly or inherit to integrate a high-performance web server and reverse proxy into your infrastructure.

## Overview

This template provides a production‑ready Nginx instance as a Monk runnable. You can:

* Run it directly to get a managed Nginx web server with sensible defaults
* Inherit it in your own runnable to serve static content, reverse proxy, or load balance traffic

Nginx is a high-performance HTTP server and reverse proxy, as well as an IMAP/POP3 proxy server. It's known for its high performance, stability, rich feature set, simple configuration, and low resource consumption.

## What this template manages

* Nginx container (`nginx` image, configurable tag)
* Network services on ports 80 (HTTP) and 443 (HTTPS)
* Custom nginx.conf configuration
* Static content serving
* Reverse proxy capabilities

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Nginx with defaults

```bash theme={null}
monk run nginx/nginx
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Configuration added with custom files will not affect this runnable unless you inherit it and override those files.

* Preferred: inherit and customize variables or files as shown below.
* Alternative: fork/clone and edit the `variables` in `nginx/nginx.yaml`, then `monk load MANIFEST` and run.

Once started, access Nginx at `http://localhost:80`.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  nginx-image-tag: "latest"           # container image tag  
  http-port: "80"                     # HTTP port (env: HTTP_PORT)
  https-port: "443"                   # HTTPS port (env: HTTPS_PORT)
  worker-processes: "auto"            # worker processes count
  worker-connections: "1024"          # connections per worker
```

Custom nginx.conf can be provided via the `files` section in the template. Static content and configuration files are typically mounted from the host or defined inline.

## Use by inheritance (recommended for apps)

Inherit the Nginx runnable in your application to create a reverse proxy or serve static content. Example:

```yaml theme={null}
namespace: myapp
web:
  defines: runnable
  inherits: nginx/nginx
  files:
    nginx-conf:
      container: nginx
      path: /etc/nginx/nginx.conf
      contents: |
        events {
          worker_connections 1024;
        }
        http {
          upstream backend {
            server api:8080;
          }
          server {
            listen 80;
            location / {
              proxy_pass http://backend;
              proxy_set_header Host $host;
            }
          }
        }
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    proxy:
      runnable: web
      service: nginx
```

Then run your application group:

```bash theme={null}
monk run myapp/api
```

## Ports and connectivity

* Service: `nginx` on TCP port `80` (HTTP) and `443` (HTTPS)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Nginx host.

## Persistence and configuration

* Configuration files can be mounted via the `files` section in your runnable definition.
* Static content can be served by mounting host directories or defining inline content.
* SSL/TLS certificates should be mounted from the host or provided via secrets management.
* Logs are available via `monk logs` command or can be persisted to host volumes if needed.

## Features

* High-performance static file serving
* Reverse proxy with caching
* Load balancing (round-robin, least connections, IP hash)
* SSL/TLS termination
* HTTP/2 support
* WebSocket proxying
* URL rewriting and redirects
* Access control and rate limiting

## Use cases

Nginx excels at:

* Serving static websites and assets
* Reverse proxy for microservices
* Load balancing across application servers
* SSL/TLS termination
* API gateway
* Content caching

## Related templates

* Combine with application backends (Node.js, Python, PHP)
* Use `certbot/` or `traefik/` for SSL/TLS certificates
* Integrate with `prometheus-grafana/` for monitoring

## Troubleshooting

* Test nginx configuration syntax:

```bash theme={null}
monk do nginx/nginx/test-config
```

* Verify Nginx is responding:

```bash theme={null}
curl http://localhost:80
```

* For SSL/HTTPS setup, ensure certificates are properly mounted and paths are correct.
* If configuration changes don't take effect, ensure you've reloaded or restarted the container.
* Check logs:

```bash theme={null}
monk logs -l 500 -f nginx/nginx
```


# OrientDB
Source: https://docs.monk.io/integrations/monk-orientdb

Ready-to-run OrientDB container template you can run directly or inherit to integrate a multi-model NoSQL database into your stack.

## Overview

This template provides a production‑ready OrientDB instance as a Monk runnable. You can:

* Run it directly to get a managed OrientDB container with sensible defaults
* Inherit it in your own runnable to seamlessly add a multi-model database to your stack

OrientDB is a multi-model NoSQL database that combines the power of graphs with documents, key-values, and objects. It supports ACID transactions, SQL queries, and provides high performance for both transactional and analytical workloads.

## What this template manages

* OrientDB server
* Network service on ports 2424 (binary), 2480 (HTTP)
* Persistent volumes for data storage
* Multi-model support (graph, document, key-value, object)
* SQL-like query language

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run OrientDB with defaults

```bash theme={null}
monk run orientdb/db
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `orientdb.yml`, then `monk load MANIFEST` and run.

Once started, access OrientDB Studio at `http://localhost:2480` or connect via binary protocol on port 2424.

Default credentials: `root` / `password` (change for production!)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  image: "3.2.17-tp3"            # container image tag
  db_password: "..."             # root password (env: ORIENTDB_ROOT_PASSWORD)
  db_studio_port: "2480"         # HTTP/Studio port
  db_port: "2424"                # binary protocol port
```

Data is persisted under `${monk-volume-path}/orientdb` on the host.

## Use by inheritance (recommended for apps)

Inherit the OrientDB runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
graphdb:
  defines: runnable
  inherits: orientdb/db
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: graphdb
      service: db
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-port:
      value: "2424"
    database-password:
      value: <- secret("orientdb-root-password")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g orientdb-root-password="STRONG_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `db` on TCP port `2424` (binary protocol)
* Service: `db_studio` on TCP port `2480` (HTTP/Studio)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the DB host.

## Persistence and configuration

* Data path: `${monk-volume-path}/orientdb:/orientdb/databases`
* OrientDB stores all databases, graphs, and documents in this directory

## Features

* Multi-model database (graph, document, key-value, object)
* SQL support with graph extensions
* ACID transactions
* Distributed architecture
* Schema-less and schema-full modes
* High performance for both reads and writes
* Built-in full-text search

## Use cases

OrientDB excels at:

* Social networks and recommendation engines
* Knowledge graphs
* Fraud detection
* Master data management
* Content management
* Network and IT operations

## Related templates

* Combine with application servers for multi-model data needs
* Use with `prometheus-grafana/` for performance monitoring
* Integrate with ETL tools for data warehousing

## Troubleshooting

* If you changed `db_password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside OrientDB to match.
* Access OrientDB Studio web interface at `http://localhost:2480`
* Ensure the host volumes are writable by the container user
* Check logs:

```bash theme={null}
monk logs -l 500 -f orientdb/db
```

* For production, always change the default root password


# pgAdmin
Source: https://docs.monk.io/integrations/monk-pgadmin

Ready-to-run pgAdmin container template for web-based PostgreSQL administration and management.

## Overview

This template provides a production‑ready pgAdmin instance as a Monk runnable. You can:

* Run it directly to get a managed web-based PostgreSQL administration tool
* Inherit it in your own database infrastructure to provide a GUI for PostgreSQL management

pgAdmin is the most popular and feature-rich open-source administration and development platform for PostgreSQL. It provides a web interface for managing databases, running queries, creating backups, and monitoring server performance.

## What this template manages

* pgAdmin 4 web application
* SQLite or PostgreSQL for pgAdmin metadata
* Web UI for database administration
* Query tool and data editor
* Server monitoring and statistics
* Web UI on port 5050

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run pgAdmin with defaults

```bash theme={null}
monk run pgadmin/pgadmin
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `pgadmin/pgadmin.yml`, then `monk load MANIFEST` and run.

Once started, access pgAdmin at `http://localhost:5050` (or the runnable hostname inside Monk networks) using the configured credentials.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  pgadmin-image-tag: "latest"                                 # container image tag
  pgadmin-port: "5050"                                        # web UI port (env: PGADMIN_LISTEN_PORT)
  pgadmin-email: "admin@example.com"                          # admin email/username (env: PGADMIN_DEFAULT_EMAIL)
  pgadmin-password: "..."                                     # admin password (env: PGADMIN_DEFAULT_PASSWORD)
  pgadmin-config-enhanced-cookie-protection: "True"           # optional security config
  pgadmin-config-login-banner: "Welcome to pgAdmin"           # optional login banner
  pgadmin-config-console-log-level: "10"                      # optional log level
```

Data is persisted under `${monk-volume-path}/pgadmin:/var/lib/pgadmin` on the host.

## Use by inheritance (recommended for database management)

Inherit the pgAdmin runnable in your database infrastructure and declare a connection. Example:

```yaml theme={null}
namespace: myapp
db-admin:
  defines: runnable
  inherits: pgadmin/pgadmin
  variables:
    pgadmin-email: "dba@mycompany.com"
    pgadmin-password: <- secret("pgadmin-password")
db:
  defines: runnable
  inherits: postgres/postgres
  variables:
    postgres-password: <- secret("postgres-password")
  connections:
    admin:
      runnable: db-admin
      service: pgadmin
```

Then set the secrets once and run your database group:

```bash theme={null}
monk secrets add -g pgadmin-password="STRONG_PASSWORD"
monk secrets add -g postgres-password="STRONG_DB_PASSWORD"
monk run myapp/db-admin
```

## Ports and connectivity

* Service: `pgadmin` on TCP port `5050`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the pgAdmin host.
* From pgAdmin, connect to PostgreSQL servers on their respective ports (typically `5432`)

## Persistence and configuration

* Data path: `${monk-volume-path}/pgadmin:/var/lib/pgadmin`
* Server definitions, query history, and settings are persisted in the data path

## Features

* **Web-Based**: Access from any browser, no desktop client needed
* **Query Tool**: Interactive SQL editor with syntax highlighting
* **Data Editor**: View and edit table data
* **Schema Browser**: Visual database structure exploration
* **Backup & Restore**: GUI for pg\_dump and pg\_restore
* **Server Monitoring**: Real-time server statistics
* **Multi-Server**: Manage multiple PostgreSQL servers
* **User Management**: Role-based access control
* **Import/Export**: CSV, JSON, and other formats

## Adding PostgreSQL Servers

After login:

1. Right-click "Servers" → Register → Server
2. **General tab**: Name your connection
3. **Connection tab**:
   * Host: `postgres` (or server hostname)
   * Port: `5432`
   * Maintenance database: `postgres`
   * Username: `postgres`
   * Password: (save password for convenience)
4. Click "Save"

## Query Tool

Features:

* Syntax highlighting for SQL
* Query history
* Auto-completion
* Explain and analyze plans
* Export results to CSV, JSON
* Saved queries

## Use cases

pgAdmin excels at:

* PostgreSQL database administration
* SQL query development and testing
* Database schema design
* Data exploration and analysis
* Backup and restore operations
* Server monitoring and tuning
* Team database management

## Related templates

* See other templates in this repository for complementary services
* Combine with monitoring tools (`prometheus-grafana/`) for observability
* Integrate with your application stack as needed

## Troubleshooting

* If you changed `pgadmin-password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside pgAdmin to match.
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f pgadmin/pgadmin
```

* For connection issues to PostgreSQL:
  * Verify PostgreSQL is running and accessible
  * Check hostname/IP and port
  * Verify PostgreSQL allows connections from pgAdmin container
  * Check `pg_hba.conf` for access rules
* For performance issues, ensure adequate resources for pgAdmin container
* Store server passwords securely in pgAdmin's password vault


# Prometheus + Grafana
Source: https://docs.monk.io/integrations/monk-prometheus-grafana

Ready-to-run Prometheus and Grafana stack template for comprehensive monitoring, metrics collection, and visualization.

## Overview

This template provides a production‑ready Prometheus + Grafana monitoring stack as Monk runnables. You can:

* Run it directly to get a complete monitoring solution with metrics collection and visualization
* Inherit it in your own infrastructure to add observability to your applications

Prometheus is a time-series database and monitoring system that collects metrics via HTTP pulls. Grafana is a visualization platform that creates dashboards from Prometheus and other data sources. Together, they provide a powerful, open-source monitoring stack.

## What this template manages

* Prometheus server for metrics collection
* Grafana for visualization and dashboards
* AlertManager for alerting (optional)
* Service discovery and scrape configuration
* Persistent storage for metrics and dashboards
* Pre-configured data sources

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run the monitoring stack

```bash theme={null}
monk run prometheus-grafana/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in the template, then `monk load MANIFEST` and run.

Once started:

* Prometheus UI: `http://localhost:9090`
* Grafana UI: `http://localhost:3000` (default: admin/admin)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Prometheus
  prometheus-image-tag: "latest"      # Prometheus image tag
  prometheus-port: "9090"             # Prometheus UI/API port
  scrape-interval: "15s"              # metrics scrape interval
  retention-time: "15d"               # metrics retention period
  
  # Grafana
  grafana-image-tag: "latest"         # Grafana image tag
  grafana-port: "3000"                # Grafana UI port
  grafana-admin-user: "admin"         # admin username
  grafana-admin-password: "..."       # admin password
```

Data is persisted under `${monk-volume-path}/prometheus` and `${monk-volume-path}/grafana` on the host.

## Use by inheritance (recommended for monitoring)

Inherit the stack to monitor your applications. Example:

```yaml theme={null}
namespace: myapp
monitoring:
  defines: runnable
  inherits: prometheus-grafana/stack
  variables:
    grafana-admin-password: <- secret("grafana-password")
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
      labels:
        prometheus.scrape: "true"
        prometheus.port: "8080"
        prometheus.path: "/metrics"
  connections:
    monitor:
      runnable: monitoring
      service: prometheus
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g grafana-password="STRONG_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `prometheus` on TCP port `9090`
* Service: `grafana` on TCP port `3000`
* Service: `alertmanager` on TCP port `9093` (if enabled)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve service hosts.
* From monitored services, Prometheus scrapes metrics via HTTP

## Persistence and configuration

* Prometheus data: `${monk-volume-path}/prometheus:/prometheus`
* Grafana data: `${monk-volume-path}/grafana:/var/lib/grafana`
* Prometheus config: `${monk-volume-path}/prometheus/config`
* You can customize Prometheus scrape configs and Grafana dashboards via the mounted volumes.

## Features

### Prometheus

* Time-series metrics database
* Powerful PromQL query language
* Service discovery (Kubernetes, Docker, Consul, etc.)
* Pull-based metrics collection
* Alerting with AlertManager
* High availability and federation

### Grafana

* Beautiful, customizable dashboards
* Multiple data source support
* Templating and variables
* Alerting and notifications
* User management and RBAC
* Dashboard sharing and versioning

## Metrics Exposition

Expose metrics from your applications:

```python theme={null}
# Python example with prometheus_client
from prometheus_client import Counter, start_http_server

requests = Counter('http_requests_total', 'Total HTTP requests')

@app.route('/metrics')
def metrics():
    return generate_latest()
```

Configure Prometheus to scrape:

```yaml theme={null}
scrape_configs:
  - job_name: 'myapp'
    static_configs:
      - targets: ['api:8080']
```

## Alerting

Configure alerts in Prometheus:

```yaml theme={null}
groups:
  - name: example
    rules:
      - alert: HighErrorRate
        expr: rate(http_errors_total[5m]) > 0.05
        for: 10m
        annotations:
          summary: "High error rate detected"
```

## Use cases

This stack excels at:

* Application performance monitoring
* Infrastructure monitoring
* Real-time alerting
* Capacity planning
* SLA monitoring
* DevOps observability

## Related templates

* Use `alertmanager/` for advanced alerting and notification routing
* Integrate with `node-exporter/` for system metrics collection
* Combine with `loki/` for log aggregation and correlation

## Troubleshooting

* Access Prometheus targets at `http://localhost:9090/targets` to verify scrape status
* Check Grafana data sources in Settings → Data Sources
* Verify metrics are being scraped:

```bash theme={null}
# Query Prometheus API
curl 'http://localhost:9090/api/v1/query?query=up'
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f prometheus-grafana/prometheus
monk logs -l 500 -f prometheus-grafana/grafana
```

* For missing metrics, verify:
  * Service is exposing metrics on the configured port
  * Prometheus can reach the target (check firewalls)
  * Scrape configuration is correct
* For Grafana dashboard issues, check data source configuration and time ranges


# Radicle
Source: https://docs.monk.io/integrations/monk-radicle

Ready-to-run Radicle container template for peer-to-peer code collaboration and decentralized Git hosting.

## Overview

This template provides a production‑ready Radicle instance as a Monk runnable. You can:

* Run it directly to get a managed peer-to-peer code collaboration platform
* Inherit it in your own infrastructure to add decentralized Git hosting

Radicle is a sovereign peer-to-peer network for code collaboration. It enables developers to collaborate on code without relying on trusted intermediaries. Built on Git, Radicle provides secure peer-to-peer collaboration, resilient to censorship and centralized control.

## What this template manages

* Radicle node (seed node)
* Radicle HTTP API
* Git repository hosting
* Peer-to-peer networking
* Identity and authentication
* Web UI on port 8080 (httpd)

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Radicle seed node

```bash theme={null}
monk run radicle/seed
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. To customize node configuration:

* Preferred: inherit and override variables as shown below.
* Alternative: fork/clone and edit the `variables` in `radicle.yaml`, then `monk load MANIFEST` and run.

Once started:

* HTTP API: `http://localhost:8080`
* Connect with Radicle CLI (`rad`)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  radicle-image-tag: "latest"              # Radicle image tag
  httpd-port: "8080"                       # HTTP API port
  p2p-port: "8776"                         # P2P networking port
  node-alias: "my-seed"                    # node alias/name
  external-address: "seed.example.com:8776" # external P2P address
```

Data is persisted under `${monk-volume-path}/radicle` on the host.

## Use by inheritance (recommended for teams)

Inherit the Radicle seed node in your infrastructure for decentralized Git hosting. Example:

```yaml theme={null}
namespace: myteam

seed:
  defines: runnable
  inherits: radicle/seed
  variables:
    node-alias: "team-seed"
    external-address: "git.myteam.com:8776"
    httpd-port: "8080"
    p2p-port: "8776"
```

Run the seed node:

```bash theme={null}
monk run myteam/seed
```

## Ports and connectivity

* Service: `radicle-httpd` on TCP port `8080` (HTTP API)
* Service: `radicle-node` on TCP port `8776` (P2P network)
* Git over HTTP: accessible via HTTP API
* From Radicle CLI, connect to seed node using node ID and address

## Persistence and data

* Data path: `${monk-volume-path}/radicle:/app/.radicle`
* Git repositories: stored in Radicle storage
* Node identity and configuration persisted in data path

## Features

* **Peer-to-Peer**: No central server, censorship-resistant
* **Git Native**: Built on Git, compatible with existing workflows
* **Cryptographic Identity**: Key-based authentication
* **Offline-First**: Work locally, sync when connected
* **Social Coding**: Issues, patches, and discussions
* **Seed Nodes**: Public nodes for discovery and availability
* **Secure**: End-to-end encrypted, signed commits

## Radicle CLI Usage

Install Radicle CLI and connect to your seed:

```bash theme={null}
# Initialize a repository
rad init

# Push to Radicle network
rad push

# Clone a repository
rad clone rad://...

# Configure seed node
rad config set seed.default <seed-node-id>@<seed-address>:8776
```

## Seed Node

Seed nodes provide:

* **Discovery**: Help peers find each other
* **Availability**: Always-online repository hosting
* **Replication**: Backup copies of repositories
* **HTTP Gateway**: Web access to repositories

## Identities

Radicle uses cryptographic identities:

* **Device ID**: Unique identifier for each device
* **Project ID**: Unique identifier for each project
* **Peer ID**: Unique identifier for each peer

## Use cases

Radicle excels at:

* Decentralized open-source development
* Censorship-resistant code collaboration
* Private team collaboration without GitHub
* Air-gapped environments
* Sovereign infrastructure
* Web3 and crypto projects

## Integration with Git

Radicle integrates seamlessly:

```bash theme={null}
# Add Radicle as remote
git remote add rad rad://...

# Push to Radicle
git push rad main

# Pull from Radicle
git pull rad main
```

## Related templates

* Combine with monitoring tools for observability
* Integrate with CI/CD pipelines for automated workflows

## Troubleshooting

* Access HTTP API at `http://localhost:8080` to verify the seed node is running.
* Check node status:

```bash theme={null}
rad node status
```

* View node ID and peer list:

```bash theme={null}
rad self
rad node peers
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f radicle/seed
```

* For connectivity issues:
  * Verify P2P port 8776 is accessible from external networks
  * Check firewall rules allow incoming connections on port 8776
  * Ensure `external-address` matches your actual public address
* For synchronization issues, check seed node connectivity and peer list
* Monitor disk space for repository storage under `${monk-volume-path}/radicle`
* Ensure system time is synchronized (important for P2P networking)


# Redis
Source: https://docs.monk.io/integrations/monk-redis

Ready-to-run Redis container template you can run directly or inherit to integrate an in-memory data store into your stack.

## Overview

This template provides a production‑ready Redis instance as a Monk runnable. You can:

* Run it directly to get a managed Redis container with sensible defaults
* Inherit it in your own runnable to seamlessly add an in-memory data store to your stack

It exposes Redis on port 6379, persists data to a host volume, and supports optional password authentication.

Redis is an open-source, in-memory data structure store used as a database, cache, message broker, and streaming engine. It supports various data structures such as strings, hashes, lists, sets, sorted sets, and more.

## What this template manages

* Redis container (`redis` image, configurable tag)
* Network service on port 6379
* Persistent volumes for data storage
* Optional password authentication
* Multiple data structures support

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Redis with defaults

```bash theme={null}
monk run redis/redis
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `redis/redis.yml`, then `monk load MANIFEST` and run.

Once started, connect to `localhost:6379` (or the runnable hostname inside Monk networks) using any Redis client.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  redis-image-tag: "latest"           # container image tag
  redis-password: "..."               # optional password for authentication
  redis-port: "6379"                  # Redis port
  redis-maxmemory: "256mb"            # maximum memory limit
  redis-persistence: "yes"            # enable/disable RDB snapshots
```

Data is persisted under `${monk-volume-path}/redis` on the host.

## Use by inheritance (recommended for apps)

Inherit the Redis runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
cache:
  defines: runnable
  inherits: redis/redis
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    cache:
      runnable: cache
      service: redis-svc
  variables:
    redis-host:
      value: <- connection-hostname("cache")
    redis-port:
      value: "6379"
    redis-password:
      value: <- secret("redis-password")
```

Then set the secrets once and run your app:

```bash theme={null}
monk secrets add -g redis-password="STRONG_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `redis-svc` on TCP port `6379`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Redis host.

## Persistence and configuration

* Data path: `${monk-volume-path}/redis:/data`
* Redis can persist data using RDB snapshots or AOF (Append Only File)
* Configure persistence options in the template variables

## Features

* In-memory key-value store
* Multiple data structures (strings, hashes, lists, sets, sorted sets)
* Pub/Sub messaging
* Transactions
* Persistence options (RDB, AOF)
* Lua scripting
* Replication and clustering

## Related templates

* High‑availability setup: see the `redis-cluster-sentinel/` template in this repository for a Redis Sentinel configuration.
* Distributed setup: check `redis-cluster-sentinel-haproxy/` for Redis Cluster with HAProxy load balancing.
* Combine with databases for caching layer (MySQL, PostgreSQL, MongoDB).

## Troubleshooting

* If you changed `redis-password` but the container has existing data, authentication may fail. Either reset the data volume or update the password configuration.
* Ensure the host volumes are writable by the container user if persistence is enabled.
* Test connection with redis-cli:

```bash theme={null}
redis-cli -h localhost -p 6379 ping
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f redis/redis
```

* If memory issues occur, adjust `redis-maxmemory` variable.


# SonarQube
Source: https://docs.monk.io/integrations/monk-sonarqube

Ready-to-run SonarQube container template you can run directly or inherit to integrate continuous code quality inspection into your stack.

## Overview

This template provides a production‑ready SonarQube instance as a Monk runnable. You can:

* Run it directly to get a managed code quality and security platform
* Inherit it in your own runnable to seamlessly add continuous code inspection to your CI/CD pipeline

SonarQube is a leading platform for continuous inspection of code quality and security. It performs automatic reviews with static analysis to detect bugs, code smells, and security vulnerabilities across 25+ programming languages.

## What this template manages

* SonarQube server container (`sonarqube` image, configurable tag)
* PostgreSQL database for persistent storage
* Network service on port 9000 (Web UI and API)
* Analysis engine and quality gates
* Persistent volumes for data, extensions, and logs

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run SonarQube with database

```bash theme={null}
monk run sonarqube/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in the YAML files, then `monk load MANIFEST` and run.

Once started, access SonarQube at `http://localhost:9000`. Default credentials: `admin` / `admin` (change immediately!)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  sonarqube-image-tag: "latest"       # SonarQube container image tag
  sonarqube-port: "9000"              # web UI and API port
  sonarqube-admin-password: "..."     # admin password
  postgres-password: "..."            # PostgreSQL password
  postgres-user: "sonar"              # database user
  postgres-db: "sonarqube"            # database name
  sonar-web-javaOpts: "-Xmx512m"      # web server JVM options
  sonar-ce-javaOpts: "-Xmx512m"       # compute engine JVM options
```

Data is persisted under `${monk-volume-path}/sonarqube` and `${monk-volume-path}/postgres` on the host.

## Use by inheritance (recommended for CI/CD)

Inherit the SonarQube runnable in your CI/CD pipeline and declare a connection. Example:

```yaml theme={null}
namespace: myapp
quality-gate:
  defines: runnable
  inherits: sonarqube/stack
  variables:
    sonarqube-admin-password:
      value: <- secret("sonar-password")
    postgres-password:
      value: <- secret("postgres-password")
ci:
  defines: runnable
  containers:
    ci:
      image: myorg/ci-runner
      environment:
        - SONAR_HOST_URL=http://quality-gate:9000
        - SONAR_TOKEN=<- secret("sonar-token")
  connections:
    sonar:
      runnable: quality-gate
      service: sonarqube
```

Then set the secrets once and run your CI pipeline:

```bash theme={null}
monk secrets add -g sonar-password="STRONG_PASSWORD"
monk secrets add -g postgres-password="STRONG_DB_PASSWORD"
monk secrets add -g sonar-token="<your-sonar-token>"
monk run myapp/ci
```

## Ports and connectivity

* Service: `sonarqube` on TCP port `9000`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the SonarQube host.

## Persistence and configuration

* SonarQube data: `${monk-volume-path}/sonarqube/data:/opt/sonarqube/data`
* Extensions: `${monk-volume-path}/sonarqube/extensions:/opt/sonarqube/extensions`
* Logs: `${monk-volume-path}/sonarqube/logs:/opt/sonarqube/logs`
* PostgreSQL data: `${monk-volume-path}/postgres:/var/lib/postgresql/data`

## Features

* **Code Quality Analysis**: Detect bugs, code smells, and technical debt
* **Security Scanning**: Find vulnerabilities and security hotspots
* **25+ Languages**: Java, JavaScript, TypeScript, Python, C#, Go, PHP, etc.
* **Quality Gates**: Define pass/fail criteria for builds
* **Pull Request Decoration**: Automatic PR comments in GitHub, GitLab, etc.
* **Custom Rules**: Create organization-specific quality standards
* **Historical Trends**: Track code quality over time
* **Integration**: Jenkins, GitLab CI, GitHub Actions, Azure DevOps

## CI/CD Integration

Example with Maven:

```bash theme={null}
mvn clean verify sonar:sonar \
  -Dsonar.projectKey=myproject \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.login=<token>
```

Example with Docker:

```bash theme={null}
docker run --rm \
  -e SONAR_HOST_URL=http://sonarqube:9000 \
  -e SONAR_LOGIN=<token> \
  -v $(pwd):/usr/src \
  sonarsource/sonar-scanner-cli
```

## Supported Languages

* Java, JavaScript, TypeScript
* Python, PHP, C#, VB.NET
* C, C++, Objective-C
* Go, Kotlin, Ruby, Scala
* HTML, CSS, XML
* And many more...

## Use cases

SonarQube excels at:

* Continuous code quality monitoring
* Security vulnerability detection
* Technical debt management
* Code review automation
* Compliance and standards enforcement
* Developer education on best practices

## Related templates

* Integrate with source control (GitLab, GitHub) for automated code analysis
* Use with artifact repositories (`nexus/`, `artifactory/`) for build integration
* Combine with CI/CD platforms (Jenkins, GitLab CI) for continuous inspection

## Troubleshooting

* Access SonarQube UI at `http://localhost:9000` (default credentials: `admin` / `admin`)
* Generate API token: Administration → Security → Users → Tokens
* Check system health: Administration → System
* Verify database connection in logs
* Check logs:

```bash theme={null}
monk logs -l 500 -f sonarqube/sonarqube
```

* If analysis is slow, increase JVM heap size in `sonar-web-javaOpts` and `sonar-ce-javaOpts`
* Ensure PostgreSQL is running and accessible before starting SonarQube
* For large projects, allocate more resources (4GB+ RAM recommended)
* Check Elasticsearch storage requirements for large codebases


# Apache Superset
Source: https://docs.monk.io/integrations/monk-superset

Ready-to-run Apache Superset container template for modern data exploration and business intelligence visualization.

## Overview

This template provides a production‑ready Apache Superset instance as a Monk runnable. You can:

* Run it directly to get a managed business intelligence and data visualization platform
* Inherit it in your own data infrastructure to add BI and analytics capabilities

Apache Superset is a modern, enterprise-ready business intelligence web application. It's fast, lightweight, intuitive, and loaded with options that make it easy for users to explore and visualize their data, from simple line charts to highly detailed geospatial charts.

## What this template manages

* Superset web server and workers
* PostgreSQL or MySQL metadata database
* Redis for caching and async queries
* Web UI on port 8088
* SQL Lab for data exploration
* Dashboard and chart management

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Superset stack

```bash theme={null}
monk run superset/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in the template files, then `monk load MANIFEST` and run.

Once started, access Superset at `http://localhost:8088` using the configured credentials (default: `admin` / `admin`).

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Superset
  superset-image-tag: "latest"        # container image tag
  superset-port: "8088"               # web UI port (env: SUPERSET_PORT)
  superset-admin-username: "admin"    # admin username (env: ADMIN_USERNAME)
  superset-admin-password: "..."      # admin password (env: ADMIN_PASSWORD)
  superset-secret-key: "..."          # Flask secret key (env: SECRET_KEY)
  
  # Database
  postgres-password: "..."            # PostgreSQL password (env: POSTGRES_PASSWORD)
  postgres-user: "superset"           # database user (env: POSTGRES_USER)
  postgres-db: "superset"             # database name (env: POSTGRES_DB)
  
  # Redis
  redis-password: "..."               # Redis password, optional (env: REDIS_PASSWORD)
```

Data is persisted under `${monk-volume-path}/superset`, `${monk-volume-path}/postgres`, and `${monk-volume-path}/redis` on the host.

## Use by inheritance (recommended for data platforms)

Inherit the Superset stack in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
analytics:
  defines: runnable
  inherits: superset/stack
  variables:
    superset-admin-password: <- secret("superset-password")
    superset-secret-key: <- secret("superset-secret")
    postgres-password: <- secret("postgres-password")
datawarehouse:
  defines: runnable
  containers:
    dw:
      image: myorg/datawarehouse
  connections:
    bi:
      runnable: analytics
      service: superset
  variables:
    superset-url:
      value: <- connection-hostname("bi")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g superset-password="STRONG_PASSWORD"
monk secrets add -g superset-secret="<random-secret-key>"
monk secrets add -g postgres-password="STRONG_DB_PASSWORD"
monk run myapp/analytics
```

## Ports and connectivity

* Service: `superset` on TCP port `8088`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Superset host.
* From data sources, Superset connects via database drivers (configure in UI)

## Persistence and configuration

* Superset home path: `${monk-volume-path}/superset:/app/superset_home`
* PostgreSQL data path: `${monk-volume-path}/postgres:/var/lib/postgresql/data`
* Redis data path: `${monk-volume-path}/redis:/data`
* You can customize Superset configuration by mounting additional config files into the superset\_home directory.

## Features

* **Rich Visualizations**: 40+ chart types (line, bar, pie, maps, etc.)
* **SQL Lab**: Interactive SQL editor with query history
* **No-Code Viz Builder**: Create charts without writing code
* **Dashboards**: Combine multiple charts into interactive dashboards
* **Database Support**: PostgreSQL, MySQL, SQLite, Redshift, BigQuery, Snowflake, etc.
* **Caching**: Redis-based caching for fast query results
* **Security**: Row-level security, LDAP/OAuth integration
* **Async Queries**: Long-running queries with Celery
* **Alerting**: Schedule reports and alerts

## Connecting Data Sources

Superset supports many databases:

* **SQL**: PostgreSQL, MySQL, SQLite, Oracle
* **Big Data**: Presto, Hive, Spark SQL, Druid
* **Cloud**: BigQuery, Redshift, Snowflake, Athena
* **Time-Series**: InfluxDB, Prometheus
* And 30+ more via SQLAlchemy drivers

Add database in UI: Data → Databases → + Database

## SQL Lab

Interactive SQL editor with:

* Auto-completion
* Query history
* Multiple tabs
* Query results export
* Visualization from queries

## Use cases

Superset excels at:

* Business intelligence dashboards
* Data exploration and discovery
* Ad-hoc data analysis
* Scheduled reporting
* Self-service analytics
* Data democratization

## Production Considerations

For production deployments:

* Use external PostgreSQL or MySQL for metadata
* Configure Redis for caching and Celery
* Enable SSL/TLS
* Set up authentication (OAuth, LDAP)
* Configure row-level security
* Set up monitoring and logging

## Related templates

* Use `pgadmin/` for web-based database administration
* Combine with `grafana/` for time-series visualization
* Integrate with `telegraf/` for metrics collection

## Troubleshooting

* Access Superset UI at `http://localhost:8088`
* If you changed `superset-admin-password` but the container has existing data, you may need to recreate the admin user inside Superset.
* Ensure the host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f superset/superset
```

* For connection issues to data sources, verify database drivers are installed in the Superset container
* For slow queries, check Redis cache configuration
* For large datasets, configure async query execution with Celery workers
* Monitor PostgreSQL for metadata database performance
* Initialize database manually (if needed):

```bash theme={null}
superset db upgrade
superset init
```


# TensorFlow
Source: https://docs.monk.io/integrations/monk-tensorflow

Ready-to-run TensorFlow container template you can run directly or inherit to integrate machine learning and deep learning capabilities.

## Overview

This template provides a production‑ready TensorFlow instance as a Monk runnable. You can:

* Run it directly to get a managed TensorFlow environment for ML/DL development
* Inherit it in your own ML applications to add training and inference capabilities

TensorFlow is an end-to-end open-source platform for machine learning. It has a comprehensive ecosystem of tools, libraries, and community resources that lets researchers push the state-of-the-art in ML and developers easily build and deploy ML-powered applications.

## What this template manages

* TensorFlow container (`tensorflow/tensorflow` image)
* Jupyter notebook server (optional)
* GPU acceleration support (with tensorflow-gpu)
* Python environment with TensorFlow libraries
* Model serving with TensorFlow Serving

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run TensorFlow with defaults

```bash theme={null}
monk run tensorflow/tensorflow
```

3. Access Jupyter notebook (if enabled)

Navigate to `http://localhost:8888` and use the token from logs.

4. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `tensorflow/tensorflow.yml`, then `monk load MANIFEST` and run.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  tensorflow-image-tag: "latest"      # container image tag
  jupyter-enabled: "true"             # enable Jupyter notebook
  jupyter-port: "8888"                # Jupyter port
  gpu-support: "false"                # use tensorflow-gpu image
  python-version: "3.9"               # Python version
```

Data is persisted under `${monk-volume-path}/tensorflow` on the host. Custom configuration can be mounted to the container as needed.

## Use by inheritance (recommended for ML apps)

Inherit the TensorFlow runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: myapp
ml-trainer:
  defines: runnable
  inherits: tensorflow/tensorflow
  variables:
    gpu-support: "true"
    tensorflow-image-tag: "latest-gpu"
  files:
    training-script:
      container: tensorflow
      path: /workspace/train.py
      contents: |
        import tensorflow as tf
        # Your training code here
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    ml-service:
      runnable: ml-trainer
      service: tensorflow
  variables:
    ml-host:
      value: <- connection-hostname("ml-service")
```

Then run your app group:

```bash theme={null}
monk run myapp/api
```

## Ports and connectivity

* Service: `tensorflow` (configurable ports)
* Jupyter: TCP port `8888` (if enabled)
* TensorFlow Serving: TCP port `8501` (REST API)
* gRPC: TCP port `8500` (for serving)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the TensorFlow host.

## Persistence and configuration

* Notebooks path: `${monk-volume-path}/tensorflow/notebooks`
* Models path: `${monk-volume-path}/tensorflow/models`
* Data path: `${monk-volume-path}/tensorflow/data`
* You can mount additional configuration files and datasets to the container as needed.

## Features

* Complete ML/DL framework
* Keras high-level API
* Eager execution for intuitive development
* GPU and TPU acceleration
* TensorFlow Serving for production inference
* TensorFlow Lite for mobile and embedded
* TensorFlow\.js for browser-based ML
* Distributed training support
* Model optimization and quantization

## Use cases

TensorFlow excels at:

* Image classification and object detection
* Natural language processing
* Time series forecasting
* Recommendation systems
* Reinforcement learning
* Generative models (GANs, VAEs)
* Any deep learning task

## GPU Support

For GPU acceleration:

```yaml theme={null}
variables:
  tensorflow-image-tag: "latest-gpu"
  gpu-support: "true"
```

Requirements:

* NVIDIA GPU with CUDA support
* NVIDIA drivers installed
* Docker GPU runtime configured

## Model Serving

TensorFlow Serving provides production-ready model inference:

* REST and gRPC APIs
* Model versioning
* Batching for efficiency
* Hot-reloading of models

## Related templates

* See other ML/AI templates in this repository for complementary services.
* Combine with monitoring tools for observability of training jobs and model serving.

## Troubleshooting

* For GPU support, verify CUDA compatibility with TensorFlow version and ensure NVIDIA drivers are properly installed.
* Ensure sufficient RAM/VRAM for your models. Monitor GPU memory usage to avoid OOM errors.
* Ensure host volumes are writable by the container user.
* Check logs:

```bash theme={null}
monk logs -l 500 -f tensorflow/tensorflow
```

* Check Jupyter logs for token:

```bash theme={null}
monk logs -l 100 tensorflow/tensorflow | grep token
```

* Verify TensorFlow installation inside the container:

```python theme={null}
import tensorflow as tf
print(tf.__version__)
print(tf.config.list_physical_devices('GPU'))
```


# TIG Stack (Telegraf + InfluxDB + Grafana)
Source: https://docs.monk.io/integrations/monk-tig

Ready-to-run TIG stack template for time-series metrics collection, storage, and visualization.

## Overview

This template provides a production‑ready TIG (Telegraf, InfluxDB, Grafana) monitoring stack as Monk runnables. You can:

* Run it directly to get a complete time-series monitoring solution
* Inherit it in your own infrastructure to collect, store, and visualize metrics

The TIG stack combines Telegraf (metrics collection agent), InfluxDB (time-series database), and Grafana (visualization) to provide a powerful, purpose-built monitoring platform for time-series data.

## What this template manages

* Telegraf agents for metrics collection
* InfluxDB for time-series data storage
* Grafana for visualization and dashboards
* Pre-configured data sources and inputs
* Persistent storage for time-series data

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run the TIG stack

```bash theme={null}
monk run tig/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in the manifest, then `monk load MANIFEST` and run.

Once started:

* InfluxDB UI: `http://localhost:8086`
* Grafana UI: `http://localhost:3000` (default: admin/admin)

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # InfluxDB
  influxdb-image-tag: "latest"        # InfluxDB image tag
  influxdb-port: "8086"               # InfluxDB HTTP API port
  influxdb-org: "myorg"               # organization name
  influxdb-bucket: "metrics"          # default bucket
  influxdb-admin-token: "..."         # admin token (env: DOCKER_INFLUXDB_INIT_ADMIN_TOKEN)
  influxdb-retention: "30d"           # data retention period
  
  # Telegraf
  telegraf-image-tag: "latest"        # Telegraf image tag
  telegraf-interval: "10s"            # collection interval
  
  # Grafana
  grafana-image-tag: "latest"         # Grafana image tag
  grafana-port: "3000"                # Grafana UI port
  grafana-admin-password: "..."       # admin password (env: GF_SECURITY_ADMIN_PASSWORD)
```

Data is persisted under `${monk-volume-path}/influxdb`, `${monk-volume-path}/grafana`, and `${monk-volume-path}/telegraf` on the host.

## Use by inheritance (recommended for monitoring)

Inherit the TIG stack to monitor your infrastructure and declare connections. Example:

```yaml theme={null}
namespace: myapp
monitoring:
  defines: runnable
  inherits: tig/stack
  variables:
    influxdb-admin-token:
      value: <- secret("influxdb-token")
    grafana-admin-password:
      value: <- secret("grafana-password")
api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    metrics:
      runnable: monitoring
      service: influxdb
  variables:
    influxdb-host:
      value: <- connection-hostname("metrics")
    influxdb-token:
      value: <- secret("influxdb-token")
```

Then set the secrets once and run your app group:

```bash theme={null}
monk secrets add -g influxdb-token="STRONG_TOKEN"
monk secrets add -g grafana-password="STRONG_PASSWORD"
monk run myapp/api
```

## Ports and connectivity

* Service: `influxdb` on TCP port `8086` (HTTP API)
* Service: `grafana` on TCP port `3000`
* Telegraf communicates with InfluxDB internally
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve service hosts.

## Persistence and configuration

* InfluxDB data path: `${monk-volume-path}/influxdb:/var/lib/influxdb2`
* Grafana data path: `${monk-volume-path}/grafana:/var/lib/grafana`
* Telegraf config path: `${monk-volume-path}/telegraf:/etc/telegraf`
* You can customize Telegraf inputs and outputs by modifying the configuration files in the Telegraf config path.

## Features

### Telegraf

* 200+ input plugins (system, Docker, databases, APIs)
* Multiple output plugins
* Data transformation and aggregation
* Lightweight and efficient

### InfluxDB

* Purpose-built time-series database
* High write and query performance
* Flux query language
* Automatic data downsampling
* Retention policies
* Clustering and HA support

### Grafana

* Beautiful dashboards
* InfluxDB native integration
* Alerting and notifications
* Templating and variables

## Telegraf Configuration

Example Telegraf inputs:

```toml theme={null}
[[inputs.cpu]]
  percpu = true
  totalcpu = true

[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs"]

[[inputs.mem]]

[[inputs.docker]]
  endpoint = "unix:///var/run/docker.sock"

[[outputs.influxdb_v2]]
  urls = ["http://influxdb:8086"]
  token = "$INFLUXDB_TOKEN"
  organization = "myorg"
  bucket = "metrics"
```

## InfluxDB Query Example

Using Flux:

```flux theme={null}
from(bucket: "metrics")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> aggregateWindow(every: 1m, fn: mean)
```

## Use cases

The TIG stack excels at:

* Infrastructure monitoring (CPU, memory, disk, network)
* Container and Kubernetes monitoring
* IoT sensor data collection
* Application performance monitoring
* Custom metrics collection
* Real-time dashboards

## Related templates

* Use `prometheus/` for alternative metrics collection and storage
* Combine with `loki/` for log aggregation alongside metrics
* Integrate with `alertmanager/` for advanced alerting capabilities

## Troubleshooting

* If you changed `influxdb-admin-token` or `grafana-admin-password` but the containers have existing data, authentication may fail. Either reset the data volumes or update the credentials inside the respective services to match.
* Ensure the host volumes are writable by the container users.
* Access InfluxDB UI at `http://localhost:8086`
* Check Telegraf is collecting:

```bash theme={null}
monk logs -l 100 tig/telegraf
```

* Query InfluxDB:

```bash theme={null}
influx query 'from(bucket:"metrics") |> range(start:-5m) |> limit(n:10)'
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f tig/influxdb
monk logs -l 500 -f tig/telegraf
monk logs -l 500 -f tig/grafana
```

* For missing metrics:
  * Verify Telegraf configuration
  * Check InfluxDB token permissions
  * Ensure network connectivity between components
* For Grafana issues, verify InfluxDB data source configuration with correct org, bucket, and token


# Trino (formerly Presto SQL)
Source: https://docs.monk.io/integrations/monk-trino

Ready-to-run Trino container template for fast distributed SQL query engine for big data analytics.

## Overview

This template provides a production‑ready Trino instance as a Monk runnable. You can:

* Run it directly to get a managed distributed SQL query engine
* Inherit it in your own data infrastructure to query data across multiple sources

Trino (formerly Presto SQL) is a fast distributed SQL query engine for big data analytics. It allows you to query data where it lives, whether in Hadoop, S3, Cassandra, MySQL, or dozens of other data sources, using standard SQL.

## What this template manages

* Trino coordinator
* Trino workers (optional, for distributed setup)
* Web UI and query interface
* Catalog configuration for data sources
* Query execution engine
* Web UI on port 8080

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Trino with defaults

```bash theme={null}
monk run trino/trino
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `trino/trino.yml`, then `monk load MANIFEST` and run.

Once started:

* Web UI: `http://localhost:8080`
* Connect with Trino CLI or JDBC: `jdbc:trino://localhost:8080/catalog/schema`

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Trino
  trino-image-tag: "latest"              # container image tag
  trino-port: "8080"                     # HTTP port (env: TRINO_PORT)
  discovery-uri: "http://localhost:8080" # discovery service URI
  
  # Performance
  query-max-memory: "5GB"                # max memory per query
  query-max-memory-per-node: "1GB"       # max memory per node
  heap-size: "2G"                        # JVM heap size
```

Data and configuration are persisted under `${monk-volume-path}/trino` on the host. Custom catalog configurations are mounted from `${monk-volume-path}/trino/catalog:/etc/trino/catalog`.

## Use by inheritance (recommended for data platforms)

Inherit the Trino runnable in your data platform and declare connections. Example:

```yaml theme={null}
namespace: mydata
query-engine:
  defines: runnable
  inherits: trino/trino
  files:
    postgres-catalog:
      container: trino
      path: /etc/trino/catalog/postgresql.properties
      contents: |
        connector.name=postgresql
        connection-url=jdbc:postgresql://postgres:5432/mydb
        connection-user=<- secret("db-user")
        connection-password=<- secret("db-password")
api:
  defines: runnable
  containers:
    api:
      image: myorg/analytics-api
  connections:
    analytics:
      runnable: query-engine
      service: trino
  variables:
    trino-host:
      value: <- connection-hostname("analytics")
    trino-port:
      value: "8080"
```

Then set the secrets once and run your data platform group:

```bash theme={null}
monk secrets add -g db-user="trino"
monk secrets add -g db-password="STRONG_PASSWORD"
monk run mydata/api
```

## Ports and connectivity

* Service: `trino` on TCP port `8080`
* Web UI: `http://localhost:8080`
* JDBC: `jdbc:trino://localhost:8080/catalog/schema`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Trino host.

## Persistence and configuration

* Data path: `${monk-volume-path}/trino:/etc/trino`
* Catalog path: `${monk-volume-path}/trino/catalog:/etc/trino/catalog`
* You can drop additional catalog `.properties` files into the catalog path to configure data source connectors.

## Features

* **Fast Queries**: In-memory distributed execution
* **Federated Queries**: Query across multiple data sources in one SQL
* **Standard SQL**: ANSI SQL support
* **40+ Connectors**: PostgreSQL, MySQL, S3, Hive, Kafka, Elasticsearch, etc.
* **Scalable**: Add workers for horizontal scaling
* **No ETL**: Query data where it lives, no data movement
* **BI Tool Integration**: Tableau, Looker, Metabase, Superset

## Supported Connectors

* **RDBMS**: PostgreSQL, MySQL, Oracle, SQL Server
* **NoSQL**: MongoDB, Cassandra, Redis
* **Cloud Storage**: S3, GCS, Azure Blob
* **Data Lakes**: Hive, Iceberg, Delta Lake
* **Streaming**: Kafka, Kinesis
* **Search**: Elasticsearch, OpenSearch
* **And 40+ more...**

## Catalog Configuration

Example PostgreSQL catalog (`/etc/trino/catalog/postgresql.properties`):

```properties theme={null}
connector.name=postgresql
connection-url=jdbc:postgresql://postgres:5432/mydb
connection-user=trino
connection-password=secret
```

Example S3/Hive catalog:

```properties theme={null}
connector.name=hive
hive.metastore.uri=thrift://hive-metastore:9083
hive.s3.aws-access-key=AKIAIOSFODNN7EXAMPLE
hive.s3.aws-secret-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```

## Querying with Trino

Connect with Trino CLI:

```bash theme={null}
trino --server localhost:8080 --catalog postgresql --schema public
```

Run queries:

```sql theme={null}
-- Query PostgreSQL
SELECT * FROM postgresql.public.users LIMIT 10;

-- Federated query across multiple sources
SELECT u.name, o.total
FROM postgresql.public.users u
JOIN mysql.sales.orders o ON u.id = o.user_id
WHERE o.created_at > DATE '2024-01-01';

-- Query S3 data lake
SELECT * FROM hive.default.events
WHERE dt = '2024-01-01';
```

## Use cases

Trino excels at:

* Data lake analytics
* Federated queries across silos
* Interactive analytics on big data
* Ad-hoc SQL queries
* BI and reporting on distributed data
* ETL and data pipeline queries
* Real-time analytics

## Related templates

* Data warehouses: `postgresql/`, `clickhouse/`, for connecting to RDBMS
* ETL tools: `airflow/`, `dagster/` for data pipeline orchestration
* BI platforms: Use Trino as a data source for Tableau, Looker, Metabase, or Superset

## Troubleshooting

* **Access Web UI**: Navigate to `http://localhost:8080` to view running queries and statistics
* **Check catalog connections**:

```sql theme={null}
SHOW CATALOGS;
SHOW SCHEMAS FROM catalog_name;
```

* **Check logs**:

```bash theme={null}
monk logs -l 500 -f trino/trino
```

* **Slow queries**: Check query plan with `EXPLAIN` statement
* **Connector issues**: Verify catalog configuration files in `${monk-volume-path}/trino/catalog`
* **Memory errors**: Increase `query-max-memory` or `query-max-memory-per-node` variables
* **Resource monitoring**: Use Web UI to monitor CPU, memory, and query performance
* **Query history**: Review failed queries in Web UI for troubleshooting


# WordPress
Source: https://docs.monk.io/integrations/monk-wordpress

Ready-to-run WordPress container template you can run directly or inherit to integrate a CMS into your stack.

## Overview

This template provides a production‑ready WordPress instance as a Monk runnable. You can:

* Run it directly to get a managed WordPress site with database
* Inherit it in your own runnable to seamlessly add a CMS to your stack

WordPress powers over 40% of all websites on the internet. It's a powerful, flexible CMS for blogs, e-commerce sites, and enterprise portals.

## What this template manages

* WordPress container (`wordpress` image, configurable tag)
* MySQL or MariaDB database
* Network service on ports 80/443
* Persistent volumes for uploads, themes, and plugins
* Optional initialization of database and security keys

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run WordPress stack

```bash theme={null}
monk run wordpress/stack
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `wordpress/stack.yaml`, then `monk load MANIFEST` and run.

Once started, access WordPress at `http://localhost:80` and complete the famous 5-minute installation.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # WordPress
  wordpress-image-tag: "latest"       # container image tag
  wordpress-port: "80"                # HTTP port
  wordpress-https-port: "443"         # HTTPS port (env: WORDPRESS_HTTPS_PORT)
  wordpress-table-prefix: "wp_"       # database table prefix (env: WORDPRESS_TABLE_PREFIX)
  
  # Database
  wordpress-db-host: "mysql"          # database host (env: WORDPRESS_DB_HOST)
  wordpress-db-name: "wordpress"      # database name (env: WORDPRESS_DB_NAME)
  wordpress-db-user: "wordpress"      # database user (env: WORDPRESS_DB_USER)
  wordpress-db-password: "..."        # database password (env: WORDPRESS_DB_PASSWORD)
  
  # Security
  wordpress-auth-key: "..."           # generate unique keys
  wordpress-secure-auth-key: "..."    # at wordpress.org/secret-key
  wordpress-logged-in-key: "..."      # (env: WORDPRESS_AUTH_KEY, etc.)
  wordpress-nonce-key: "..."
```

Data is persisted under `${monk-volume-path}/wordpress` and `${monk-volume-path}/mysql` on the host.

## Use by inheritance (recommended for websites)

Inherit the WordPress runnable in your application and declare a connection. Example:

```yaml theme={null}
namespace: mysite
cms:
  defines: runnable
  inherits: wordpress/stack
  variables:
    wordpress-db-password: <- secret("wordpress-db-password")
    wordpress-auth-key: <- secret("wordpress-auth-key")
    wordpress-secure-auth-key: <- secret("wordpress-secure-auth-key")
    wordpress-logged-in-key: <- secret("wordpress-logged-in-key")
    wordpress-nonce-key: <- secret("wordpress-nonce-key")
```

Then set the secrets once and run your site:

```bash theme={null}
monk secrets add -g wordpress-db-password="STRONG_PASSWORD"
monk secrets add -g wordpress-auth-key="<generated-key>"
# Generate security keys at https://api.wordpress.org/secret-key/1.1/salt/
monk run mysite/cms
```

## Ports and connectivity

* HTTP: TCP port `80`
* HTTPS: TCP port `443` (if configured with SSL)
* Admin panel: `http://\<host>/wp-admin/`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the WordPress host.

## Persistence and configuration

* WordPress files: `${monk-volume-path}/wordpress/html:/var/www/html`
* Uploads: `${monk-volume-path}/wordpress/uploads:/var/www/html/wp-content/uploads`
* Plugins: `${monk-volume-path}/wordpress/plugins:/var/www/html/wp-content/plugins`
* Themes: `${monk-volume-path}/wordpress/themes:/var/www/html/wp-content/themes`
* MySQL data: `${monk-volume-path}/mysql:/var/lib/mysql`

## Related templates

* Combine with databases (MariaDB, MySQL) for content storage
* Use with CDN for static asset delivery
* Integrate with object storage (S3, Minio) for media files

## Troubleshooting

* Access WordPress admin at `http://localhost/wp-admin/`
* For database connection errors, verify MySQL is running and credentials are correct
* If you changed `wordpress-db-password` but the container has existing data, authentication may fail. Either reset the data volume or update the password inside the DB to match.
* Enable WordPress debug mode in `wp-config.php`:

```php theme={null}
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f wordpress/wordpress
monk logs -l 500 -f wordpress/mysql
```

* For white screen of death, check PHP error logs
* For plugin conflicts, rename plugins folder to disable all
* For theme issues, switch to default theme


# Apache ZooKeeper
Source: https://docs.monk.io/integrations/monk-zookeeper

Ready-to-run Apache ZooKeeper container template you can run directly or inherit to integrate distributed coordination and configuration management.

## Overview

This template provides a production‑ready Apache ZooKeeper instance as a Monk runnable. You can:

* Run it directly to get a managed ZooKeeper server with sensible defaults
* Inherit it in your own infrastructure to add distributed coordination and configuration management

Apache ZooKeeper is a centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services. It is used by distributed systems like Kafka, Hadoop, HBase, and others for coordination.

## What this template manages

* ZooKeeper container (`zookeeper` image, configurable tag)
* Network services on ports 2181 (client), 2888 (follower), 3888 (election)
* Persistent data and transaction log storage
* Configuration management
* Ensemble coordination (for multi-node setups)

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run ZooKeeper with defaults

```bash theme={null}
monk run zookeeper/zookeeper
```

3. Customize configuration (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. For production deployments, it's recommended to inherit this template and customize the configuration as shown below.

* Preferred: inherit and override variables as needed for your use case.
* Alternative: fork/clone and edit the `variables` in `zookeeper.yml`, then `monk load MANIFEST` and run.

Once started, connect to ZooKeeper at `localhost:2181` (or the runnable hostname inside Monk networks).

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  zookeeper-image-tag: "latest"       # container image tag
  client-port: "2181"                 # client connection port
  tick-time: "2000"                   # tick time in milliseconds
  init-limit: "10"                    # follower init time limit
  sync-limit: "5"                     # follower sync time limit
  max-client-cnxns: "60"              # max concurrent client connections
```

Data is persisted under `${monk-volume-path}/zookeeper` on the host. Configuration files can be customized as needed for advanced setups.

## Use by inheritance (recommended for distributed systems)

Inherit ZooKeeper to provide coordination for distributed services. Example:

```yaml theme={null}
namespace: myapp
coordination:
  defines: runnable
  inherits: zookeeper/zookeeper
kafka:
  defines: runnable
  containers:
    kafka:
      image: confluentinc/cp-kafka:latest
      environment:
        - KAFKA_ZOOKEEPER_CONNECT=coordination:2181
  connections:
    zk:
      runnable: coordination
      service: zookeeper
  variables:
    zookeeper-host:
      value: <- connection-hostname("zk")
```

## Ports and connectivity

* Service: `zookeeper` on TCP port `2181` (client connections)
* Follower port: TCP port `2888` (ensemble communication)
* Election port: TCP port `3888` (leader election)
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the ZooKeeper host.

## Persistence and configuration

* Data path: `${monk-volume-path}/zookeeper/data:/data`
* Transaction logs: `${monk-volume-path}/zookeeper/datalog:/datalog`
* ZooKeeper stores znodes and transaction logs persistently
* Ensure the host volumes are writable by the container user

## Features

* Distributed configuration management
* Naming registry
* Distributed synchronization (locks, barriers)
* Leader election
* Group membership services
* Reliable data storage with ACID properties
* Watch mechanism for change notifications

## Ensemble (Cluster) Mode

For production, run ZooKeeper in ensemble mode (3 or 5 nodes):

* Provides high availability
* Tolerates node failures
* Requires odd number of nodes (3, 5, 7)
* Maintains quorum for consistency

## Use cases

ZooKeeper is essential for:

* Kafka cluster coordination
* Hadoop NameNode HA
* HBase master election
* Distributed lock management
* Configuration management
* Service discovery

## Related templates

* See other templates in this repository for complementary services (Kafka, Hadoop, HBase)
* Combine with monitoring tools for observability

## Troubleshooting

* Test ZooKeeper connectivity:

```bash theme={null}
echo ruok | nc localhost 2181
# Should return: imok
```

* Check server status:

```bash theme={null}
echo stat | nc localhost 2181
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f zookeeper/zookeeper
```

* For ensemble setups, ensure all nodes can communicate on ports 2888 and 3888.
* Verify persistent storage is writable by the container user.
* Monitor disk space for transaction logs to prevent disk full issues.
* If configuration changes don't apply, ensure the container has been restarted.


# Neon
Source: https://docs.monk.io/integrations/neon

Serverless Postgres with branching and autoscaling.

## What is this integration?

Provision Neon projects, branches, computes, and roles.

## What Monk manages

* Project, Branch, Compute, Role

## Auth

* Uses a Monk secret (e.g., neon-api-key)

## Getting Started

1. Set secret:

```bash theme={null}
monk secrets add -g neon-api-key="neon_secret_key"
```

2. Define Neon resources (save as neon.yaml):

```yaml theme={null}
namespace: examples

my-neon-project:
  defines: neon/project
  secret_ref: neon-api-key
  name: my-neon-project
  region_id: aws-us-east-2
  pg_version: 17
  permitted-secrets:
    neon-api-key: true

dev-branch:
  defines: neon/branch
  secret_ref: neon-api-key
  projectId: \<- connection-target("project") entity-state get-member("id")
  name: dev
  connections:
    project:
      runnable: examples/my-neon-project
      service: data
  depends:
    wait-for:
      runnables:
        - examples/my-neon-project
      timeout: 60

dev-compute:
  defines: neon/compute
  secret_ref: neon-api-key
  projectId: \<- connection-target("project") entity-state get-member("id")
  branchId: \<- connection-target("branch") entity-state get-member("id")
  computeType: read_write
  minCu: 1
  maxCu: 2
  connections:
    project:
      runnable: examples/my-neon-project
      service: data
    branch:
      runnable: examples/dev-branch
      service: data
  depends:
    wait-for:
      runnables:
        - examples/my-neon-project
        - examples/dev-branch
      timeout: 60
```

3. Create/update:

```bash theme={null}
monk update examples/my-neon-project
monk update examples/dev-branch
monk update examples/dev-compute
```


# Netlify
Source: https://docs.monk.io/integrations/netlify

Managed hosting, deploys, and forms for static sites.

## What is this integration?

Manage Netlify sites, deploys, and forms via API.

## What Monk manages

* Site, Deploy, Form

## Auth

* Uses a Monk secret (e.g., netlify-api-token)

## Getting Started

1. Set secret:

```bash theme={null}
monk secrets add -g netlify-api-token="netlify_api_token"
```

2. Define a site and deploy (save as netlify.yaml):

```yaml theme={null}
namespace: netlify-example

my-site:
  defines: netlify/site
  secret_ref: netlify-api-token
  name: my-awesome-site
  custom_domain: mydomain.com
  permitted-secrets:
    netlify-api-token: true

prod-deploy:
  defines: netlify/deploy
  secret_ref: netlify-api-token
  site_id: \<- connection-target("site") entity-state get-member("id")
  dir: ./dist
  prod: true
  connections:
    site:
      runnable: netlify-example/my-site
      service: data
  depends:
    wait-for:
      runnables:
        - netlify-example/my-site
      timeout: 120
```

3. Create/update:

```bash theme={null}
monk update netlify-example/my-site
monk update netlify-example/prod-deploy
```


# PostgreSQL
Source: https://docs.monk.io/integrations/postgresql

Production-ready PostgreSQL runnable you can run directly or inherit to integrate a relational database into your stack.

## Overview

This template provides a PostgreSQL runnable exposing port 5432 with a persistent data volume. Use it directly for quick starts, or inherit it in your app and wire credentials via Monk secrets.

## Quick start (run directly)

```bash theme={null}
monk load MANIFEST
monk run postgresql/db
```

Connect to `localhost:5432` with the default credentials from `postgres.yml`.

## Configuration

Key variables in `postgres.yml` (under `postgresql/db`):

```yaml theme={null}
variables:
  db_user: monk                 # env: POSTGRES_USER
  db_pass: adminpassword        # env: POSTGRES_PASSWORD
  db_name: monk                 # env: POSTGRES_DB
```

Note: When running the base template directly, values come from the template. For production, inherit and replace with Monk secrets.

## Inherit and use secrets (recommended)

```yaml theme={null}
namespace: myapp

db:
  defines: runnable
  inherits: postgresql/db

api:
  defines: runnable
  containers:
    api:
      image: myorg/api
  connections:
    database:
      runnable: db
      service: postgres
  variables:
    database-host:
      value: <- connection-hostname("database")
    database-user:
      value: <- secret("db_user")
    database-password:
      value: <- secret("db_pass")
    database-name:
      value: <- secret("db_name")
```

Set secrets once, then run:

```bash theme={null}
monk secrets add -g db_user="appuser"
monk secrets add -g db_pass="STRONG_PASSWORD"
monk secrets add -g db_name="appdb"

monk run myapp/api
```

## Ports and persistence

* Service: `postgres` on TCP `5432`
* Data path: `${monk-volume-path}/postgresql:/var/lib/postgresql/data`

## Credential updates

This template includes a custom entrypoint that automatically updates the database password when the `POSTGRES_PASSWORD` environment variable changes. Unlike the default PostgreSQL Docker image behavior (which only applies credentials on first initialization), this template ensures password changes take effect on existing databases.

When the container starts:

1. If an existing database is detected, the entrypoint updates the user password via `ALTER USER`
2. If it's a fresh initialization, credentials are applied normally by the PostgreSQL image

## Troubleshooting

* Ensure the host volume is writable by the container.
* Check container logs (`monk logs postgresql/db`) if credential updates fail.


# Redis Cloud
Source: https://docs.monk.io/integrations/redis-cloud

Managed Redis databases with Essentials and Pro tiers.

## What is this integration?

Redis Cloud is a fully managed Redis service that offers both Essentials (shared) and Pro (dedicated) database tiers with automatic failover, backups, and scaling.

## What Monk manages

* Essentials Subscription, Essentials Database
* Pro Subscription, Pro Database

## What the Agent can do and how to use it

* **Subscription Management**: Create and manage Essentials and Pro subscriptions
* **Database Provisioning**: Deploy Redis databases with configurable memory, persistence, and modules
* **Backup & Recovery**: Create on-demand snapshots and restore from external backups
* **Security**: Configure TLS, IP access lists, and authentication
* **High Availability**: Enable replication and multi-zone deployments (Pro)
* **Clustering**: Configure Redis Cluster with sharding (Pro)

Steps:

1. Set Redis Cloud API secrets
2. monk update \<namespace>/\<name>

## Obtaining Redis Cloud Credentials

To use Redis Cloud with Monk, you'll need API keys from your Redis Cloud account.

### What You'll Need

* **Account Key** - Redis Cloud Account API key
* **User Key** - Redis Cloud User API key
* **Database Password** - Password for database access (Monk can generate this)

### Step-by-Step

1. **Log into Redis Cloud** at [https://app.redislabs.com/](https://app.redislabs.com/)
2. Navigate to **Account Settings** (gear icon)
3. Go to **API Keys** section
4. Find your **Account Key** and **User Key**
   * If no keys exist, contact Redis Cloud support to enable API access
5. **Copy both keys** and save them securely
6. **Choose a database password** - or let Monk generate a secure one

### Providing to Monk

When using Redis Cloud, ask Monk:

```
use Redis Cloud instead of self-hosted Redis
```

Monk will request your Redis Cloud credentials if not already configured.

### Security Best Practices

✅ **Keep keys secure** - API keys have full account access
✅ **Use strong database passwords** - Let Monk generate them
✅ **Enable IP access lists** - Restrict database access to your application IPs
✅ **Monitor usage** - Check Redis Cloud activity logs

## Auth

* Uses Monk secrets for Redis Cloud API credentials:
  * `redis-cloud-account-key`: Account API key
  * `redis-cloud-user-key`: User API key
  * `redis-cloud-db-password`: Database password

## Getting Started

1. Provide credentials to Monk when deploying:

```
use Redis Cloud for caching
```

### CLI Reference (Advanced)

For manual secret management:

```bash theme={null}
monk secrets add -g redis-cloud-account-key="YOUR_ACCOUNT_KEY"
monk secrets add -g redis-cloud-user-key="YOUR_USER_KEY"
monk secrets add -g redis-cloud-db-password="SECURE_PASSWORD"
```

2. Define an Essentials database (save as redis.yaml):

```yaml theme={null}
namespace: my-app

my-subscription:
  defines: redis-cloud/essentials-subscription
  account_key_secret: redis-cloud-account-key
  user_key_secret: redis-cloud-user-key
  name: My-Subscription
  size: 30
  provider: AWS
  region: us-east-1
  permitted-secrets:
    redis-cloud-account-key: true
    redis-cloud-user-key: true

my-redis:
  defines: redis-cloud/essentials-database
  subscription_id: <- connection-target("sub") entity-state get-member("id")
  account_key_secret: redis-cloud-account-key
  user_key_secret: redis-cloud-user-key
  name: my-redis-db
  connections:
    sub:
      runnable: my-app/my-subscription
      service: subscription
  depends:
    wait-for:
      runnables:
        - my-app/my-subscription
      timeout: 300
```

3. Create/update:

```bash theme={null}
monk update my-app/my-subscription
monk update my-app/my-redis
monk describe my-app/my-redis
```

## Pro Database (Dedicated Clusters)

For production workloads requiring dedicated resources, clustering, and advanced features:

```yaml theme={null}
namespace: my-app

pro-subscription:
  defines: redis-cloud/pro-subscription
  account_key_secret: redis-cloud-account-key
  user_key_secret: redis-cloud-user-key
  name: Pro-Subscription
  payment_method_type: Visa
  permitted-secrets:
    redis-cloud-account-key: true
    redis-cloud-user-key: true

pro-redis:
  defines: redis-cloud/pro-database
  name: production-redis
  subscription_id: <- connection-target("sub") entity-state get-member("id")
  dataset_size_in_gb: 1
  data_persistence: aof-every-1-second
  replication: true
  remote_backup:
    active: true
    interval: every-6-hours
    storage_type: s3
    storage_path: s3://my-backups/redis/
  connections:
    sub:
      runnable: my-app/pro-subscription
      service: subscription
```

**Pro Features:**

* Dedicated infrastructure with configurable memory/storage
* Redis modules (RediSearch, RedisJSON, RedisTimeSeries, etc.)
* Active-Active geo-replication
* Scheduled remote backups to S3/GCS/Azure
* VPC peering and private endpoints

## Backup & Snapshot Actions

| Action               | Description                              |
| -------------------- | ---------------------------------------- |
| `get-backup-info`    | View backup configuration and status     |
| `create-snapshot`    | Create an on-demand backup snapshot      |
| `list-snapshots`     | List available backups                   |
| `restore`            | Restore/import data from external backup |
| `get-restore-status` | Check restore task progress              |

```bash theme={null}
# View backup configuration
monk do my-app/my-redis/get-backup-info

# Create a backup snapshot
monk do my-app/my-redis/create-snapshot

# List available backups
monk do my-app/my-redis/list-snapshots

# Restore from S3 backup
monk do my-app/my-redis/restore source_type="aws-s3" source_uri="s3://bucket/backup.rdb"

# Check restore task progress
monk do my-app/my-redis/get-restore-status task_id="xxx"
```


# Stripe
Source: https://docs.monk.io/integrations/stripe

Complete payment processing, subscription management, and webhook handling for modern applications.

# Stripe Integration

Build complete payment flows, subscription systems, and revenue management with Stripe and Monk.

## Why Stripe?

**Stripe** is the complete payments platform for internet business, offering:

* **Global payments** - Accept cards, digital wallets, bank transfers in 135+ currencies
* **Subscription management** - Handle recurring billing, trials, coupons, and churn
* **No-code integrations** - Pre-built checkout flows and customer portals
* **Enterprise security** - PCI DSS Level 1 compliance and advanced fraud protection
* **Developer experience** - Excellent APIs, SDKs, and webhook handling

**Perfect for:**

* SaaS applications with subscription billing
* E-commerce platforms and marketplaces
* Mobile apps with in-app purchases
* B2B software with complex pricing models
* Platforms handling payments at scale

## What Monk Manages

This integration ships the following Stripe entities:

* **Credentials (stripe/credentials)**: Validates API key, derives mode (test/live), exposes `account_id` and optional `publishable_key`.
* **Product (stripe/product)**: Creates or adopts a product by `product_id` or name; supports `product_description` and `metadata`.
* **Price (stripe/price)**: Resolves by `lookup_key` or creates a price with `currency`, `unit_amount`, optional `recurring_interval`, and `product_id`.
* **Webhook endpoint (stripe/webhook-endpoint)**: Creates an endpoint at `destination_url`, subscribes to `event_types`, stores signing secret in `signing_secret_ref` (default `stripe-webhook-secret`).

## Step-by-Step Integration Guide

### Step 1: Set Up Stripe Account

1. **Create a Stripe account** at [stripe.com](https://stripe.com)
2. **Get your API keys** from the dashboard (Publishable key and Secret key)
3. **Configure webhooks** in your Stripe dashboard for payment events

### Step 2: Configure Monk Secrets

Add your Stripe credentials as Monk secrets:

```bash theme={null}
# Test environment
monk secrets add -g stripe-secret-key-test "sk_test_..."

# Live environment (when ready for production)
monk secrets add -g stripe-secret-key-live "sk_live_..."

# Webhook signing secret (stored by entity on create, or set manually)
monk secrets add -g stripe-webhook-secret "whsec_..."
```

### Step 3: Create Your Stripe Configuration

Create a file named `payment-system.yaml`:

```yaml theme={null}
namespace: my-saas-payments

# Stripe credentials for different environments
stripe-creds-test:
  defines: stripe/credentials
  secret_ref: stripe-secret-key-test
  publishable_key: "pk_test_..."  # optional, convenience only

stripe-creds-live:
  defines: stripe/credentials
  secret_ref: stripe-secret-key-live
  publishable_key: "pk_live_..."  # optional, convenience only

# SaaS product with multiple pricing tiers
saas-product:
  defines: stripe/product
  secret_ref: stripe-secret-key-live
  name: "My SaaS Platform"
  product_description: "Complete business management platform"
  images: ["https://myapp.com/product-image.jpg"]
  metadata:
    category: "productivity"
    tier: "enterprise"

# Monthly subscription price
monthly-price:
  defines: stripe/price
  secret_ref: stripe-secret-key-live
  product_id: <- connection-target("saas-product") entity-state get-member("product_id")
  lookup_key: "monthly_basic"
  currency: usd
  unit_amount: 2900  # $29.00
  recurring_interval: month
  # trial periods can be configured at checkout/session level

# Annual subscription price (with discount)
annual-price:
  defines: stripe/price
  secret_ref: stripe-secret-key-live
  product_id: <- connection-target("saas-product") entity-state get-member("product_id")
  lookup_key: "annual_basic"
  currency: usd
  unit_amount: 29000  # $290.00 (2 months free)
  recurring_interval: year
  metadata:
    discount: "20_percent"

# Webhook endpoint for payment events
payment-webhook:
  defines: stripe/webhook-endpoint
  secret_ref: stripe-secret-key-live
  destination_url: "https://myapp.com/api/stripe/webhook"
  event_types:
    - "customer.subscription.created"
    - "customer.subscription.updated"
    - "customer.subscription.deleted"
    - "invoice.payment_succeeded"
    - "invoice.payment_failed"
    - "checkout.session.completed"
  signing_secret_ref: stripe-webhook-secret

  # Connect to credentials for proper API access
  connections:
    credentials:
      runnable: my-saas-payments/stripe-creds-live
      service: data
```

### Step 4: Deploy and Test

Deploy your payment infrastructure:

```bash theme={null}
# Deploy in test mode first
monk update my-saas-payments/stripe-creds-test
monk update my-saas-payments/saas-product
monk update my-saas-payments/monthly-price
monk update my-saas-payments/annual-price
monk update my-saas-payments/payment-webhook

# Verify everything is working
monk describe my-saas-payments/saas-product
monk describe my-saas-payments/monthly-price

# Test webhook endpoint
stripe listen --forward-to localhost:3000/api/stripe/webhook
```

## Advanced Configuration Examples

### Multi-Product SaaS Platform

```yaml theme={null}
namespace: enterprise-saas

# Multiple products with different features
starter-product:
  defines: stripe/product
  secret_ref: stripe-secret-key-live
  name: "Starter Plan"
  product_description: "Perfect for small teams getting started"

professional-product:
  defines: stripe/product
  secret_ref: stripe-secret-key-live
  name: "Professional Plan"
  product_description: "Advanced features for growing businesses"

enterprise-product:
  defines: stripe/product
  secret_ref: stripe-secret-key-live
  name: "Enterprise Plan"
  product_description: "Complete solution for large organizations"

# Corresponding prices
starter-monthly:
  defines: stripe/price
  secret_ref: stripe-secret-key-live
  product_id: <- connection-target("starter-product") entity-state get-member("product_id")
  lookup_key: "starter_monthly"
  currency: usd
  unit_amount: 0  # Free tier
  recurring_interval: month

pro-monthly:
  defines: stripe/price
  secret_ref: stripe-secret-key-live
  product_id: <- connection-target("professional-product") entity-state get-member("product_id")
  lookup_key: "pro_monthly"
  currency: usd
  unit_amount: 4900  # $49/month
  recurring_interval: month

enterprise-monthly:
  defines: stripe/price
  secret_ref: stripe-secret-key-live
  product_id: <- connection-target("enterprise-product") entity-state get-member("product_id")
  lookup_key: "enterprise_monthly"
  currency: usd
  unit_amount: 19900  # $199/month
  recurring_interval: month
  metadata:
    seats_included: 50
    custom_features: true
```

### E-commerce Integration

```yaml theme={null}
namespace: online-store

# Store products
tshirt-product:
  defines: stripe/product
  secret_ref: stripe-secret-key-live
  name: "Premium Cotton T-Shirt"
  product_description: "Comfortable, high-quality cotton t-shirt"
  images: ["https://store.com/tshirt-image.jpg"]

hoodie-product:
  defines: stripe/product
  secret_ref: stripe-secret-key-live
  name: "Zip Hoodie"
  product_description: "Warm and stylish hoodie for any occasion"

# One-time purchase prices
tshirt-price-small:
  defines: stripe/price
  secret_ref: stripe-secret-key-live
  product_id: <- connection-target("tshirt-product") entity-state get-member("product_id")
  lookup_key: "tshirt_small"
  currency: usd
  unit_amount: 2500  # $25.00
  # No recurring fields for one-time purchases

hoodie-price-large:
  defines: stripe/price
  secret_ref: stripe-secret-key-live
  product_id: <- connection-target("hoodie-product") entity-state get-member("product_id")
  lookup_key: "hoodie_large"
  currency: usd
  unit_amount: 6500  # $65.00
```

## Webhook Event Handling

Monk helps you handle Stripe webhook events automatically:

```yaml theme={null}
# Advanced webhook configuration with event filtering
advanced-webhook:
  defines: stripe/webhook-endpoint
  secret_ref: stripe-secret-key-live
  destination_url: "https://myapp.com/api/webhooks/stripe"
  event_types:
    - "payment_intent.succeeded"
    - "payment_intent.payment_failed"
    - "customer.subscription.trial_will_end"
    - "invoice.payment_action_required"
  signing_secret_ref: stripe-webhook-secret

  # Custom headers for webhook verification
  custom_headers:
    "X-Stripe-Signature": true
```

## Subscription Management

### Handling Subscription Lifecycle

```yaml theme={null}
# Customer portal for self-service subscription management
customer-portal:
  defines: runnable
  script: |
    #!/bin/bash
    # Create Stripe customer portal session
    stripe customer portal create \
      --customer $STRIPE_CUSTOMER_ID \
      --return-url https://myapp.com/dashboard
```

### Trial and Onboarding

```yaml theme={null}
# Automated trial extension for users
trial-extension:
  defines: runnable
  script: |
    #!/bin/bash
    # Extend trial period for customers who need more time
    stripe subscriptions update $SUBSCRIPTION_ID \
      --trial-end $(date -d '+14 days' +%s)
```

## Troubleshooting & Best Practices

### Common Issues

**Webhook signature verification failing:**

```bash theme={null}
# Ensure webhook secret is correctly configured
monk secrets list | grep stripe-webhook
# Verify the webhook endpoint URL is accessible
curl -X POST https://yourapp.com/api/webhooks/stripe \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook"}'
```

**Test mode vs Live mode confusion:**

* Always test with test API keys and toggle to live only when ready
* Use separate namespaces for test and live environments
* Never use live credentials in development

**Subscription state synchronization:**

```bash theme={null}
# Check subscription status in Stripe dashboard
# Verify customer portal configuration
monk describe my-saas-payments/customer-portal
```

### Best Practices

1. **Environment Separation**: Use separate Stripe accounts or clear test/live toggles
2. **Webhook Security**: Always verify webhook signatures in production
3. **Error Handling**: Implement proper retry logic for failed payments
4. **Monitoring**: Track payment success rates and failed payment reasons
5. **Compliance**: Handle tax calculation and invoice generation properly

### Security Considerations

* Store API keys as encrypted secrets, never in code
* Use restricted API keys with minimal required permissions
* Implement webhook signature verification
* Regularly rotate API keys
* Monitor for suspicious payment activity

## Real-World Use Cases

### SaaS Platform

Complete subscription billing with trial periods, multiple pricing tiers, and customer self-service portals.

### E-commerce Store

Process one-time payments, handle inventory, manage coupons, and integrate with shipping providers.

### Marketplace

Handle multi-party payments, platform fees, and automated payouts to sellers.

### Mobile App

Implement in-app purchases, subscription renewals, and cross-platform payment processing.

## Integration with Other Services

Stripe works seamlessly with:

* **Monk Databases**: Store customer and subscription data
* **Email Services**: Send payment confirmations and receipts
* **Analytics**: Track payment metrics and conversion funnels
* **CRM Systems**: Sync customer data and payment history
* **Tax Services**: Calculate and collect appropriate taxes

## Support & Resources

* **Stripe Documentation**: [Complete API Reference](https://docs.stripe.com/api)
* **Webhook Guide**: [Testing Webhooks](https://docs.stripe.com/webhooks/test)
* **Recipes & Examples**: [Stripe Samples](https://github.com/stripe-samples)
* **Community Support**: [Stripe Developer Forum](https://community.stripe.dev/)


# Vercel
Source: https://docs.monk.io/integrations/vercel

Lightning-fast frontend hosting, serverless functions, and global deployment platform.

# Vercel Integration

Deploy modern web applications with automatic scaling, global CDN, and serverless functions through Monk.

## Why Vercel?

**Vercel** is the platform for frontend developers, offering:

* **Instant deployments** - Deploy from Git with zero configuration
* **Global edge network** - 99.99% uptime with 150+ edge locations worldwide
* **Serverless functions** - Run API routes and serverless functions at the edge
* **Advanced caching** - Automatic static asset optimization and caching
* **Preview deployments** - Every pull request gets its own deployment URL
* **Analytics & monitoring** - Built-in performance monitoring and analytics

**Perfect for:**

* React, Next.js, Vue, Nuxt, Svelte applications
* Static sites and JAMstack applications
* Serverless API routes and functions
* Progressive Web Apps (PWAs)
* E-commerce frontends and marketing sites

## What Monk Manages

Monk handles your complete Vercel deployment pipeline:

* **Projects**: Create and configure Vercel projects and teams
* **Deployments**: Automated deployments from your codebase
* **Environment variables**: Secure secret and config management
* **Domains**: Custom domain configuration and SSL certificates
* **Serverless functions**: Deploy and manage edge functions
* **Preview deployments**: Automatic branch and PR deployments
* **Analytics integration**: Performance monitoring and insights

## Obtaining Vercel Credentials

To deploy to Vercel with Monk, you'll need a Vercel API token.

### What You'll Need

* **Personal Access Token** - Vercel API token
* **Optional:** Team ID (for team deployments)

### Step-by-Step

1. **Log into Vercel** at [https://vercel.com](https://vercel.com)
2. Navigate to **Settings** → **Tokens**
3. Click **Create Token**
4. **Token name:** "Monk Deployment"
5. **Scope:** Choose "Full Account" or minimal scopes:
   * Deploy projects
   * Read project information
6. **Expiration:** Set based on your security policy (or no expiration)
7. Click **Create** and **copy the token**
8. Save it securely

**For team deployments:**

* Go to your team settings to find **Team ID**
* Provide both token and Team ID to Monk

### Providing to Monk

When deploying your frontend to Vercel, ask Monk:

```
deploy my frontend to Vercel
```

```
deploy to Vercel with staging and production environments
```

Monk will request your Vercel credentials if not already configured.

### Security Best Practices

✅ **Use tokens with minimal scopes** - Only grant deploy and read access
✅ **Set expiration dates** - Rotate tokens regularly
✅ **Enable 2FA** on your Vercel account
✅ **Monitor deployments** - Check Vercel dashboard for unauthorized activity
✅ **Revoke unused tokens** - Remove old tokens when no longer needed

## Using Vercel with Monk

### Deploy Your Frontend

Tell Monk to deploy to Vercel:

```
deploy my React app to Vercel
```

```
put the frontend on Vercel and backend on AWS
```

Monk handles:

* Creating Vercel project
* Configuring build settings
* Setting up environment variables
* Deploying to Vercel's global network

### Configuration Examples

Below are template examples for advanced users who want to configure Vercel deployments directly.

Create a file named `frontend-deployment.yaml`:

```yaml theme={null}
namespace: my-web-app

# Vercel project configuration
nextjs-app:
  defines: vercel/project
  name: "my-awesome-nextjs-app"
  framework: "nextjs"
  root_directory: "./"
  permitted-secrets:
    vercel-api-token: true
    github-token: true

  # Project settings
  settings:
    build_command: "npm run build"
    output_directory: ".next"
    install_command: "npm install"
    dev_command: "npm run dev"

  # Environment variables for all deployments
  environment_variables:
    NODE_ENV: "production"
    NEXT_PUBLIC_API_URL: "https://api.myapp.com"
    DATABASE_URL: \<- connection-target("database") entity-state get-member("connection_string")

  # GitHub integration for automatic deployments
  git_repository:
    type: "github"
    repo: "myorg/my-awesome-nextjs-app"
    production_branch: "main"
    pr_deployment_enabled: true

# Production deployment
production-deployment:
  defines: runnable
  inherits: vercel/deploy
  connections:
    project:
      runnable: my-web-app/nextjs-app
      service: data
  variables:
    project: \<- connection-target("project") entity-state get-member("name")
    environment: "production"
    source_path: "./"
    auto_deploy: true

# Staging deployment for testing
staging-deployment:
  defines: runnable
  inherits: vercel/deploy
  connections:
    project:
      runnable: my-web-app/nextjs-app
      service: data
  variables:
    project: \<- connection-target("project") entity-state get-member("name")
    environment: "staging"
    source_path: "./"
    auto_deploy: true

# Serverless API functions
api-functions:
  defines: vercel/deployment
  project_name: \<- connection-target("project") entity-state get-member("name")
  source_path: "./api"
  functions:
    - "api/contact.js"
    - "api/webhook.js"
    - "api/auth.js"
  environment_variables:
    STRIPE_WEBHOOK_SECRET: \<- connection-target("stripe-webhook") entity-state get-member("secret")
```

### Step 4: Deploy and Monitor

Deploy your application:

```bash theme={null}
# Deploy the project configuration
monk update my-web-app/nextjs-app

# Deploy to production
monk update my-web-app/production-deployment

# Deploy to staging
monk update my-web-app/staging-deployment

# Check deployment status
monk describe my-web-app/production-deployment

# Monitor deployments
monk ps -a | grep vercel
```

## Advanced Configuration Examples

### Next.js Application with Database

```yaml theme={null}
namespace: fullstack-app

# Database connection (example with Neon)
database:
  defines: neon/database
  name: "my-app-production-db"
  region: "us-east-1"

# Next.js app with database integration
nextjs-with-db:
  defines: vercel/project
  name: "my-fullstack-nextjs-app"
  framework: "nextjs"
  permitted-secrets:
    vercel-api-token: true
    database-url: true

  environment_variables:
    DATABASE_URL: \<- connection-target("database") entity-state get-member("connection_string")
    NEXTAUTH_SECRET: \<- connection-target("auth-secret") entity-state get-member("value")
    NEXTAUTH_URL: "https://my-fullstack-nextjs-app.vercel.app"

  functions:
    - "api/auth/[...nextauth].js"
    - "api/users.js"
    - "api/posts.js"
```

### Static Site with CMS

```yaml theme={null}
namespace: blog-site

# Strapi CMS backend
strapi-cms:
  defines: runnable
  script: |
    #!/bin/bash
    cd /app/cms && npm start

# Gatsby static site generator
gatsby-blog:
  defines: vercel/project
  name: "my-gatsby-blog"
  framework: "gatsby"
  build_command: "npm run build"
  output_directory: "public"
  permitted-secrets:
    vercel-api-token: true
    strapi-url: true

  environment_variables:
    GATSBY_STRAPI_URL: \<- connection-target("strapi-cms") entity-state get-member("url")
    GATSBY_ACTIVE_ENV: "production"

# Deploy static site
static-deployment:
  defines: runnable
  inherits: vercel/deploy
  connections:
    project:
      runnable: blog-site/gatsby-blog
      service: data
  variables:
    project: \<- connection-target("project") entity-state get-member("name")
    environment: "production"
    source_path: "./public"
```

### E-commerce Frontend

```yaml theme={null}
namespace: online-store-frontend

# E-commerce Next.js application
store-frontend:
  defines: vercel/project
  name: "my-online-store"
  framework: "nextjs"
  permitted-secrets:
    vercel-api-token: true
    stripe-keys: true

  environment_variables:
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: \<- connection-target("stripe-keys") entity-state get-member("publishable_key")
    NEXT_PUBLIC_API_URL: "https://api.mystore.com"
    NEXT_PUBLIC_CDN_URL: "https://cdn.mystore.com"

  # Custom domains
  domains:
    - "store.mydomain.com"
    - "www.store.mydomain.com"

# Deploy with preview environments
store-deployment:
  defines: runnable
  inherits: vercel/deploy
  connections:
    project:
      runnable: online-store-frontend/store-frontend
      service: data
  variables:
    project: \<- connection-target("project") entity-state get-member("name")
    environment: "production"
    auto_deploy: true
    preview_deployment: true
```

## Preview Deployments

Monk supports automatic preview deployments for every branch and pull request:

```yaml theme={null}
# Preview deployment configuration
preview-deployment:
  defines: runnable
  inherits: vercel/deploy
  connections:
    project:
      runnable: my-web-app/nextjs-app
      service: data
  variables:
    project: \<- connection-target("project") entity-state get-member("name")
    environment: "preview"
    source_path: "./"
    auto_deploy: true
    preview_deployment: true
    branch_name: \<- env("GIT_BRANCH", "main")
```

## Environment Management

### Environment-Specific Configurations

```yaml theme={null}
# Development environment
dev-deployment:
  defines: runnable
  inherits: vercel/deploy
  connections:
    project:
      runnable: my-web-app/nextjs-app
      service: data
  variables:
    project: \<- connection-target("project") entity-state get-member("name")
    environment: "development"
    environment_variables:
      NODE_ENV: "development"
      API_URL: "https://dev-api.myapp.com"
      DEBUG: "true"

# Production environment
prod-deployment:
  defines: runnable
  inherits: vercel/deploy
  connections:
    project:
      runnable: my-web-app/nextjs-app
      service: data
  variables:
    project: \<- connection-target("project") entity-state get-member("name")
    environment: "production"
    environment_variables:
      NODE_ENV: "production"
      API_URL: "https://api.myapp.com"
      SENTRY_DSN: \<- connection-target("sentry") entity-state get-member("dsn")
```

## Troubleshooting & Best Practices

### Common Issues

**Deployment failures:**

```bash theme={null}
# Check build logs
vercel logs --follow

# Verify environment variables
monk describe my-web-app/nextjs-app

# Check project settings in Vercel dashboard
```

**Domain issues:**

```bash theme={null}
# Verify DNS configuration
nslookup store.mydomain.com

# Check SSL certificate status
curl -I https://store.mydomain.com
```

**Performance issues:**

* Enable Vercel's edge caching for static assets
* Use Vercel Analytics to identify slow pages
* Optimize images and fonts for web delivery

### Best Practices

1. **Environment Variables**: Use separate secrets for each environment (dev, staging, prod)
2. **Branch Protection**: Enable branch protection rules for production branch
3. **Preview Deployments**: Always test changes in preview before merging to production
4. **Monitoring**: Set up uptime monitoring and error tracking (e.g., Sentry)
5. **CDN Optimization**: Use Vercel's edge locations for global performance

### Security Considerations

* Store API tokens as encrypted secrets
* Use restricted tokens with minimal permissions
* Enable 2FA on your Vercel account
* Regularly rotate deployment tokens
* Monitor for unauthorized deployments

## Real-World Use Cases

### SaaS Application

Deploy a full-stack Next.js application with authentication, database integration, and global CDN distribution.

### E-commerce Platform

Static storefront with dynamic product catalog, shopping cart, and integrated payment processing.

### Blog/Content Site

Gatsby or Next.js blog with CMS integration, SEO optimization, and fast global loading.

### Developer Portfolio

Showcase site with project galleries, contact forms, and performance analytics.

## Integration with Other Services

Vercel integrates seamlessly with:

* **Git Providers**: GitHub, GitLab, Bitbucket for automatic deployments
* **Databases**: MongoDB, PostgreSQL, MySQL for data storage
* **Authentication**: NextAuth.js, Auth0, Clerk for user management
* **Payments**: Stripe for e-commerce functionality
* **Monitoring**: Sentry, LogRocket for error tracking and analytics
* **CMS**: Strapi, Sanity, Contentful for content management

## Support & Resources

* **Vercel Documentation**: [Complete Guide](https://vercel.com/docs)
* **API Reference**: [REST API Docs](https://vercel.com/docs/rest-api)
* **Community**: [Vercel Community](https://vercel.community/)
* **Templates**: [Next.js Examples](https://nextjs.org/examples)
* **Learning**: [Vercel Learn](https://nextjs.org/learn)


# Backup & Restore
Source: https://docs.monk.io/prompting/backup-and-restore

Database backup and restore operations

<Note type="warning">
  **Chat-based backup/restore is coming soon.** While backup APIs exist for
  managed databases, full Monk chat integration is still in development. This
  guide shows the planned experience and current manual operations.
</Note>

## Future Chat-Based Backups

When fully integrated, you'll be able to ask Monk:

```
/monk back up my database
```

```
/monk show me available backups
```

```
/monk restore from the latest backup
```

This natural language interface is being built.

## Current Manual Operations

Today, backup/restore operations require using integration-specific actions or provider consoles.

→ [Databases](/features/databases)

## Managed Database Backups Today

Many managed databases include automated backups by default:

**MongoDB Atlas M10+:**

* Daily automated backups
* Configurable retention
* Point-in-time restore available

**AWS RDS:**

* Daily automated backups (1-35 days)
* Manual snapshots
* Point-in-time restore

**DigitalOcean:**

* Daily automated backups (7-day retention)
* No additional configuration needed

**Check your provider's integration docs for backup details:**

* [MongoDB Atlas](/integrations/mongodb-atlas) - Backup actions reference
* [AWS RDS](/integrations/aws-rds) - Snapshot operations
* [DigitalOcean Databases](/integrations/digitalocean-database) - Backup/restore actions
* [GCP Cloud SQL](/integrations/gcp) - Backup configuration
* [Redis Cloud](/integrations/redis-cloud) - Remote backup setup

## Databases with Backup Support

The following managed databases have backup/restore APIs:

### Production-Ready Backup APIs

**MongoDB Atlas** (M10+ dedicated clusters)

* ✅ Automated daily backups
* ✅ On-demand snapshots
* ✅ Point-in-time restore
* ❌ M0/M2/M5 free tier (no backup API)

**AWS RDS** (PostgreSQL, MySQL, MariaDB, SQL Server, Oracle)

* ✅ Automated daily backups (1-35 days retention)
* ✅ Manual snapshots
* ✅ Point-in-time restore
* ✅ Cross-region replication

**DigitalOcean Managed Databases** (PostgreSQL, MySQL, MongoDB, Redis)

* ✅ Automated daily backups (7-day retention)
* ✅ Fork-based restore (creates new cluster)
* ✅ Point-in-time restore (PostgreSQL/MySQL only)

**GCP Cloud SQL** (PostgreSQL, MySQL)

* ✅ Automated backups
* ✅ On-demand snapshots
* ✅ Point-in-time restore

**Azure Cosmos DB**

* ✅ Continuous backup (30 days retention)
* ✅ Periodic backup mode
* ✅ Point-in-time restore

**Redis Cloud** (Pro tier)

* ✅ Remote backups to S3/GCS/Azure
* ✅ Scheduled backups
* ✅ Import/restore from backup

**AWS DynamoDB**

* ✅ On-demand backups
* ✅ Point-in-time restore
* ✅ Continuous backups

### Using Backups Today

Currently, use integration-specific actions via templates or provider consoles:

**MongoDB Atlas example:**

See [MongoDB Atlas Integration](/integrations/mongodb-atlas) - includes actions for get-backup-info, create-snapshot, list-snapshots, restore

**AWS RDS example:**

See [AWS RDS Integration](/integrations/aws-rds) - includes actions for backup management

**DigitalOcean example:**

See [DigitalOcean Databases](/integrations/digitalocean-database) - includes actions for list-backups, restore

### Self-Hosted Databases

For containerized databases:

* No automated backup API
* Use manual procedures:
  * mongodump/mongorestore for MongoDB
  * pg\_dump/pg\_restore for PostgreSQL
  * mysqldump for MySQL
* Volume snapshots (cloud provider level)

## Backup Best Practices

### Before Major Changes

Always back up before:

* Database migrations
* Schema changes
* Version upgrades
* Infrastructure changes

```
/monk back up my database before migration
```

### Test Your Backups

Regularly verify backups can be restored:

```
/monk restore latest backup to a test database
```

Monk can restore backups to separate instances for testing without affecting production.

### Monitor Backup Status

Check backup health regularly:

```
/monk when was my last backup?
```

```
/monk show me failed backups
```

```
/monk what's my backup size?
```

### Automate Pre-Deployment Backups

For critical deployments, ask Monk to back up automatically:

```
/monk always back up database before deploying
```

## Backup Information by Provider

Each managed database provider offers different backup information:

**MongoDB Atlas Console:**

* View snapshots in Backup tab
* Shows snapshot ID, date, size, status
* Point-in-time restore window
* Retention policy settings

**AWS RDS Console:**

* Automated backups section
* Manual snapshots list
* Latest restorable time
* Backup window configuration

**DigitalOcean Control Panel:**

* Backups tab per database cluster
* 7-day automated backups listed
* Fork (restore) option per backup
* Point-in-time selections (PostgreSQL/MySQL)

**Redis Cloud Console:**

* Backup configuration in database settings
* Remote backup schedule
* S3/GCS/Azure backup locations
* Import/restore interface

## Common Backup Practices

### Pre-Migration Safety

Before switching database providers, ensure you have a recent backup:

**For MongoDB Atlas M10+:**

* Automated daily backups are already running
* Create on-demand snapshot via Atlas console or API if needed

**For AWS RDS:**

* Automated backups enabled by default (if backup\_retention\_period > 0)
* Create manual snapshot via AWS console or RDS API

**For self-hosted:**

* Use mongodump, pg\_dump, or mysqldump before migration
* Store backup files securely

### Production Backup Checklist

**Before deploying to production:**

* ✅ Verify automated backups are enabled (check provider console)
* ✅ Confirm retention period meets your requirements
* ✅ Test restore procedure (practice on staging)
* ✅ Document backup locations and access credentials
* ✅ Set up monitoring for backup failures (if available)

### Testing Restores

**Critical:** Test that you can actually restore from backups:

1. Create test database instance
2. Restore from backup to test instance
3. Verify data integrity
4. Document the restore process
5. Time the restore (know how long it takes)

Don't wait for an emergency to learn restore doesn't work.

## Backup Storage Costs

Backup storage has costs:

**MongoDB Atlas:**

* Backup storage charged separately from cluster
* Scales with data size
* Check Atlas billing for costs

**AWS RDS:**

* Free backup storage up to DB instance size
* Additional storage charged at standard rates

**DigitalOcean:**

* 7-day backups included
* No additional backup storage charges

**Redis Cloud:**

* Remote backup storage (S3/GCS/Azure) charged by provider
* Not included in Redis Cloud subscription

## Next Steps

* [Working with Databases](/prompting/working-with-databases) - Database operations
* [MongoDB Deployment Guide](/integration-guides/mongodb-deployment-guide) - MongoDB-specific guidance
* [Managing Costs](/prompting/managing-costs) - Track backup storage costs
* [Databases](/features/databases) - All database capabilities


# Configuring Services
Source: https://docs.monk.io/prompting/configuring-services

Update configuration and environment variables

## Add Environment Variables

```
/monk add FEATURE_FLAG_NEW_UI to the frontend
```

Add new environment variables to services.

→ [Configuration & Wiring](/features/configuration-and-wiring)

## Change Configuration

```
/monk change the database connection pool size to 20
```

Adjust service settings.

## Update API Configuration

```
/monk update the Stripe webhook URL
```

Reconfigure third-party API integrations.

→ [APIs](/features/apis)

## Review Configuration

```
/monk show me the full configuration
```

View complete system configuration.

## Change Service Settings

```
/monk set the Redis cache size to 4GB
```

Modify service-specific settings.

## Update Connection Strings

```
/monk change the Redis connection pool size to 50
```

Adjust connection settings.

## Rotate Secrets

```
/monk rotate the database password
```

Update passwords and credentials securely.

→ [Security](/features/security)

## Update CORS

```
/monk update CORS settings to allow requests from myapp.com
```

Modify networking configurations.

→ [Networking](/features/networking)

## What Monk Handles

**Automatic:**

* Connection strings
* Service URLs
* Internal networking
* Load balancer configuration

**You configure:**

* External API keys
* Feature flags
* Business logic constants
* Custom environment variables

## Zero-Downtime Updates

All configuration changes applied without downtime:

* Services restart gracefully
* Traffic shifted smoothly
* No user impact

## When Changes Apply

**Immediately:**

* Environment variables
* Connection settings
* Feature flags

**On next deployment:**

* Some infrastructure changes
* Major configuration updates

## Next Steps

* [Working with Databases](/prompting/working-with-databases) - Configure databases
* [Monitoring & Debugging](/prompting/monitoring-and-debugging) - Verify changes
* [Troubleshooting Issues](/prompting/troubleshooting) - Fix configuration problems


# Deploying Your First App
Source: https://docs.monk.io/prompting/deploying-your-first-app

Deploy any application to the cloud

## Basic Deployment

```
/monk deploy this project
```

Monk analyzes your code, creates containers, provisions infrastructure, and deploys everything.

→ [Autonomous Deployment](/features/autonomous-deployment)

## Choose a Cloud Provider

```
/monk deploy this to AWS
```

Or GCP, Azure, DigitalOcean - pick your preferred cloud.

→ [Multi-Cloud Support](/features/multi-cloud)

## Specify Region

<img alt="Region selection dropdown menu" />

Choose a specific region for your deployment.

## Full Specification

```
/monk deploy to AWS us-east-1, use RDS for PostgreSQL, put the frontend on Netlify
```

Provide complete preferences upfront to skip questions.

## Analyze Before Deploying

```
/monk analyze this project
```

See what Monk found without deploying yet.

→ [Code Analysis](/features/code-analysis)

***

```
/monk build my project
```

Generate containers and configuration without deploying.

***

```
/monk show me the configuration
```

Review the full system configuration Monk generated.

→ [Configuration & Wiring](/features/configuration-and-wiring)

## What Monk Asks For

**Cloud credentials:**

* AWS access keys
* GCP service account
* Azure credentials
* DigitalOcean API token

→ [How to get cloud credentials](/getting-started/obtaining-credentials)

**Service credentials (if your app uses them):**

* MongoDB Atlas, Redis Cloud, Netlify, Auth0, Vercel, etc.
* Monk requests these when it detects usage in your code

→ [How to get service credentials](/getting-started/obtaining-credentials)

**Deployment choices:**

* Which cloud provider?
* Which region?
* How to deploy databases? (managed vs self-hosted)

## What Happens

1. **Code analysis** - Monk examines your project
2. **Containerization** - Creates Docker containers automatically
3. **Infrastructure provisioning** - Sets up cloud resources (VMs, databases, networking)
4. **Deployment** - Deploys everything and wires it together
5. **Verification** - Checks that everything is healthy

**Timeline:** 5-15 minutes for most applications.

## After Deployment

```
/monk what's running right now?
```

See your deployed application status.

***

```
/monk show me the logs
```

View live logs from your services.

→ [Monitoring](/features/monitoring)

## Next Steps

* [Set Up CI/CD](/prompting/setting-up-cicd) - Auto-deploy on code push
* [Monitor & Debug](/prompting/monitoring-and-debugging) - View logs and troubleshoot
* [Manage Costs](/prompting/managing-costs) - Check spending


# How Prompting Works
Source: https://docs.monk.io/prompting/how-prompting-works

Understanding how to talk to Monk effectively

## Quick Reminder: Talking to Monk

Open the coding agent where the [Monk plugin](/getting-started/get-started) is installed and just start typing — your agent hands infrastructure work to Monk automatically.

## Talk Naturally

Start with `/monk`, then say what you want in natural language — no flags to memorize, no syntax to learn.

**Just say what you want:**

```
/monk deploy this project
/monk show me the logs
/monk how much does this cost?
/monk scale the API server up
```

<img alt="Deploy project with monk" />

**Not this:**

```
monk deploy --target=production --provider=aws
GET /api/logs?service=api&lines=100
```

## Monk Interprets Your Intent

You describe **what** you want, not **how** to do it.

**You say:**

```
/monk deploy this to the cloud
```

**Monk figures out:**

* Analyze the code
* Create containers
* Provision infrastructure
* Deploy services
* Wire everything together

**All the steps are autonomous.** You don't specify them.

## Vague Prompts Work

Don't know all the details? Start vague:

```
You: /monk deploy this application

Monk: I see a React frontend and Node.js API.
      Which cloud provider would you like?
      - AWS
      - GCP
      - Azure
      - DigitalOcean
      - Hetzner

You: AWS

Monk: Which region?

You: us-east-1

Monk: [Proceeds with deployment]
```

**Or be specific upfront:**

```
You: /monk deploy to AWS us-east-1, use RDS for the database

Monk: [Proceeds without questions]
```

**More detail = fewer questions.**

## Monk Works Autonomously

Unlike chatbots that ask permission for everything, Monk executes autonomously.

**Monk doesn't ask:**

* "Should I analyze your package.json?"
* "Should I create a Dockerfile?"
* "Should I configure networking?"

**Monk does ask:**

* **Credentials** - When it needs cloud provider or API credentials
* **Important choices** - Deployment options, cloud provider selection
* **Destructive actions** - Confirmation before deleting resources
* **Clarification** - When requirements are ambiguous

## The Build → Deploy → Adjust Cycle

Monk follows a natural workflow:

### 1. Build

```
You: /monk deploy this project
```

* Monk analyzes your code
* Creates containers
* Generates configuration
* Shows you what will be deployed

### 2. Deploy

```
You: [Approve after reviewing]
```

* Monk provisions infrastructure
* Deploys your application
* Verifies everything works

### 3. Adjust

```
You: /monk show me the logs
     /monk scale up
     /monk add a Redis cache
```

* Monitor and modify as needed
* Changes applied with zero downtime

**Then repeat:** Make code changes, deploy updates, adjust again.

## Answering Monk's Questions

When Monk asks, answer naturally:

**Direct answer:**

```
Monk: Which cloud provider?
You: AWS
```

**Ask Monk to decide:**

```
Monk: Which cloud provider?
You: What do you recommend?
Monk: [Provides recommendation based on your needs]
```

**Provide context:**

```
Monk: How should I deploy the database?
You: We need high availability, budget isn't a concern
Monk: I recommend AWS RDS Multi-AZ for high availability
```

## Secure Credentials

When Monk needs credentials, you'll see secure input prompts:

* Values masked as you type
* Never exposed to the AI
* Stored encrypted on your infrastructure
* Never sent to Monk servers

**You provide credentials once per provider:**

* First time: Monk asks
* Next time: Uses saved credentials

## Common Patterns

**Exploratory** (understand before acting):

```
/monk analyze this project
/monk what will it cost?
/monk show me the configuration
```

**Action** (make something happen):

```
/monk deploy this
/monk set up CI/CD
/monk scale up
/monk migrate to DigitalOcean
```

**Information** (check status):

```
/monk what's running?
/monk show me the logs
/monk how much am I spending?
```

**Troubleshooting** (fix issues):

```
/monk why is the API slow?
/monk users are reporting errors
/monk check the database performance
```

## Next: Prompting Cookbook

The rest of this section is a cookbook - specific tasks with example prompts.

Pick what you want to do:

* [Deploy Your First App](/prompting/deploying-your-first-app)
* [Set Up CI/CD](/prompting/setting-up-cicd)
* [Manage Infrastructure](/prompting/managing-infrastructure)
* [Work with Databases](/prompting/working-with-databases)
* [Scale Resources](/prompting/scaling-resources)
* [Monitor & Debug](/prompting/monitoring-and-debugging)
* [Manage Costs](/prompting/managing-costs)
* [Migrate Between Clouds](/prompting/migrating-between-clouds)
* [Configure Services](/prompting/configuring-services)
* [Troubleshoot Issues](/prompting/troubleshooting)


# Managing Costs
Source: https://docs.monk.io/prompting/managing-costs

Track and optimize infrastructure spending

## Current Cost

```
/monk how much am I spending?
```

Get instant current cost breakdown.

→ [Cost Tracking](/features/cost-tracking)

## Different Time Units

```
/monk how much per day?
```

View costs per second, hour, day, week, or month.

## Project Monthly Cost

```
/monk project the monthly cost
```

Estimate future spending.

## Cost Breakdown

```
/monk show me cost breakdown by service
```

See costs per component.

## Before Changes

```
/monk how much would it cost to add 2 more instances?
```

Estimate cost impact before making changes.

## Compare Clouds

```
/monk how much would this cost on DigitalOcean instead of AWS?
```

Compare costs across providers.

→ [Multi-Cloud Support](/features/multi-cloud)

## Compare Regions

```
/monk which region is cheaper for this workload?
```

Find most cost-effective regions.

## Cost by Project

```
/monk show me costs by project
```

View costs per project (when team features available).

## What Monk Tracks

**Resources:**

* Virtual machines
* Databases
* Storage
* Networking (load balancers, data transfer)
* All cloud services

**Integrations:**

* Managed databases (RDS, Cloud SQL)
* Managed services (Redis Cloud, MongoDB Atlas)
* Third-party APIs

**Accuracy:**

* Real-time pricing data
* Up-to-date rate tables
* Actual resource uptime

## Cost Optimization

**Ask for help:**

```
/monk how can I reduce costs?
/monk what's using the most money?
/monk recommend cheaper alternatives
```

Monk can suggest optimizations.

## Next Steps

* [Managing Infrastructure](/prompting/managing-infrastructure) - Optimize resources
* [Scaling Resources](/prompting/scaling-resources) - Right-size infrastructure
* [Migrating Between Clouds](/prompting/migrating-between-clouds) - Move to cheaper provider


# Managing Infrastructure
Source: https://docs.monk.io/prompting/managing-infrastructure

Provision and manage cloud resources

## Add Virtual Machines

```
/monk add 2 more machines to the API cluster
```

Scale infrastructure by adding VMs.

## Resize Instances

```
/monk scale the database instance up to 8GB RAM
```

Change VM sizes for more resources.

## Add GPU Instances

```
/monk provision a GPU instance for the ML service
```

Add GPU resources for AI/ML workloads.

## Region Recommendations

```
/monk which region should I use for US customers?
```

Get Monk's recommendation for region selection.

→ [Cloud Infrastructure](/features/cloud-provisioning)

## Cost Estimates

```
/monk how much would it cost to add 2 more instances?
```

Estimate cost before making changes.

→ [Cost Tracking](/features/cost-tracking)

## Remove Resources

```
/monk remove the extra VMs, traffic is back to normal
```

<img alt="Delete Resources" />

Scale down when load decreases.

## Compare Clouds

```
/monk how much would this cost on DigitalOcean instead of AWS?
```

Compare infrastructure costs across providers.

## Modify Storage

```
/monk increase database storage to 500GB
```

Adjust disk sizes for databases and volumes.

## What Monk Asks

**Before provisioning:**

* Confirmation of resources to create
* Estimated monthly cost
* Region if not specified

**Credentials:**

* Cloud provider credentials (if not provided previously)

## Next Steps

* [Multi-Cloud Deployments](/prompting/multi-cloud-deployment) - Deploy to AWS, GCP, Azure, DO, Hetzner
* [Scaling Resources](/prompting/scaling-resources) - Scale workloads
* [Managing Costs](/prompting/managing-costs) - Track spending
* [Migrating Between Clouds](/prompting/migrating-between-clouds) - Switch providers


# Migrating Between Clouds
Source: https://docs.monk.io/prompting/migrating-between-clouds

Move applications between cloud providers

## Migrate to Different Cloud

```
/monk migrate this application to DigitalOcean
```

Move your entire application to a different cloud provider.

→ [Workload Migration](/features/workload-migration)

## What Gets Migrated

* ✅ Containerized services
* ✅ Application code
* ✅ Configuration
* ✅ Networking setup
* ⚠️ Database data (coming soon - currently manual)

## Compare Before Migrating

```
/monk how much would this cost on DigitalOcean instead of AWS?
```

Check cost savings before migrating.

→ [Multi-Cloud Support](/features/multi-cloud)

## Partial Migration

```
/monk migrate to DigitalOcean but keep the database on AWS
```

Move some components, keep others where they are.

## What Monk Does

1. **Provisions new infrastructure** - Creates matching resources on target cloud
2. **Deploys workloads** - Starts your application on new cloud
3. **Updates DNS** - Points domain to new infrastructure (if using Monk-managed DNS)
4. **Verifies** - Checks everything works
5. **Cleanup** - Removes old resources after confirmation

## What You Provide

**Credentials:**

* Target cloud provider credentials

**Confirmation:**

* Approve resource provisioning
* Confirm deletion of old resources

## Migration Reasons

**Cost savings:**

```
/monk save 30-60% by switching providers
```

**Better services:**

```
/monk access provider-specific features
```

**Geographic expansion:**

```
/monk reach new regions
```

**Compliance:**

```
/monk meet data residency requirements
```

## Timeline

**Workload migration:** 15-30 minutes for most apps

**Database data migration:** Currently manual (automatic migration coming soon)

## Next Steps

* [Managing Infrastructure](/prompting/managing-infrastructure) - Set up on new cloud
* [Managing Costs](/prompting/managing-costs) - Track savings
* [Monitoring & Debugging](/prompting/monitoring-and-debugging) - Verify migration


# Monitoring & Debugging
Source: https://docs.monk.io/prompting/monitoring-and-debugging

View logs, metrics, and troubleshoot issues

## View Logs

```
/monk show me the API server logs
```

Stream live logs from any service.

→ [Monitoring](/features/monitoring)

## Analyze Logs

```
/monk check the API server logs for errors
```

Monk analyzes logs and finds patterns.

## Shell Access

```
/monk give me shell access to the database server
```

Get direct shell access to any container.

## Check Status

```
/monk what's running right now?
```

See current state of all services.

## Resource Usage

```
/monk what's the resource usage?
```

Check CPU, memory, disk, network for all services.

## Check Specific Service

```
/monk show me the database performance
```

View metrics for a specific service.

## Live Monitoring

```
/monk watch the API server metrics
```

Monitor a service in real-time.

## Service Health

```
/monk are all services healthy?
```

Check health status across your system.

## What Monk Shows

**Logs:**

* Live streaming
* Historical logs
* Filtered by time/severity
* Error highlighting

**Metrics:**

* CPU, memory, disk, network
* Application metrics (queue depth, cache hits)
* Database performance (query times, connections)
* API response times

**System State:**

* Running services
* Container status
* Resource allocation
* Network connections

## Next Steps

* [Troubleshooting Issues](/prompting/troubleshooting) - Fix problems
* [Scaling Resources](/prompting/scaling-resources) - Scale based on metrics
* [Managing Costs](/prompting/managing-costs) - Correlate usage with costs


# Multi-Cloud Deployments
Source: https://docs.monk.io/prompting/multi-cloud-deployment

Deploy across AWS, GCP, Azure, DigitalOcean, Hetzner

## Deploy to AWS

```
/monk deploy this to AWS
```

Monk will ask for region preference and AWS credentials (if not already configured).

**With specific region:**

```
/monk deploy to AWS in us-east-1
```

**With managed database:**

```
/monk deploy to AWS with RDS for PostgreSQL
```

**With MongoDB:**

```
/monk deploy to AWS with DocumentDB for MongoDB
```

→ [AWS Integrations](/integrations/aws-ec2) for all AWS services

## Deploy to Google Cloud

```
/monk deploy to GCP
```

**With region:**

```
/monk deploy to GCP in europe
```

**With Cloud SQL:**

```
/monk use Cloud SQL for PostgreSQL
```

**With Firebase Hosting:**

```
/monk deploy frontend to Firebase
```

→ [GCP Integration](/integrations/gcp) for all GCP services

## Deploy to Microsoft Azure

```
/monk deploy this to Azure
```

**With region:**

```
/monk deploy to Azure in westus2
```

**With Cosmos DB (MongoDB API):**

```
/monk use Azure Cosmos DB with MongoDB API
```

**With Azure Database:**

```
/monk use Azure Database for PostgreSQL
```

## Deploy to DigitalOcean

```
/monk deploy to DigitalOcean
```

**With region:**

```
/monk deploy to DigitalOcean in nyc1
```

**With DO Managed MongoDB:**

```
/monk use DigitalOcean managed MongoDB
```

**With DO Spaces:**

```
/monk use DigitalOcean Spaces for object storage
```

→ [DigitalOcean Integrations](/integrations/digitalocean-agent) for all DO services

## Deploy to Hetzner

```
/monk deploy to Hetzner
```

**With region:**

```
/monk deploy to Hetzner in eu-central
```

**With specific instance type:**

```
/monk deploy to Hetzner on cx22 instances
```

## Hybrid Deployments

Mix cloud providers for optimal placement:

```
/monk deploy frontend to Netlify, backend to AWS, database on Atlas
```

Monk handles cross-cloud networking and configuration automatically.

**Example scenarios:**

**Serverless frontend + containerized backend:**

```
/monk deploy React app to Vercel, API to DigitalOcean
```

**Multi-cloud for redundancy:**

```
/monk deploy primary to AWS, failover to GCP
```

**Cost-optimized stack:**

```
/monk deploy compute to DigitalOcean, database to Atlas, CDN to Cloudflare
```

## Compare Costs Across Clouds

Before deciding, ask Monk to compare:

```
/monk how much would this cost on AWS vs GCP vs Azure?
```

**Monk shows:**

* Cost breakdown per provider
* Monthly estimates
* Differences in pricing
* Which is most cost-effective

```
/monk which cloud is cheapest for this deployment?
```

```
/monk compare DigitalOcean vs AWS for my API
```

## Regional Deployments

### Deploy to Specific Regions

```
/monk deploy to AWS in us-east-1
```

```
/monk deploy to GCP in asia-southeast1
```

```
/monk deploy to Azure in westeurope
```

```
/monk deploy to DigitalOcean in sfo3
```

### Ask for Region Recommendations

Not sure which region to use?

```
/monk which AWS region is cheapest for my app?
```

```
/monk which GCP region is closest to Europe?
```

```
/monk recommend an Azure region for US users
```

**Monk considers:**

* Latency to your users
* Cost differences between regions
* Service availability
* Compliance requirements

### Multi-Region Deployments

Deploy to multiple regions simultaneously:

```
/monk deploy to AWS us-east-1 and eu-west-1
```

```
/monk deploy to GCP in US and Europe
```

**Monk automatically:**

* Provisions infrastructure in each region
* Sets up load balancing across regions
* Configures geo-routing (if applicable)
* Manages cross-region connectivity

## What Monk Manages Per Cloud

### AWS

**Infrastructure:**

* EC2 instances for containers
* VPC and networking
* Security groups
* Load balancers (ALB/NLB)

**Managed Services:**

* RDS (PostgreSQL, MySQL, MariaDB)
* DocumentDB (MongoDB-compatible)
* ElastiCache (Redis)
* S3 (object storage)
* Lambda (serverless functions)
* DynamoDB, SQS, SNS, and more

**Ask Monk:**

```
/monk use AWS Lambda for my API
```

### Google Cloud Platform

**Infrastructure:**

* Compute Engine VMs
* VPC networking
* Firewall rules
* Load balancers

**Managed Services:**

* Cloud SQL (PostgreSQL, MySQL)
* Firestore (NoSQL)
* Memorystore (Redis)
* Cloud Storage (object storage)
* Cloud Functions (serverless)
* BigQuery, Pub/Sub, and more

**Ask Monk:**

```
/monk use GCP Cloud Storage for uploads
```

### Microsoft Azure

**Infrastructure:**

* Virtual Machines
* Virtual Networks
* Network Security Groups
* Load Balancers

**Managed Services:**

* Azure Database (PostgreSQL, MySQL)
* Cosmos DB (MongoDB API, multi-model)
* Azure Cache (Redis)
* Blob Storage (object storage)
* Azure Functions (serverless)
* Event Hubs, Service Bus, and more

**Ask Monk:**

```
/monk use Azure Blob Storage for files
```

### DigitalOcean

**Infrastructure:**

* Droplets (VMs)
* VPC networking
* Firewalls
* Load Balancers

**Managed Services:**

* Managed Databases (PostgreSQL, MySQL, MongoDB, Redis/Valkey)
* Spaces (object storage, S3-compatible)
* App Platform (PaaS)
* Container Registry
* Monitoring

**Ask Monk:**

```
/monk use DigitalOcean App Platform for my frontend
```

## Switching Clouds

Already deployed to one cloud? Migrate to another:

```
/monk migrate this deployment from AWS to GCP
```

**Monk handles:**

1. Provisions equivalent infrastructure on target cloud
2. Updates all configuration and networking
3. Guides you through data migration (databases)
4. Verifies everything works before teardown

```
/monk move from DigitalOcean to Azure
```

```
/monk migrate database from AWS RDS to MongoDB Atlas
```

## Cloud-Specific Considerations

### When to Use AWS

**Best for:**

* Enterprise deployments
* Need for extensive managed services
* Existing AWS infrastructure
* Lambda/serverless requirements

### When to Use GCP

**Best for:**

* Data analytics and BigQuery
* Kubernetes-native deployments
* Machine learning workloads
* Firestore/Firebase integration

### When to Use Azure

**Best for:**

* Microsoft stack (.NET applications)
* Enterprise with existing Azure
* Cosmos DB global distribution
* Azure AD integration

### When to Use DigitalOcean

**Best for:**

* Simpler deployments
* Startups and SMBs
* Cost-conscious projects
* Quick setup without complexity

### Ask Monk for Recommendations

```
/monk which cloud should I use for my project?
```

```
/monk recommend a cloud provider for a Node.js API with PostgreSQL
```

Monk considers your specific needs and recommends appropriately.

## Getting Cloud Credentials

Each cloud provider requires different credentials. Monk will request these automatically when you deploy.

**Need help getting credentials?**

→ See [Obtaining Credentials](/getting-started/obtaining-credentials) for step-by-step guides for all providers:

* [AWS credentials](/getting-started/obtaining-credentials#aws-credentials)
* [GCP credentials](/getting-started/obtaining-credentials#google-cloud-platform-gcp-credentials)
* [Azure credentials](/getting-started/obtaining-credentials#microsoft-azure-credentials)
* [DigitalOcean credentials](/getting-started/obtaining-credentials#digitalocean-credentials)

## Multi-Cloud Best Practices

### Start Simple

Begin with one cloud provider:

```
/monk deploy to DigitalOcean
```

Add additional clouds as needed:

```
/monk also deploy to AWS for redundancy
```

### Use Managed Services Where Available

Let cloud providers handle complexity:

```
/monk use GCP Cloud SQL instead of self-hosted PostgreSQL
```

```
/monk use AWS RDS instead of container database
```

### Co-locate Resources

For best performance and lowest cost, keep related services in the same cloud/region:

**Good:**

```
/monk deploy API to AWS us-east-1 with RDS database in us-east-1
```

**Less optimal:**

```
/monk deploy API to AWS, database on GCP
```

(Cross-cloud latency and data transfer costs)

### Consider Data Transfer Costs

Moving data between clouds is expensive. Ask Monk:

```
/monk how much would data transfer cost between AWS and GCP?
```

## Related Guides

* [Cloud Infrastructure](/features/cloud-provisioning) - How Monk provisions clouds
* [Multi-Cloud Support](/features/multi-cloud) - Multi-cloud capabilities
* [Managing Costs](/prompting/managing-costs) - Compare cloud costs
* [Migrating Between Clouds](/prompting/migrating-between-clouds) - Cloud migration
* [Obtaining Credentials](/getting-started/obtaining-credentials) - Getting cloud credentials


# Scaling Resources
Source: https://docs.monk.io/prompting/scaling-resources

Scale workloads and infrastructure up or down

## Scale Infrastructure

```
/monk add 2 more machines
```

Add VMs to your deployment.

→ [Scaling](/features/scaling)

## Scale Services

```
/monk scale the API server up
```

Increase replicas for a service (workload autoscaling handles this automatically, but you can manually adjust).

## Scale Database

```
/monk increase the database instance to 16GB RAM
```

Resize database resources.

## Adjust Worker Count

```
/monk increase the worker count to 5
```

Scale background workers.

## Scale Down

```
/monk remove the extra VMs, traffic is back to normal
```

Remove resources when load decreases.

## Get Recommendations

```
/monk should I scale up for this traffic?
```

Ask Monk for scaling recommendations.

## Cost Impact

```
/monk how much will it cost to add 2 more instances?
```

Estimate cost before scaling.

→ [Cost Tracking](/features/cost-tracking)

## What Monk Does

**Before scaling:**

* Shows current setup
* Recommends instance types/sizes
* Estimates cost impact
* Asks for confirmation

**During scaling:**

* Provisions new resources
* Deploys containers
* Updates load balancers
* Zero downtime

<img alt="Cloud scaling executed by monk" />

## Automatic Workload Scaling

Monk's algorithmic autoscaler handles container scaling automatically:

* Scales up when CPU/memory is high
* Scales down when load decreases
* No manual intervention needed

**You manually scale:**

* Infrastructure (VMs)
* Databases
* Service settings

## Next Steps

* [Managing Infrastructure](/prompting/managing-infrastructure) - Provision more resources
* [Managing Costs](/prompting/managing-costs) - Track scaling costs
* [Monitoring & Debugging](/prompting/monitoring-and-debugging) - Watch resource usage


# Setting Up CI/CD
Source: https://docs.monk.io/prompting/setting-up-cicd

Auto-deploy when you push code

## Set Up Continuous Deployment

```
/monk set up CI/CD for this project
```

Monk configures GitHub Actions to auto-deploy on every push to main.

→ [Build & CI/CD](/features/build-and-cicd)

## What You Need

* GitHub repository (your project must be in GitHub)
* Already deployed application
* **Optional:** GitHub Personal Access Token (for automatic setup)

## With GitHub PAT (Automatic)

```
You: set up CI/CD

Monk: I'll need a GitHub Personal Access Token to configure this automatically.
      Create one at: https://github.com/settings/tokens

You: [Provides PAT]

Monk: ✓ Created GitHub Actions workflow
      ✓ Injected deployment keys
      ✓ CI/CD ready - push to main to deploy
```

## Without PAT (Manual)

```
You: set up CI/CD

Monk: I've generated the GitHub Actions workflow.
      Please manually add these secrets to your repository:

      [Shows step-by-step instructions]
```

## Deploying Updates

Once CI/CD is set up, simply push code to your main branch:

**Commit and push your changes:**

Your deployment triggers automatically when code reaches the main branch. No need to tell Monk - GitHub Actions handles it.

## Deploy Manually (Alternative)

```
/monk deploy the latest changes
```

Deploy updates without CI/CD.

→ [Updates & Maintenance](/features/updates-and-maintenance)

## Prevent Dependency Upgrades

```
/monk deploy but don't upgrade dependencies
```

Update only your code, keep databases/services at current versions.

## What Gets Auto-Deployed

* **Code changes** - Updated services
* **New services** - Added components
* **Configuration changes** - Environment variables
* **Container updates** - New dependencies

## Smart Rebuilds

Monk only rebuilds what changed:

* Changed frontend → Rebuilds frontend only
* Changed API → Rebuilds API container
* No changes → Skips rebuild

## Next Steps

* [Monitor & Debug](/prompting/monitoring-and-debugging) - Watch deployments
* [Managing Costs](/prompting/managing-costs) - Track CI/CD impact on costs


# Troubleshooting Issues
Source: https://docs.monk.io/prompting/troubleshooting

Diagnose and fix problems

## Report Problems

```
/monk users are reporting errors, investigate
```

<img alt="Deploy project fix by monk" />

Tell Monk about issues - it investigates autonomously.

→ [Monitoring](/features/monitoring)

## Performance Issues

```
/monk why is the API slow?
```

Monk checks code, logs, metrics, and infrastructure to diagnose.

## Application Errors

```
/monk the frontend isn't loading, what's wrong?
```

Troubleshoot specific problems.

## Database Problems

```
/monk check the database performance
```

Analyze database query times and resource usage.

→ [Databases](/features/databases)

## Service Issues

```
/monk the API server keeps crashing
```

Diagnose service failures.

## Network Problems

```
/monk services can't connect to the database
```

Debug connectivity issues.

→ [Networking](/features/networking)

## What Monk Does

**Autonomous investigation:**

1. Reads logs across all services
2. Checks metrics and resource usage
3. Examines workload state
4. Correlates data to find root cause
5. Suggests fixes

**Example:**

```
You: Users reporting 500 errors

Monk: Investigating...

      Found: API server #2 out of memory
      Cause: Memory leak in session handling
      Impact: ~150 active users affected

      Fix: Restart affected instance and scale up

      Should I proceed?
```

## Common Issues

**High CPU/Memory:**

```
/monk what's using all the CPU?
/monk which service is using the most memory?
```

**Connectivity:**

```
/monk can the API reach the database?
/monk test the connection to Redis
```

**Errors:**

```
/monk show me recent errors
/monk filter logs for 500 errors
```

**Performance:**

```
/monk what's causing slow queries?
/monk why is the cache hit rate low?
```

## Get Detailed Info

**Logs:**

```
/monk show me the last 100 lines of API logs
/monk check logs from the past hour
```

**Metrics:**

```
/monk show me resource usage for the past day
/monk compare current vs normal performance
```

**Status:**

```
/monk which services are unhealthy?
/monk show me failed deployments
```

## After Diagnosis

**Apply fixes:**

```
/monk restart the API server
/monk scale up the database
/monk increase worker memory
```

**Code fixes (if deployment-related):**

If Monk identifies a code issue causing deployment problems, it may propose fixes:

```
Monk: The issue is your app reads REDIS_HOST but Monk provides REDIS_URL.
      I can update your code to read from REDIS_URL. Should I fix this?

You: Yes, fix it
```

→ See [Source Code Editing](/features/code-editing) for targeted code fixes

**Verify:**

```
/monk check if the issue is resolved
/monk test the API endpoint
```

## Next Steps

* [Monitoring & Debugging](/prompting/monitoring-and-debugging) - Continuous monitoring
* [Scaling Resources](/prompting/scaling-resources) - Scale to fix capacity issues
* [Configuring Services](/prompting/configuring-services) - Adjust settings


# Setting Up Watcher
Source: https://docs.monk.io/prompting/watcher-setup

Quick-start guide for enabling 24/7 cluster monitoring

## Set Up Watcher

After deploying to a cluster, ask Monk to set up monitoring:

```
/monk set up watcher
```

<img alt="Slack Watcher Configuration" />

Monk shows a configuration form. The defaults work for most clusters. Click **Deploy Watcher** to start.

<Note type="info">
  Watcher is available on the Pro and Team plans.
</Note>

## What Happens

1. Monk deploys the watcher-agent and watcher-ai components to your cluster
2. If you have a Slack webhook configured, alerts are sent there
3. Watcher monitors nodes and containers continuously
4. When issues are detected, AI analyzes them and sends recommendations
5. Each Slack alert includes a **Fix with Monk** button

## Slack Alerts

When prompted, you can configure Slack alerts:

1. Monk opens a browser window where you authorize the Slack webhook
2. You pick a Slack channel for alerts
3. Monk connects everything automatically — no manual webhook URLs needed

If you skip Slack, Watcher still monitors your cluster — you just won't get push notifications.

<Tip>
  Watcher alerts are separate from [Slack remote control](/features/slack). You can use one without the other.
</Tip>

## Example Alerts

**Issue detected:**

<img alt="Slack Watcher Alert Started" />

<img alt="Slack Watcher Alert" />

**Recovery:**

<img alt="Slack Watcher Alert Normalized" />

## Fix with Monk Button

Click **Fix with Monk** in any Slack alert to:

1. Open your coding agent
2. Load the chat or agent panel with full issue context
3. Ask Monk to fix the issue

## Watcher Credits

Watcher is on the Pro and Team plans, and each account starts with 50 watcher credits from the free trial. Only the Watcher's monitoring, diagnosis, and repair cycles consume watcher credits - deploying, chatting with Monk, and everyday operations through the plugin do not. For current pricing, visit [Monk Pricing](https://monk.io/pricing).

## Learn More

→ [Watcher](/features/watcher) - Full configuration options and details
→ [Monitoring & Observability](/features/monitoring) - Log streaming, metrics, troubleshooting


# Working with Databases & Services
Source: https://docs.monk.io/prompting/working-with-databases

Deploy and configure databases, caches, queues

## Deploying with a Database

When deploying an app that uses a database, Monk detects it automatically:

```
/monk deploy this project
```

Monk: "I detected your app uses PostgreSQL. How should I deploy it?"

* Self-hosted (container)
* Cloud-managed (RDS, Cloud SQL)
* Third-party (Neon, Supabase)

→ [Databases](/features/databases)

## Choose Deployment Option

Tell Monk your preference:

```
/monk use MongoDB Atlas instead of self-hosted
```

```
/monk use AWS RDS for PostgreSQL
```

Switch between self-hosted, cloud-managed, or third-party managed.

## Deploying with Redis

If your app uses Redis for caching or sessions, Monk detects it:

```
/monk deploy this project
```

Monk: "I detected Redis. How should I deploy it?"

* Self-hosted (container)
* Redis Cloud (managed)

```
/monk use Redis Cloud instead of self-hosted
```

## Deploying with Message Queues

If your app uses a message queue (RabbitMQ, Kafka, SQS), Monk detects and asks:

```
/monk deploy this project
```

Monk: "Your app uses RabbitMQ. Self-hosted or managed service?"

→ [Essential Services](/features/essential-services)

## Configure Database Settings

```
/monk change the database connection pool size to 20
```

Adjust database configuration.

→ [Configuration & Wiring](/features/configuration-and-wiring)

## Resize Database

```
/monk increase database RAM to 16GB
```

Scale database resources.

## Add Object Storage

```
/monk add S3 for file uploads
```

Add object storage for files and assets.

## Backup Database

```
/monk back up my database
```

Create on-demand backups of your database.

```
/monk show me available backups
```

List all database backups and snapshots.

→ [Backup & Restore Guide](/prompting/backup-and-restore)

## What Monk Asks

**Deployment choice:**

* Self-hosted in container?
* Cloud-managed (RDS, Cloud SQL)?
* Third-party (MongoDB Atlas, Redis Cloud)?

**Credentials:**

* For managed services: Provider credentials
* For third-party: Service API keys

→ [Obtaining Credentials](/getting-started/obtaining-credentials) for setup guides

## Database Options

**Relational:**

* PostgreSQL
* MySQL
* MariaDB

**NoSQL:**

* MongoDB ([deployment guide](/integration-guides/mongodb-deployment-guide))
* Redis
* Cassandra

**Others:**

* Elasticsearch
* TimescaleDB
* And 20+ more

→ [See all supported databases](/features/databases)

## Next Steps

* [Configuring Services](/prompting/configuring-services) - Adjust settings
* [Monitoring & Debugging](/prompting/monitoring-and-debugging) - Check database performance
* [Managing Costs](/prompting/managing-costs) - Track database costs