Docker

How do I run Areev in Docker?

Mount a host volume to /data and pass configuration through environment variables to start a persistent Areev container.

Areev is a context database that stores AI memory as encrypted, governance-aware grains. The Docker image ships a single static Rust binary — no runtime dependencies, no JVM, no interpreter. Because all autonomous memory operations (write, recall, forget) modify the Fjall LSM data directory, you must mount a volume; without one, data is lost when the container stops. The container exposes port 4011 for HTTP and 50051 for gRPC.

The serve command combines create-or-open behavior: it creates the database if it does not exist, or opens an existing one. Policy is sealed at creation time and persists across restarts. Pass --mcp and --a2a to enable the Model Context Protocol and Agent-to-Agent protocol endpoints alongside HTTP.

# Pull and run with persistent storage
docker run -d \
  --name areev \
  -p 4011:4011 \
  -v areev-data:/data \
  -e AREEV_MASTER_KEY=your-256-bit-hex-key \
  areev/areev:latest \
  --policy gdpr serve --http 0.0.0.0:4011

# With all protocols and gRPC
docker run -d \
  --name areev \
  -p 4011:4011 -p 50051:50051 \
  -v areev-data:/data \
  -e AREEV_MASTER_KEY=your-256-bit-hex-key \
  areev/areev:node \
  --policy gdpr serve --http 0.0.0.0:4011 --grpc 0.0.0.0:50051 --mcp --a2a

What build profiles does the Dockerfile support?

Areev provides five build profiles that control which features are compiled into the binary.

Each profile produces a different binary size and capability set. The edge profile is the most minimal, including FTS, HTTP, auth, CAL, import, and operational metrics for IoT or embedded deployments. The dev profile (the default) includes FTS, HTTP, gRPC, MCP, A2A, app UI, import, CAL, chat, hooks, auth, vector search, and metrics — everything needed for local development. The node profile enables every feature for self-hosted production including signing, vault, KMS, PII detection, and metrics export. The cluster profile adds distributed Raft consensus and OpenTelemetry to node. The cloud profile adds billing metrics and pilot-managed identity to cluster.

Use Dockerfile.dev for local development — it performs a self-contained build without requiring the CI builder image. Use Dockerfile for CI/CD production builds (defaults to cloud profile). Both accept a PROFILE build argument.

# Production build with node profile
docker build --build-arg PROFILE=node -t areev:node .

# Local dev build (uses Dockerfile.dev)
docker build -f Dockerfile.dev --build-arg PROFILE=dev -t areev:dev .

What environment variables does the container accept?

Pass configuration as environment variables that map to CLI flags and the flat JSON configuration file.

The context database encrypts all grains at rest using an AES-256-GCM envelope. AREEV_MASTER_KEY provides the 256-bit hex customer master key that wraps per-user data encryption keys. Without it, grains are stored unencrypted. Policy is set via the --policy CLI flag (gdpr, hipaa, ccpa, lgpd, pipl, sox, ephemeral, or permissive) and controls retention, consent requirements, and erasure behavior. Pass --policy before the serve subcommand since it is a global argument.

AREEV_API_KEY sets a static API key for authentication in non-auth builds. When built with the auth feature (dev, edge, node, cluster, cloud profiles), the server seeds a system identity at startup with a deterministic API key. For OAuth-based authentication, set the Google OAuth client ID and secret. AREEV_DATA_DIR overrides the default /data directory, and RUST_LOG controls log verbosity.

How do I use the local development Docker setup?

Run scripts/dev/docker-build.sh and scripts/dev/docker-run.sh to build and start a development container named areev-dev on port 4011.

The dev scripts use Dockerfile.dev for a self-contained build that does not depend on the CI builder image. By default the build uses the dev profile; pass a profile name as the first argument to override. The dev container mounts ~/data on the host for persistent AI memory storage, so data survives container restarts and rebuilds.

The docker-run.sh script accepts an optional port argument (default: 4011). It loads shared API keys and OAuth credentials from ~/mg/local/, seeds a system identity with a deterministic API key, and starts the server with MCP, A2A, request coalescing, hot-key detection, and a built-in cross-encoder reranker model. Logs stream via docker-logs.sh, and docker-stop.sh removes the container cleanly.

# Build the dev image (dev profile by default)
scripts/dev/docker-build.sh

# Build with cloud profile
scripts/dev/docker-build.sh cloud

# Run on default port (4011)
scripts/dev/docker-run.sh

# Run on custom port
scripts/dev/docker-run.sh 4012

# View logs / stop
scripts/dev/docker-logs.sh
scripts/dev/docker-stop.sh

Related

• Kubernetes: StatefulSet deployment with persistent volumes
• Configuration: Full configuration reference
• Distributed: Multi-node cluster deployment