# How to Configure the Craft Agents Server for TLS with Self-Signed Certificates

> Configure Craft Agents Server for TLS using self-signed certificates. Simply set CRAFT_RPC_TLS_CERT and CRAFT_RPC_TLS_KEY environment variables for secure wss:// connections. Learn how now.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Set the `CRAFT_RPC_TLS_CERT` and `CRAFT_RPC_TLS_KEY` environment variables to point to your PEM-encoded certificate and private key files, then start the server to enable `wss://` connections.**

The Craft Agents headless server from the craft-ai-agents/craft-agents-oss repository supports TLS encryption for its WebSocket RPC interface. By supplying a self-signed certificate and key via environment variables, you can configure the server to use `wss://` instead of `ws://` for secure local development and testing.

## TLS Environment Variables

The server reads three specific environment variables at startup to configure TLS encryption. According to the documentation in [`README.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/README.md) (lines 998-1002), these variables control how the WebSocket listener is wrapped in HTTPS:

- **`CRAFT_RPC_TLS_CERT`**: Path to the PEM-encoded certificate file
- **`CRAFT_RPC_TLS_KEY`**: Path to the PEM-encoded private key file  
- **`CRAFT_RPC_TLS_CA`**: Optional path to a CA chain file for client certificate verification

When `CRAFT_RPC_TLS_CERT` and `CRAFT_RPC_TLS_KEY` are set, the server creates an HTTPS-wrapped WebSocket listener and advertises its URL using the `wss://` scheme instead of `ws://`.

## Generating Self-Signed Certificates for Development

For local development and testing, the repository includes a helper script that generates a self-signed certificate pair valid for 365 days. Located at [`./scripts/generate-dev-cert.sh`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/./scripts/generate-dev-cert.sh) (referenced in [`README.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/README.md) lines 1004-1008), this script automatically creates the required files:

```bash
./scripts/generate-dev-cert.sh

```

This generates two files in the `certs/` directory:

- `certs/cert.pem` — The self-signed certificate
- `certs/key.pem` — The corresponding private key

## Starting the Server with TLS Enabled

Once you have your certificate files, launch the server with the TLS variables set. The entry point at [`packages/server/src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server/src/index.ts) reads these variables and initializes the secure WebSocket listener.

Run the following command to start the server with self-signed certificates:

```bash
export CRAFT_SERVER_TOKEN=$(openssl rand -hex 32)
export CRAFT_RPC_HOST=0.0.0.0
export CRAFT_RPC_TLS_CERT=certs/cert.pem
export CRAFT_RPC_TLS_KEY=certs/key.pem

bun run packages/server/src/index.ts

```

The server will output a secure URL like `CRAFT_SERVER_URL=wss://<public-ip>:9100`. Clients must use this `wss://` URL to connect.

## Connecting Clients to the TLS Endpoint

After starting the server, configure your clients to use the WebSocket Secure protocol. For example, using the Craft CLI:

```bash
export CRAFT_SERVER_URL=wss://203.0.113.5:9100
export CRAFT_SERVER_TOKEN=$CRAFT_SERVER_TOKEN

craft-cli ping

```

For containerized deployments, mount the certificates as read-only volumes and pass the environment variables:

```dockerfile
docker run -d \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=$(openssl rand -hex 32) \
  -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 ./certs:/certs:ro \
  craft-agents-server

```

## Production Deployment Considerations

While self-signed certificates work for development, production deployments should use certificates from a trusted Certificate Authority. As noted in the [`README.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/README.md) (lines 1010-1018), you can replace the self-signed cert with one from **Let's Encrypt** or terminate TLS at a reverse proxy such as **nginx** or **Caddy** before forwarding traffic to the Craft Agents server.

## Summary

- **Set `CRAFT_RPC_TLS_CERT` and `CRAFT_RPC_TLS_KEY`** to enable TLS encryption on the WebSocket interface.
- **Use [`./scripts/generate-dev-cert.sh`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/./scripts/generate-dev-cert.sh)** to quickly create self-signed certificates for development environments.
- **Reference [`packages/server/src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server/src/index.ts)** as the server entry point that initializes the TLS listener.
- **Connect clients using `wss://` URLs** once TLS is enabled, ensuring all traffic is encrypted.
- **Replace self-signed certs with trusted CA certificates** or use a reverse proxy for production deployments.

## Frequently Asked Questions

### Can I use a self-signed certificate in production?

You can use self-signed certificates in production, but clients will receive certificate validation errors unless they explicitly trust your custom CA. For production environments, use certificates from a trusted Certificate Authority like Let's Encrypt, or terminate TLS at a reverse proxy such as nginx or Caddy.

### What file format should the TLS certificates use?

The Craft Agents server expects PEM-encoded files for both the certificate and private key. The `CRAFT_RPC_TLS_CERT` file should contain the base64-encoded certificate data, while `CRAFT_RPC_TLS_KEY` should contain the unencrypted or appropriately encrypted private key in PEM format.

### How do I troubleshoot TLS connection errors?

Verify that the file paths in `CRAFT_RPC_TLS_CERT` and `CRAFT_RPC_TLS_KEY` are correct and accessible to the server process. Check that the certificate and key match, and ensure the certificate has not expired. If using self-signed certificates, clients must either disable strict certificate checking or add your CA to their trust store.

### Is the CA chain environment variable required?

No, `CRAFT_RPC_TLS_CA` is optional. You only need to set this variable if you are implementing mutual TLS (mTLS) and need to verify client certificates against a specific certificate authority chain.