Gateway daemon mode

2 min readReferenceUpdated 2026-05-22

What you'll find here

The foreground gateway daemon, the two contracts that describe gateway lifecycle (gateway_config and gateway_runtime_state), and the current boundary between the health service and channel dispatch.

Gateway daemon mode is foreground and local-first, with service-management helpers.

craik gateway start still runs the foreground HTTP service with a /health endpoint, pid-file lock, and persisted lifecycle transitions. craik gateway install now generates launchd/systemd user-service definitions, while status, logs, stop, restart, and doctor commands make lifecycle inspection explicit. Channel dispatch remains policy-bound contract work; do not expose the daemon publicly without TLS termination and explicit policy.

Contracts

Contract

Records

Purpose

craik.gateway_config

config

Local bind settings · mode · policy envelope · pid/log file paths · whether the gateway is enabled.

craik.gateway_runtime_state

supervisor state

Supervised lifecycle state · process id · timestamps · receipts · supervision notes.

Lifecycle states

State

Transitions

Meaning

starting

→ running / failed

A supervisor has accepted a start request and is preparing the process.

running

→ stopping / failed

The supervisor has a process id and start timestamp.

stopping

→ stopped

Reserved for future graceful shutdown coordination.

stopped

terminal

Process is no longer active and has a stop timestamp.

failed

terminal

Supervisor recorded an explicit failure reason.

Commands

Run setup first, then start the foreground daemon:

craik setup --enable-gateway --policy-envelope-id policy_gateway
craik gateway install
craik gateway status
craik gateway start
craik gateway logs
craik gateway stop
craik gateway restart
craik gateway doctor

The command requires an active operator session, loads gateway_default, writes starting, writes running after the HTTP server binds, and writes stopped on graceful shutdown. If the pid file already exists, startup fails instead of running a second daemon.

craik gateway install writes a generated service definition under Craik config:

The generated service uses the absolute craik executable resolved at install time, avoiding service-manager PATH ambiguity.

macOS

launchd plist for a user LaunchAgent.

Linux

systemd --user service unit.

Windows

Manual service plan for this release.

craik gateway stop records a stop request and recovers stale pid files. It does not silently kill a process unless the operator passes --signal-process. craik gateway restart records the stopped state and returns the next step for the installed service or foreground start.

Public binds require policy and explicit TLS acknowledgement.

Daemon mode requires a pid file. Public binds such as 0.0.0.0 require a policy envelope so externally reachable gateway behavior is never implicit. The setup CLI also requires --allow-insecure-public-gateway for public binds because Craik does not terminate TLS itself; production deployments should place the gateway behind TLS termination or keep it on a private network.

Boundary

This phase defines a runnable health service, lifecycle state, persistence, and inspection boundaries. It does not yet add:

Open inbound messages

Production dispatch loop

Hosted TLS termination

Those surfaces must attach policy checks and receipts before they can affect runtime state.

Gateway records are safe to inspect from the operator surface and local store. Starting a long-running service remains an explicit operator action.

What's next

GuideGateway troubleshootingWhat's diagnosable from the contracts today.ReferenceGateway receiptsWhat every channel decision records.