> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploxy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> A deep dive into the .deploxy.json file, managing environment variables, regional settings, and other advanced deployment configurations.

## The `.deploxy.json` File

This file is the primary configuration for your Deploxy project. It instructs the Deploxy CLI on how to deploy and manage your MCP server.

### Basic Structure

Here is a comprehensive example of the `.deploxy.json` file with commonly used options:

```json theme={null}
{
  "authToken": "YOUR_DEPLOXY_TOKEN",
  "defaultDeployRegion": "us-east-1",
  "stdioArgsIndex": "--args",
  "packageType": "js",
  "nodejsRuntime": "nodejs22x",
  "memorySizeMB": 256,
  "injectedEnv": {
    "NODE_ENV": "production",
    "DATABASE_URL": "YOUR_DATABASE_URL",
    "STRIPE_API_KEY": "YOUR_SECRET_KEY"
  },
  "packageManager": {
    "manager": "npm",
    "installCommand": "npm install --production"
  }
}
```

### Key Properties

* **`authToken`** (required): Your Access Token from the [Tokens page](https://deploxy.com/account/settings/tokens).
* **`defaultDeployRegion`** (required): The primary AWS region for deployment. See [Regional Configuration](#regional-configuration).
* **`stdioArgsIndex`** (optional): A delimiter for command-line arguments. Defaults to `--args`. See [Distinguishing Arguments with `stdioArgsIndex`](#distinguishing-arguments-with-stdioargsindex).
* **`packageType`** (required): Specifies the package type. Currently, only `"js"` (JavaScript/TypeScript) is supported.
* **`nodejsRuntime`** (optional): Specifies the Node.js runtime for your serverless function (e.g., `"nodejs22x"`). Defaults to `"nodejs22x"`.
* **`memorySizeMB`** (optional): Defines the memory allocation for your serverless function in megabytes. This setting affects billing; for details, refer to our [Pricing documentation](/resources/pricing). Defaults to `256`.
* **`injectedEnv`** (optional): Securely provides environment variables to your server. See [Secure Environment Management with `injectedEnv`](#secure-environment-management-with-injectedenv).
* **`packageManager`** (optional): Specifies the package manager (`npm`, `pnpm`, `yarn`). Defaults to `npm`. See [Package Manager Configuration](#package-manager-configuration).

## Environment variables using `injectedEnv`

The `injectedEnv` property is the primary method for securely providing environment variables to your MCP server. These variables are injected into your serverless environment during deployment and are never exposed to the end-user's client.

<Warning title="Important Security Practice">
  The `.deploxy.json` file often contains sensitive data like API keys. To prevent it from being committed to version control, you **must** add this file to your `.gitignore`.
</Warning>

All values in the `injectedEnv` object must be **strings**. These values are read from your `.deploxy.json` file at deployment time and made available inside your server code via `process.env`.

### Value Types and Parsing

By convention, all environment variable values are treated as strings. To handle complex data types like objects or arrays, you must first serialize them into a JSON string. Your server-side code is then responsible for parsing these strings back into their original data types.

#### Examples

<CodeGroup>
  ```json .deploxy.json - Correct ✅ theme={null}
  {
    "injectedEnv": {
      "ENABLE_FEATURE_X": "true",
      "API_TIMEOUT_MS": "30000",
      "CONFIG_JSON": "{\"key\":\"value\",\"nested\":true}"
    }
  }
  ```

  ```json .deploxy.json - Incorrect ❌ theme={null}
  {
    "injectedEnv": {
      "ENABLE_FEATURE_X": true,
      "API_TIMEOUT_MS": 30000,
      "CONFIG_JSON": {
        "key": "value",
        "nested": true
      }
    }
  }
  ```

  ```typescript Usage example theme={null}
  // In your server code, parse the string values:
  const featureXEnabled = process.env.ENABLE_FEATURE_X === 'true';
  const timeout = parseInt(process.env.API_TIMEOUT_MS, 10);
  const config = JSON.parse(process.env.CONFIG_JSON);
  ```
</CodeGroup>

## Regional Configuration

The `defaultDeployRegion` sets the primary deployment location for your server. For end-users on the Free Plan, all operations are routed to this region unless they specify a different one using the `--region` flag. This routing behavior does not apply to Pay-As-You-Go plans.

### Available Regions

Deploxy supports deployment to a wide range of global regions. For a complete, up-to-date list of all supported regions and their identifiers, please see the [Available Regions](/resources/regions) documentation.

## End-User args with `stdioArgsIndex`

This property acts as a delimiter to distinguish between arguments intended for the Deploxy platform and those for your MCP server. This is crucial for preventing conflicts between Deploxy's internal flags (like `--region`) and your server's custom parameters.

Deploxy processes all command-line arguments up to the `stdioArgsIndex` value. Any arguments appearing after this delimiter are passed directly to your Stdio MCP server's `process.argv` array.

<Warning title="Argument Order is Critical">
  The `stdioArgsIndex` delimiter and any arguments intended for your MCP server **must** come after all Deploxy-specific arguments.

  For instance, if you place a flag like `--region` after the `stdioArgsIndex` delimiter, it will not be interpreted by Deploxy. Instead, it will be passed directly to your server's `process.argv` array. This is the expected behavior, so always ensure your command-line arguments are ordered correctly.
</Warning>

### Configuration Example

You define the delimiter in your `.deploxy.json` file. The default is `--args`.

```json .deploxy.json theme={null}
{
  "stdioArgsIndex": "--args"
}
```

### End-User Usage Examples

Here is how an end-user's client would pass arguments to your MCP server.

<CodeGroup>
  ```bash NPX theme={null}
  # When a user runs this command:
  npx -y @your/mcp --region us-east-1 --args user-custom-key user-token

  # Deploxy handles --region us-east-1
  # Your server receives ["user-custom-key", "user-token"] in process.argv
  ```

  ```json Use case 1 theme={null}
  // Your MCP server receives
  // ["user-custom-key", "user-token"] in process.argv
  {
    "mcpServers": {
      "your-mcp-server": {
        "command": "npx",
        "args": [
          "-y",
          "@your/mcp",
          "--region",
          "us-east-1",
          "--args",
          "user-custom-key",
          "user-token"
        ]
      }
    }
  }
  ```

  ```json Use case 2 theme={null}
  // Your MCP server receives
  // [] in process.argv
  {
    "mcpServers": {
      "your-mcp-server": {
        "command": "npx",
        "args": [
          "-y",
          "@your/mcp",
          "--region",
          "us-east-1"
        ]
      }
    }
  }
  ```
</CodeGroup>

## Package Manager Configuration

You can specify which package manager Deploxy should use to install your project's dependencies on the server. The following examples show how to configure `npm`, `pnpm`, and `yarn`. If this property is not set, `npm` is used by default.

<CodeGroup>
  ```json .deploxy.json (npm) theme={null}
  {
    "packageManager": {
      "manager": "npm",
      "installCommand": "npm install --production"
    }
  }
  ```

  ```json .deploxy.json (pnpm) theme={null}
  {
    "packageManager": {
      "manager": "pnpm",
      "installCommand": "pnpm install --prod"
    }
  }
  ```

  ```json .deploxy.json (yarn) theme={null}
  {
    "packageManager": {
      "manager": "yarn",
      "installCommand": "yarn install --production"
    }
  }
  ```
</CodeGroup>