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

> Master OpenShip deployment modes with DEPLOY_MODE and CLOUD_MODE. Learn how these environment variables control self-hosted SaaS or desktop client operations.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: how-to-guide
- Published: 2026-07-30

---

**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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/apps/api/src/config/env.ts)**. The implementation parses the environment and derives a `TARGET` constant:

```typescript
// 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:

```bash

# Self-hosted instance using Docker runtime

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

npm start

```

```bash

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

export CLOUD_MODE=true
npm start

```

```bash

# Launch the desktop client

export DEPLOY_MODE=desktop
npm run desktop

```

Access these values programmatically through the environment configuration:

```typescript
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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/adapters/docs/ARCHITECTURE.md) respectively.