Craft Agents Docker Deployment and TLS Configuration: A Complete Guide

Craft Agents OSS deploys as a headless server using Dockerfile.server, with TLS encryption enabled by mounting PEM certificates and setting CRAFT_RPC_TLS_CERT and CRAFT_RPC_TLS_KEY environment variables to switch from ws:// to wss://.

The lukilabs/craft-agents-oss repository provides a production-ready containerization strategy for running Craft Agents as a persistent server. This guide covers the complete Docker deployment configuration, including image building, environment variable setup, and TLS encryption for secure WebSocket connections.

Building the Docker Image from Dockerfile.server

Start by building the server image from Dockerfile.server at the repository root. This Dockerfile installs system packages, creates a non-root craftagents user, copies the monorepo sources, installs Bun dependencies, builds the MCP helper servers, and compiles the web UI.

The final stage sets the entrypoint to the server’s main script:

ENTRYPOINT ["bun", "run", "packages/server/src/index.ts"]

Build the image using Docker Buildx:

docker buildx build -f Dockerfile.server -t craft-agents-server .

Docker Deployment Environment Variables

Container behavior is controlled via environment variables consumed by packages/server/src/index.ts. For Docker deployment and TLS configuration, these variables are essential:

Variable	Required	Default	Purpose
CRAFT_SERVER_TOKEN	Yes	—	Bearer token for client authentication
CRAFT_RPC_HOST	No	127.0.0.1	Bind address (use 0.0.0.0 for Docker)
CRAFT_RPC_PORT	No	9100	WebSocket listen port
CRAFT_RPC_TLS_CERT	No	—	Path to PEM certificate (enables wss://)
CRAFT_RPC_TLS_KEY	No	—	Path to matching private key
CRAFT_RPC_TLS_CA	No	—	Optional CA chain for client certificate validation

When CRAFT_RPC_TLS_CERT and CRAFT_RPC_TLS_KEY are present, the server loads them with fs.readFileSync and creates a WsRpcTlsOptions object. The protocol switches to wss://. Without these variables, the server falls back to unencrypted ws://.

Configuring TLS for Secure WebSocket Connections

Generating Development Certificates

For local testing, generate self-signed certificates using the provided helper script:

./scripts/generate-dev-cert.sh [output-dir]

This creates cert.pem and key.pem valid for 365 days in the specified directory (default: ./certs). The script outputs a ready-to-use Docker command configured for TLS.

Source: [scripts/generate-dev-cert.sh](https://github.com/lukilabs/craft-agents-oss/blob/main/scripts/generate-dev-cert.sh)

Running the Container with TLS Enabled

Mount the certificate directory as a read-only volume and set the TLS environment variables to the container paths:

docker run -d \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=secure-token-here \
  -e CRAFT_RPC_HOST=0.0.0.0 \
  -e CRAFT_RPC_TLS_CERT=/certs/cert.pem \
  -e CRAFT_RPC_TLS_KEY=/certs/key.pem \
  -v $(pwd)/certs:/certs:ro \
  -v craft-data:/root/.craft-agent \
  craft-agents-server

When TLS is active, the server logs CRAFT_SERVER_URL=wss://<host>:9100. Clients must connect using the wss:// scheme.

Production TLS Recommendations

For production Docker deployments:

• Use CA-signed certificates from Let's Encrypt or a commercial provider instead of self-signed certs
• Enable client certificate validation by supplying CRAFT_RPC_TLS_CA with a CA bundle for mutual TLS
• Consider reverse proxy termination: Run the container without TLS variables (using ws:// internally) and terminate SSL at nginx or Caddy. Omit the CRAFT_RPC_TLS_* variables in this configuration.

Complete Docker Deployment Examples

Basic Deployment Without TLS

docker run -d \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=dev-token-123 \
  -e CRAFT_RPC_HOST=0.0.0.0 \
  -v craft-data:/root/.craft-agent \
  craft-agents-server

This exposes the server on port 9100 with unencrypted WebSocket connections suitable for local development.

Secure Deployment With TLS

./scripts/generate-dev-cert.sh ./certs
docker run -d \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=secure-token-456 \
  -e CRAFT_RPC_HOST=0.0.0.0 \
  -e CRAFT_RPC_TLS_CERT=/certs/cert.pem \
  -e CRAFT_RPC_TLS_KEY=/certs/key.pem \
  -v $(pwd)/certs:/certs:ro \
  -v craft-data:/root/.craft-agent \
  craft-agents-server

Verify the secure connection:

craft-cli --url wss://localhost:9100 --token secure-token-456 ping

Summary

• Build the production image from Dockerfile.server using docker buildx build
• Configure the deployment via environment variables consumed by packages/server/src/index.ts
• Enable TLS by setting CRAFT_RPC_TLS_CERT and CRAFT_RPC_TLS_KEY with paths to PEM files mounted via read-only volumes
• Generate development certificates using ./scripts/generate-dev-cert.sh for local testing
• Use 0.0.0.0 as CRAFT_RPC_HOST to allow remote connections; omit TLS variables only when behind a reverse proxy

Frequently Asked Questions

How do I enable TLS in Craft Agents Docker deployment?

Set the CRAFT_RPC_TLS_CERT and CRAFT_RPC_TLS_KEY environment variables to point to PEM-encoded certificate and key files inside the container. Mount these files via a read-only volume. The server automatically switches from ws:// to wss:// when these variables are present, as implemented in packages/server/src/index.ts.

What port does the Craft Agents server use in Docker?

The default port is 9100, controlled by the CRAFT_RPC_PORT environment variable. You must expose this port when running the container using -p 9100:9100 to allow external WebSocket connections to reach the server.

Can I run Craft Agents server without TLS?

Yes. If you omit the CRAFT_RPC_TLS_CERT and CRAFT_RPC_TLS_KEY environment variables, the server starts with unencrypted WebSocket (ws://). This configuration is suitable for development environments or when running behind a reverse proxy that handles TLS termination.

How do I generate self-signed certificates for testing?

Run the ./scripts/generate-dev-cert.sh script from the repository root. It creates cert.pem and key.pem files valid for 365 days in the ./certs directory (or specify a custom output directory as an argument). The script prints a sample Docker command pre-configured to use these certificates for immediate testing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}