DOCSEARCHbyAlgolia
Submit Docs

Miren Documentation

website·Indexed 31 days ago

https://miren.md

Documentation for Miren, a platform for deploying applications with managed addons and services. Covers app.toml configuration, addon lifecycle (including PostgreSQL, MySQL, and SQLite), the JSON-RPC 2.0 admin interface, and agent skills for AI-driven deployment and health checks.

Tokens
255.3K
Snippets
2K
Records
2.7K
Agent score
59%

What's inside Miren

  1. Overview of Miren Cloud control plane

    Miren Cloud serves as a central control plane designed to connect and manage Miren clusters. It provides integrated capabilities for team management, access control, and the orchestration of multi-environment workflows.

  2. Overview of Miren Sandbox management

    Sandboxes in Miren serve as the underlying execution environments for applications. While most development tasks are performed directly through application-level commands, sandbox management commands are available for debugging and advanced infrastructure use cases.

  3. Overview of self-hosting a Headscale control server on Miren

    Headscale is an open-source implementation of the Tailscale control server. It serves as the coordination plane where Tailscale clients log in, exchange keys, and retrieve their network maps. Self-hosting Headscale on Miren allows you to maintain full ownership of your tailnet's coordination plane, ensuring the database and keys persist across redeployments and are accessible via a custom hostname over HTTPS.

  4. Understand the role of Miren Cloud in self-hosted Miren deployments

    Miren can be installed on a private server as a standalone instance, providing full ownership of the infrastructure. However, standalone installations act as isolated 'islands' where apps are only reachable within the local network and the user is solely responsible for backups and management. Miren Cloud serves as an optional 'connective tissue' that sits alongside existing clusters to provide shared services and infrastructure utilities that are typically difficult to build manually, without taking over the user's primary infrastructure.

  5. Expose local clusters to the internet with Miren Anywhere

    Miren Anywhere allows clusters running on home networks, laptops, or locked-down VPCs to make applications public without requiring a public IP, static address, dynamic DNS, or inbound firewall rules (port forwarding). The cluster establishes an outbound connection to Miren Cloud, which then routes inbound edge traffic back through that established path to the cluster.

  6. Understand Miren identity anchors for federation

    Miren uses 'anchors' to determine who serves the public keys used to verify workload identity tokens. The signing key always remains on the cluster (<data_path>/server/workload-identity.key) and is never uploaded to Miren Cloud.

    There are two anchor types:

    1. Cluster Anchor: The cluster's own ingress serves discovery. The iss claim is the cluster's hostname (e.g., https://cluster-abc.miren.systems). Use this for air-gapped or self-managed environments.
    2. Cloud Anchor: Miren Cloud serves discovery using keys published by the cluster. The iss claim is https://api.miren.cloud/identity/<cluster-id>. This is the default for clusters registered with Miren Cloud and is required for clusters not reachable from the public internet (e.g., behind carrier NAT) or to ensure discovery availability during cluster downtime.

  8. Manage Miren runner fleet health and status

    Use the runner subcommands to monitor the health and configuration of your registered nodes. runner list provides an overview of every registered node and its current health, while runner status provides detailed health and configuration reports for a specific single runner.
    runner list
runner status <runner-id>

  9. Manage service instances using the Miren Sandbox Pool

    The Sandbox Pool is a controller responsible for managing the set of instances for a specific service within a version. It tracks and reconciles the desired, current, and ready instance counts based on the service's concurrency configuration. You can view the status of sandbox pools using the miren sandbox-pool list command.
    miren sandbox-pool list

  10. Understand Miren Cloud connectivity and tunnel establishment

    Miren Cloud enables connectivity to clusters that cannot be dialed directly (e.g., those behind carrier-grade NAT) using a multi-step handshake process:

    1. Persistent Connection: The miren server maintains a long-lived WebSocket connection to miren.cloud for signaling.
    2. Request Trigger: When a request for a registered hostname hits a Point of Presence (POP) where the cluster is not yet connected, the POP holds the request and asks Miren Cloud to wake the cluster.
    3. Token Relay: Miren Cloud relays a wake-up signal and a one-time token to the cluster via the existing WebSocket connection.
    4. Tunnel Establishment: The cluster dials the POP directly over QUIC (HTTP/3) and presents the token. The POP uses this token—rather than the IP address—to identify and register the correct cluster.
    5. Traffic Forwarding: Once the encrypted tunnel is established, the held request is forwarded, and subsequent requests for those hostnames are routed through the tunnel.

  11. Understand Miren's non-HTTP traffic routing

    Non-HTTP traffic is managed at the kernel level using nftables NAT rules. When a service with non-HTTP ports is deployed, Miren assigns it an internal IP and configures firewall rules to forward traffic based on port and protocol to the active sandboxes. These rules are dynamically updated during scaling events to provide load-balancing across available endpoints.

  12. Use Miren Disk for persistent application storage

    Miren Disk provides persistent storage attached to an application. Because these disks survive both restarts and redeployments, they are the recommended storage solution for databases and other stateful workloads.