Operate ScenarioX Self-Hosted V1

Run the included scenariox command from the extracted package directory. It always uses .env and docker-compose.customer.yml from that package unless explicitly overridden by operator environment variables.

Inspect the release

./scenariox version
./scenariox config-check
./scenariox preflight
./scenariox status
./scenariox health

status shows container state. health is stricter:

• migration and object-storage initialization must have exited successfully
• readiness-backed APIs and workers must report healthy
• a service still starting or unhealthy makes the command exit nonzero
• services without a probe are labeled process state only

A running container alone is not proof of application readiness.

Start and stop

./scenariox pull
./scenariox start
./scenariox stop
./scenariox restart

stop preserves named volumes, configuration, keys, and release files. restart does not pull a new release or run an upgrade workflow.

To operate one named service, pass its Compose service name:

./scenariox restart auth
./scenariox logs auth

Use a targeted restart only after identifying the affected service and checking its logs.

Read logs

./scenariox logs
./scenariox logs auth
./scenariox logs workspace-orchestrator

The command follows the latest 200 lines. Logs can contain organization, session, candidate, trace, and operation identifiers, but they must not contain configured secret values. Handle operational logs according to the customer security policy.

Administrator bootstrap

./scenariox bootstrap-admin is a one-time installation operation, not a recurring user-management command. It creates the initial organization, user, active membership, ORG_ADMIN role assignment, and audit record atomically.

Uninstall the running application

./scenariox uninstall

This removes application containers and networks while preserving named volumes, .env, keys, and backups. It is not a data purge.

Monitor login rate limiting

The auth service throttles password login attempts per principal (organization slug + email) and per source IP. When a threshold is exceeded the auth service returns an HTTP 429. The defaults are 5 failed attempts within 300 seconds (configurable — see Configuration).

Signs of rate limiting in logs:

./scenariox logs auth | grep -E '"status_code": 429|login_rate_limit'

A rate-limited request appears as a POST /v1/auth/login with status 429. The client sees:

{
  "type": "https://scenariox.dev/errors/login_rate_limited",
  "status": 429,
  "code": "login_rate_limited",
  "detail": "Too many login attempts; try again later"
}

A 503 instead of 429 means Redis is unreachable by the auth service. Check ./scenariox logs redis and verify REDIS_URL in .env.

Inspect active throttle counters:

Rate-limit keys are stored in Redis with a auth:login: prefix and expire automatically when the window elapses. To list active counters:

docker compose -f docker-compose.customer.yml exec redis redis-cli KEYS 'auth:login:*'

Keys are keyed on SHA-256 digests of the principal and IP, not plain text, so the list confirms whether any throttle is active without exposing identity values.

Clear a stuck counter manually:

If a legitimate user is locked out and the window has not yet expired, delete the per-principal counter. This requires the SHA-256 of {org_slug}:{email} (lowercase, stripped):

# Compute the key (on the host, not in the container)
PRINCIPAL=$(printf '%s' "acme-engineering:admin@example.com" | sha256sum | awk '{print $1}')
docker compose -f docker-compose.customer.yml exec redis \
  redis-cli DEL "auth:login:principal:${PRINCIPAL}"

Replace acme-engineering:admin@example.com with the actual organization slug and email. Do not clear the per-IP counter separately unless the same IP is used for multiple principals.

Tune the limits:

See AUTH_LOGIN_RATE_LIMIT_ATTEMPTS and AUTH_LOGIN_RATE_LIMIT_WINDOW_SECONDS in Configuration. The auth service must be restarted after changing these values.

Exit codes

Recovery and upgrades

Package-native backup, backup verification, restore, upgrade, rollback assistance, support bundle generation, and purge are not available in Self-Hosted V1. Their command names are reserved and exit with code 3; they do not perform partial work.

Do not substitute an undocumented database command for these workflows. Preserve the host, package, named volumes, .env, and keys, then contact the ScenarioX support channel defined by the customer agreement.