# Craft Agents Docker Deployment and TLS Configuration: A Complete Guide

> Deploy Craft Agents OSS with Docker and configure TLS encryption. Learn to enable wss:// using PEM certificates and environment variables for secure headless server deployment. Complete guide.

- Repository: [Craft Docs/craft-agents-oss](https://github.com/lukilabs/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-04-18

---

**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:

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

```

Build the image using Docker Buildx:

```bash
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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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:

```bash
./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)](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:

```bash
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

```bash
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

```bash
./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:

```bash
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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/./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`](https://github.com/lukilabs/craft-agents-oss/blob/main/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`](https://github.com/lukilabs/craft-agents-oss/blob/main/./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.