Reference Documentation

These documents are the authoritative reference for ctrl-exec. They are rendered directly from the ctrl-exec repository and kept in sync automatically.

For narrative guides and conceptual overviews, see the sections in the left navigation.

Command and Configuration Reference

REFERENCE: Complete command reference for ced and cea, every configuration key for ctrl-exec.conf and agent.conf, all ENVEXEC_* environment variables, and operational procedures.

Logging and API

LOGGING: Every ACTION= value emitted by the dispatcher, API server, and agent — fields, priorities, example log lines, field glossary, and alert pattern tables.
API: HTTP REST API reference for ctrl-exec-api — every endpoint, request and response format, error codes, auth hook integration, and the live OpenAPI spec generator.

Installation and Deployment

INSTALL: Full installation guide — prerequisites, installer flags, initial setup, pairing walkthrough, auth hook examples, adding scripts, cert renewal, troubleshooting, and uninstall.
DOCKER: Docker deployment — Dockerfiles, entrypoint scripts, docker-compose configuration, pairing workflow in containers, encrypted credential patterns, and multi-agent setups.

Operations

HIGH-AVAILABILITY: Running redundant ctrl-exec instances — shared state, replication approaches, load balancing options, active/passive failover, active/active considerations, cert rotation procedure, and what HA does not protect against.
SECURITY: Security model — mTLS trust boundaries, pairing security properties, auth hook design, file permissions, systemd hardening, threat summary table.
SECURITY-OPERATIONS: Operational security — cert lifecycle, revocation procedures, CA compromise recovery, auth hook hardening, monitoring and alerting recommendations.

Development and Testing

TESTING: Test suite guide — running unit tests, running integration tests, --install-auth-test setup for test 15, writing new tests, coding conventions.
MANUAL-CHECKS: Manual verification checks — behaviours that cannot be automated, with step-by-step instructions and pass/fail criteria for each.
DEVELOPER: Developer documentation — module reference, binary internals, wire format, syslog format pointer, cert renewal flow, release procedure, SBOM.