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

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 (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 (referenced in README.md lines 1004-1008), this script automatically creates the required files:

./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 reads these variables and initializes the secure WebSocket listener.

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

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:

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:

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 (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 to quickly create self-signed certificates for development environments.
• Reference 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.

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