Configuration

Composery does not wrap upstream runtime settings - you configure it with environment variables. Every switch below documented as "set to 1 or true" is read the same way: the value is trimmed and matched case-insensitively, so 1, true and TRUE all turn it on and everything else - 0, false, yes, a typo, an empty value - leaves it off. In the Compose examples, set them in composery.env; Compose loads that file into the container (env_file). Other hosting providers use their own environment-variable UI.

The init system is selected by COMPOSERY_INIT, set in the compose service's environment: block (not in composery.env). The default is supervisor; use systemd on hosts that allow privileged containers and host cgroups.

The persistence engine is selected the same way by COMPOSERY_PERSISTENCE. The default is auto, which works on every deployment target. See Persistence.

On a Composery Cloud instance there is no composery.env to edit: its environment is rendered from its configuration on the website, so set these from your instance's Configuration page instead. The variables that select the init system, the persistence engine, the ports, and the volume root are part of that deployment's contract and are not configurable there; the password is changed from the IDE's own Change Password page (or recovered from your instance's page on the website) rather than set as a variable.

Variables

IDE sessions

A successful password sign-in and Continue with Composery both create the same local, signed IDE session. Newly issued sessions contain an opaque signed token rather than the configured password hash. Changing the password therefore revokes every session without a separate revocation list.

The session cookie is scoped to the whole origin the instance is served on, not to the path the workbench happens to be mounted at, because the port proxy at /proxy/<port>/ is authenticated by the same session and sits outside that mount. The proxy strips the cookie again before forwarding a request to your own port, so an app you run on your instance never sees it.

The lifetime is absolute rather than sliding: activity does not extend it. Changing COMPOSERY_SESSION_LIFETIME affects sessions created after the IDE restarts; it does not rewrite cookies already issued. Once a session expires, the next authenticated HTTP request or reconnect asks for sign-in. An already established workbench WebSocket is not cut in the middle of an operation.

browser means "every browser session," not "authenticate every HTTP request." The cookie has no Max-Age or Expires, so the browser drops it when that browser session ends. Its signed token still has a 30-day server-side ceiling in case a client retains session cookies longer than expected.

On a Composery Cloud instance, Continue with Composery redirects through the website so the signed-in owner can prove access, then returns a one-time, PKCE-bound authorization code to the instance. The website session is never copied to it, and the code can create only a local IDE session. Password recovery uses a separately typed code that can create only a one-time password-setup grant. Self-hosted instances continue to use their own password.

API

Composery serves a small automation API on the same port. It is off in practice until you mint a key with composery api key create; with no keys, every endpoint returns 401. The key store lives at <volume>/api/keys.json, on the persistent volume shared with persistence (/data by default; see COMPOSERY_DOCKER_VOLUME_PATH).

Invalid numeric values fall back to the defaults. Extreme numeric values are clamped to guardrail caps: 24h one-shot timeout, 64 MiB one-shot output, 1000 RPS, 10000 burst, 500 concurrent terminal streams, and 1000 failed-auth attempts/min/IP.

Rate limits are abuse rails, not DDoS defense - that is handled by the platform in front of the instance.

HTTP routes

The container includes Caddy as its single HTTP entrypoint. /etc/caddy/Caddyfile is its complete, persistent configuration; it is not a generated file or a Composery-specific fragment. The initial configuration strips the public /ide/ mount before sending workbench traffic to the loopback IDE. It keeps /proxy/* and /absproxy/* at the origin root so installed PWAs do not capture port applications. The health endpoint, automation API, and robots.txt/security.txt files also stay at root; other root paths return 404, except /, which redirects to /ide/.

Add an application handler above the final not-found handler:

handle /hooks/linear* {
	reverse_proxy 127.0.0.1:3000
}

Use Caddy's standard commands to check and apply changes in either runtime profile:

caddy validate --config /etc/caddy/Caddyfile
caddy reload --config /etc/caddy/Caddyfile

An invalid reload leaves the running configuration in place. An invalid configuration at cold start prevents Caddy from starting, just as it would on a VPS. Composery never replaces the file automatically.

This internal Caddy does not require Caddy at the outer edge. A VPS, ingress controller, load balancer, tunnel, or another reverse proxy can publish port 8080 directly. The Compose recipes that include a second Caddy use it only for public TLS and domains.

SSH

An instance's SSH service is separate from the API: a different protocol, a different credential, and settings of its own. See SSH.