Fix: ElizaOS Docker Compose Environment Variable Coinbase Plugin Crash

If your ElizaOS trading agent crashes during initialization inside a Docker container, specifically targeting the Coinbase plugin, the failure is likely rooted in malformed environment variable parsing. This results in session drops or “API Key not found” errors even when the keys are present in the .env file.

Diagnostic Error Log

[ELIZA] Critical: Coinbase SDK initialization failed. 
[ELIZA] Error: Missing or malformed COINBASE_API_KEY.
[ELIZA] Stack: TypeError [ERR_INVALID_ARG_TYPE]: The "key" argument must be of type string.

Corrected docker-compose.yml Configuration: To resolve this, you must ensure that the shell environment within the container receives the literal string without interpolation interference. Use the following structure:

services:
  eliza-agent:
    image: elizaos/runtime:latest
    env_file: .env
    environment:
      - COINBASE_API_KEY=${COINBASE_API_KEY}
      - COINBASE_API_SECRET=${COINBASE_API_SECRET}
      # Use single quotes for raw hex strings to prevent parsing errors
      - EVM_PRIVATE_KEY='0x1234567890abcdef...'
      # Double dollar signs to escape interpolation in secrets
      - WALLET_SECRET_SALT='$$2b$$12$$...'
    restart: always

Architectural Context: Docker Interpolation vs. Node Runtime Parsers

The conflict arises from the multi-layered parsing of environment variables. First, the Docker Compose binary evaluates the YAML file and interpolates variables from your shell or .env. Second, the Node.js runtime inside the container accesses these variables via process.env. This dual-pass evaluation is where most “silent” failures occur.

When Docker Compose parses a ${VARIABLE}, it looks for that variable in the host’s environment. If the variable contains special characters (e.g., #, $, &), and isn’t properly escaped in the .env file, Docker may truncate the value or attempt to resolve it as a sub-variable. For AI agents like ElizaOS, which rely heavily on long hexadecimal strings for EVM private keys or Base64-encoded API secrets for Coinbase, even a single character mismatch triggers a cryptographic failure.

In the Node.js environment, libraries like ethers or viem are typically used to initialize the wallet interface. These libraries perform strict validation on the privateKey string. For example, ethers.Wallet expects a 64-character hex string (excluding the 0x prefix). If Docker’s interpolation removes a trailing character or misinterprets a symbol, ethers will throw a hex data length mismatch error. Because ElizaOS plugins often wrap these calls in high-level abstractions, the developer only sees a generic “Plugin failed to load” message, masking the underlying environment corruption.

Furthermore, the Coinbase SDK utilizes HmacSHA256 or JWT-based authentication. If the COINBASE_API_SECRET is passed as a string but contains an unescaped dollar sign, the internal cryptographic handshake will sign the message with the interpolated string (the value of the non-existent variable) rather than the literal secret. This results in an Unauthorized response from the Coinbase API, leading the agent to assume the service is down or the keys are invalid.

The musl vs. glibc Factor

Another architectural nuance involves the base image used for the Docker container. Alpine-based images use musl libc, while Debian-based images use glibc. There are subtle differences in how environment variables are handled at the kernel level between these two libraries. Specifically, musl has a more restrictive limit on the total size of the environment block. If an ElizaOS agent is loaded with dozens of plugins (each with its own set of keys), the environment block may exceed these limits, leading to truncated variables at the end of the list.

Preventative Maintenance: Production Key Isolation and Validation

For institutional-grade deployments, relying on plain text .env mappings is an unacceptable security risk. You should migrate to a tiered security approach that combines environment validation with secure secret mounting.

1. Zod-Powered Environment Schema

Before ElizaOS even attempts to load a plugin, your runtime should validate the shape of the environment. Implementing a Zod schema ensures that malformed Docker interpolations are caught at the very first line of execution.

// src/config/env.ts
import { z } from 'zod';

const envSchema = z.object({
  COINBASE_API_KEY: z.string().min(10).max(100),
  COINBASE_API_SECRET: z.string().min(20),
  EVM_PRIVATE_KEY: z.string().regex(/^0x[a-fA-F0-9]{64}$/, "Invalid Hex Format"),
  NODE_ENV: z.enum(['development', 'production', 'test']),
});

export const ENV = envSchema.parse(process.env);

2. Implementing Docker Secrets

Docker Secrets are more secure than environment variables because they are never logged to the container’s metadata and are mounted as temporary files in an in-memory tmpfs.

Modified docker-compose.yml for Secrets:

services:
  eliza-agent:
    image: elizaos/runtime:latest
    secrets:
      - coinbase_api_key
      - coinbase_api_secret
    environment:
      - COINBASE_SECRET_PATH=/run/secrets/coinbase_api_secret

secrets:
  coinbase_api_key:
    file: ./secrets/cb_key.txt
  coinbase_api_secret:
    file: ./secrets/cb_secret.txt

3. Pre-Start Validation Script (entrypoint.sh)

Add a shell script to your Docker image that verifies the presence and integrity of keys before the Node process starts. This prevents the “crash loop” by failing fast with a clear error message.

#!/bin/sh
# entrypoint.sh

echo "Validating environment for ElizaOS..."

if [ -z "$COINBASE_API_KEY" ]; then
  echo "CRITICAL: COINBASE_API_KEY is unset."
  exit 1
fi

if [[ ! "$EVM_PRIVATE_KEY" =~ ^0x[a-fA-F0-9]{64}$ ]]; then
  echo "CRITICAL: EVM_PRIVATE_KEY is malformed (Interpolation Error?)."
  exit 1
fi

exec node dist/index.js

4. Security Policies for Trading Agents

When deploying AI agents with financial signing authority, implement these three mandatory policies:

• Network Isolation: Use Docker’s internal networks to prevent the agent container from being reachable from the public internet. Only the agent should initiate outbound connections to the Coinbase API.
• Resource Constraints: Limit the CPU and RAM of the agent. This prevents a “runaway” agent (due to a bug or exploit) from consuming host resources or performing high-frequency trades that drain the wallet.
• Read-Only Root Filesystem: Run the container with read_only: true. This prevents an attacker who might compromise the ElizaOS process from installing persistent malware or modifying the agent’s logic.

Advanced FAQ Layer

Q1: Why does Docker Compose sometimes ignore my updated .env file? Docker Compose caches the environment state. If you update your .env file, simply running docker-compose up might not pick up the changes if the container is already running. You must run docker-compose up -d --force-recreate or manually restart the services to ensure the interpolation logic re-reads the file and applies the new strings to the container environment.

Q2: Can I use JSON.parse to handle complex objects in Docker environment variables? While possible, it is highly discouraged. Passing JSON through the shell requires double-escaping quotes (\"), which is extremely error-prone. Instead, use a single environment variable pointing to a mounted configuration file (CONFIG_PATH=/app/config.json). This allows you to use standard JSON/YAML editors with syntax highlighting, avoiding the “quoted string within a quoted string” nightmare of Docker Compose.

Q3: How does ElizaOS handle secrets when scaling with Docker Swarm or Kubernetes? In orchestrated environments, you should use the native secret management systems (K8s Secrets or Swarm Secrets). ElizaOS supports a “Secret Provider” abstraction where it can fetch keys from an external API (like AWS Secrets Manager) instead of reading from process.env. This is the preferred method for multi-agent clusters where keys need to be rotated without redeploying the entire container stack.