How Environment Variables Control Deployment Mode in OpenShip: DEPLOY_MODE and CLOUD_MODE Explained

OpenShip uses two environment variables, DEPLOY_MODE and CLOUD_MODE, to determine whether the application runs as a self-hosted instance, a SaaS cloud service, or a desktop client.

The oblien/openship repository relies on these variables early in the boot process to configure runtime targets and feature availability. Understanding how DEPLOY_MODE and CLOUD_MODE interact is essential for developers deploying OpenShip in different environments.

Understanding DEPLOY_MODE: Runtime and Target Selection

The DEPLOY_MODE variable selects both the runtime and target environment for self-hosted instances. According to the configuration logic in apps/api/src/config/env.ts, this variable accepts four possible values:

• docker – Runs the application locally using containerization.
• bare – Runs the application locally without containers.
• cloud – Forces the Oblien runtime to target the SaaS cloud environment.
• desktop – Launches the desktop client without an internal server.

When set to docker or bare, OpenShip operates as a self-hosted instance. Setting it to cloud shifts the target to the SaaS cloud, while desktop activates the desktop client mode.

How CLOUD_MODE Overrides Deployment Behavior

The CLOUD_MODE variable acts as a boolean override that forces the instance to behave as the OpenShip SaaS cloud, regardless of other settings. When set to true, the code path treats the process as a cloud instance, mounting cloud-only routes and disabling self-hosted features.

If omitted or set to false, the instance defers to DEPLOY_MODE for determining the deployment target. This provides a clear separation between self-hosted deployments and managed cloud instances.

The Configuration Logic in env.ts

The evaluation of these variables happens early in the boot process within apps/api/src/config/env.ts. The implementation parses the environment and derives a TARGET constant:

// From apps/api/src/config/env.ts
export const CLOUD_MODE = process.env.CLOUD_MODE === "true";
export const DEPLOY_MODE = process.env.DEPLOY_MODE ?? "docker";

export const TARGET = CLOUD_MODE || DEPLOY_MODE === "cloud"
  ? "cloud"
  : DEPLOY_MODE === "desktop"
    ? "desktop"
    : "selfhosted";

This logic follows a specific precedence:

1. If CLOUD_MODE=true or DEPLOY_MODE=cloud, the target becomes cloud.
2. If DEPLOY_MODE=desktop, the target becomes desktop regardless of CLOUD_MODE.
3. All other configurations default to selfhosted, using the selected runtime.

Practical Configuration Examples

Configure these variables before starting the application to control the deployment mode:

# Self-hosted instance using Docker runtime

export DEPLOY_MODE=docker
export CLOUD_MODE=false   # optional – defaults to false

npm start

# Force SaaS cloud target (even on a self-hosted server)

export CLOUD_MODE=true
npm start

# Launch the desktop client

export DEPLOY_MODE=desktop
npm run desktop

Access these values programmatically through the environment configuration:

import { env } from "./config/env";

if (env.CLOUD_MODE) {
  console.log("Running in SaaS cloud mode");
}
console.log(`Deploy mode is ${env.DEPLOY_MODE}`);

Where These Variables Impact the Codebase

These environment variables control feature gates throughout the repository:

• Cloud-only routes in apps/api/src/modules/health/health.routes.ts mount only when CLOUD_MODE evaluates to true.
• Desktop-specific endpoints in apps/api/src/modules/auth/auth.routes.ts check DEPLOY_MODE === "desktop" to conditionally enable features.
• Runtime selection logic is documented in packages/adapters/docs/ARCHITECTURE.md, which explains the relationship between deployment variables and Oblien runtime targets.
• Default values appear in .env.example at the repository root.

Summary

• DEPLOY_MODE accepts docker, bare, cloud, or desktop to set the runtime and target environment.
• CLOUD_MODE accepts true or false and overrides DEPLOY_MODE to force SaaS cloud behavior when true.
• The TARGET derivation in apps/api/src/config/env.ts prioritizes cloud mode, then desktop mode, defaulting to self-hosted.
• Cloud-only routes and desktop features are gated by these variables in the health and auth modules.

Frequently Asked Questions

What values can DEPLOY_MODE accept?

The DEPLOY_MODE variable supports four values: docker and bare for self-hosted local instances, cloud for targeting the SaaS environment, and desktop for running the desktop client. The default value is docker when the variable is unset, as defined in apps/api/src/config/env.ts.

Does CLOUD_MODE override DEPLOY_MODE?

Yes. When CLOUD_MODE is set to true, it overrides any DEPLOY_MODE setting and forces the application to run as a SaaS cloud instance. This behavior is implemented in apps/api/src/config/env.ts where CLOUD_MODE is evaluated first in the TARGET conditional.

How do I run OpenShip as a desktop application?

Set DEPLOY_MODE=desktop before starting the application. This configuration disables the internal server and activates desktop-specific endpoints. Note that DEPLOY_MODE=desktop takes precedence over CLOUD_MODE, meaning the desktop target is selected even if cloud mode is enabled.

Where are these variables defined in the source code?

The primary definitions and parsing logic reside in apps/api/src/config/env.ts, where the environment is read and exported as constants. Default examples and documentation appear in .env.example and packages/adapters/docs/ARCHITECTURE.md respectively.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}