Skip to main content
MOAT
Reference

Environment variables

This page documents environment variables used to configure Moat and variables injected into containers.

Moat configuration

These variables configure Moat itself. Set them in your shell profile or before running Moat commands.

ANTHROPIC_API_KEY

Anthropic API key. Used by moat grant anthropic as an alternative to Claude Code OAuth.

export ANTHROPIC_API_KEY="sk-ant-api..."

When set, moat grant anthropic uses this key instead of prompting.

SSH_AUTH_SOCK

Path to SSH agent socket. Required for moat grant ssh.

Set automatically by SSH agent. Start one with eval "$(ssh-agent -s)" and ssh-add if not running.

MOAT_PROXY_PORT

Override default routing proxy port.

export MOAT_PROXY_PORT="9000"
  • Default: 8080
  • Ports below 1024 require elevated privileges on macOS/Linux (e.g., sudo moat run for port 80)

MOAT_RUNTIME

Force a specific container runtime instead of auto-detection.

export MOAT_RUNTIME=docker  # Force Docker runtime
export MOAT_RUNTIME=apple   # Force Apple containers runtime
  • Default: Auto-detect (Apple containers on macOS 26+ with Apple Silicon, Docker otherwise)
  • When the requested runtime is unavailable, Moat returns an error

See Runtimes for details on runtime selection.

BUILDKIT_HOST

Enable BuildKit for image builds. When set, Moat generates Dockerfiles with BuildKit-specific features like --mount=type=cache for faster apt installs.

export BUILDKIT_HOST=docker-container://buildkitd
  • Default: BuildKit disabled (legacy builder compatibility)
  • Set this to a BuildKit daemon address to enable BuildKit features
  • BuildKit builds are faster and support layer caching

MOAT_DISABLE_BUILDKIT

Force-disable BuildKit even when BUILDKIT_HOST is set.

export MOAT_DISABLE_BUILDKIT=1
  • Only meaningful when BUILDKIT_HOST is also set
  • Use this to temporarily fall back to legacy-compatible Dockerfiles without unsetting BUILDKIT_HOST

See Runtimes for BuildKit configuration.

MOAT_NO_SANDBOX

Disable gVisor sandbox for Docker containers on Linux.

export MOAT_NO_SANDBOX=1
  • Default: gVisor sandbox enabled on Linux, disabled on macOS/Windows (not supported)
  • gVisor provides additional isolation by intercepting syscalls
  • Disable if gVisor is unavailable or incompatible with your workload

See Sandboxing for security implications.

MOAT_PROFILE

Selects the credential profile for all grant and run commands. The --profile flag overrides this variable when both are set.

export MOAT_PROFILE=work
moat grant github        # Stored in work profile
moat run --grant github  # Uses work profile credential
  • Default: empty (uses default credential store at ~/.moat/credentials/)
  • Profile credentials are stored in ~/.moat/credentials/profiles/<name>/

See Credential profiles for details.

MOAT_WORKTREE_BASE

Override the default worktree base path (~/.moat/worktrees/).

AWS credentials

For AWS SSM secrets, standard AWS environment variables are used:

export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

Or configure via aws configure.

Container environment

These variables are injected into containers by Moat.

HTTP_PROXY / HTTPS_PROXY

Proxy URL for credential injection.

# Inside container:
echo $HTTP_PROXY
# http://127.0.0.1:54321

echo $HTTPS_PROXY
# http://127.0.0.1:54321

All HTTP/HTTPS traffic routes through this proxy for credential injection and network policy enforcement.

Note: On Apple containers (macOS 26+), the proxy URL includes a per-run authentication token: http://moat:<token>@<host>:<port>. The token is generated automatically and is different for each run. See Proxy architecture for details on the security model.

NO_PROXY

Hosts that bypass the proxy.

# Inside container:
echo $NO_PROXY
# localhost,127.0.0.1

Local addresses are excluded from proxying.

MOAT_URL_*

Endpoint URLs for hostname routing. One variable per endpoint defined in ports.

# moat.yaml
ports:
  web: 3000
  api: 8080
# Inside container:
echo $MOAT_URL_WEB
# http://web.my-agent.localhost:8080

echo $MOAT_URL_API
# http://api.my-agent.localhost:8080

Use these for inter-endpoint communication or OAuth callback URLs.

MOAT_RUN_ID

Unique identifier for the current run.

# Inside container:
echo $MOAT_RUN_ID
# run_a1b2c3d4e5f6

MOAT_RUN_NAME

Name of the current run.

# Inside container:
echo $MOAT_RUN_NAME
# my-agent

User-defined environment

Variables from env in moat.yaml or -e CLI flag:

# moat.yaml
env:
  NODE_ENV: development
  DEBUG: "true"
# Inside container:
echo $NODE_ENV
# development

echo $DEBUG
# true

Resolved secrets

Variables from secrets in moat.yaml:

# moat.yaml
secrets:
  OPENAI_API_KEY: op://Dev/OpenAI/api-key
# Inside container:
echo $OPENAI_API_KEY
# sk-... (resolved value)

Variable precedence

When the same variable is defined in multiple places:

  1. CLI -e flag (highest priority)
  2. secrets in moat.yaml
  3. env in moat.yaml
  4. Moat-injected variables (HTTP_PROXY, etc.)
  5. Base image defaults (lowest priority)

Security notes

Visible to all processes

Environment variables are visible to all processes in the container. Any process can read them via:

  • env command
  • /proc/*/environ
  • Language-specific environment APIs

Do not use for sensitive credentials

For sensitive credentials like OAuth tokens, use grants instead of environment variables. Grants inject credentials at the network layer where they’re not visible in the environment. See Security model for a full discussion of credential safety.

# Prefer: Network-layer injection
grants:
  - github

# Avoid for sensitive data: Environment variable
secrets:
  GITHUB_TOKEN: op://Dev/GitHub/token

Audit logging

Secret resolution is logged in the audit trail (which secrets were resolved, not their values). Environment variable usage is not logged.