FAQ

Short answers to recurring questions, each verified against the Envoy source or maintained references. Follow the links for the full pages.

Can tasks run without the server?

Yes. The envoy CLI runs tasks and jobs standalone: envoy <task> --config connectors.yaml, with --arguments for task arguments and --output for ndjson, json, or none. Connector credentials come from a local connectors.yaml instead of the server database. The server adds the UI, REST API, scheduling, run history, and remote executors on top of the same task runtime. See Commands and flags.

Where do connector credentials live?

Never in task or job YAML — tasks declare typed connector slots only. On the server, credentials are stored as encrypted secrets in the configured secret provider (database-backed or Azure Key Vault) and bound when a Job is created or a run starts. On the CLI, they come from connectors.yaml. See Hardening, RBAC, and secrets.

What databases are supported as the state store?

SQLite (default), Microsoft SQL Server, and PostgreSQL — store.type: sqlite | mssql | postgres in envoy-server.yaml. Run logs independently support file, db, mssql, postgres, or victoria_logs. See Server configuration.

How do I move an Envoy instance to another host?

Move the state as a set: the application database (or repoint to the same managed database), envoy-server.yaml, the data and connector-database directories, and the same ENVOY_ENCRYPTION_KEY. Without the original encryption key, stored connector and TOTP secrets are unrecoverable. See Backups and upgrades.

Why didn't my edited YAML file change the task in the UI?

Startup seed import is create-only: files in tasks_dir and jobs_dir are imported when no record with that name exists, and are skipped otherwise. After the first import, the database copy is authoritative. Push updates explicitly with a bundle import. See Seed import.

How do I see what a step is actually doing?

Run with --debug to print step input, config, and output to stderr, or set debug: true on a single step — it works without the global flag. Structured JSON logs go separately to logs/envoy.log, controlled by --log-level (trace, debug, info, warn, error, silent). See Testing and debugging tasks.

How do I validate a task without running it?

envoy validate <task> checks the YAML structure, step types, connector references, and JSONata expressions without needing connector configs. The server runs the same validator in the task editor.

What is the difference between a Job Template, a Job, and a Job Run?

A Job Template is a YAML DAG of Tasks with a connector mapping. A Job is an instantiated template with real Connectors bound; it is persistent and can run many times. A Job Run is one execution of a Job, containing individual task runs.

Can one deployment run tasks on a separate machine?

Yes. Set executor.type: http on the control plane and start envoy executor --control-plane <url> on the worker with the shared ENVOY_EXECUTOR_KEY. Executors register, heartbeat, and receive dispatched tasks; the control plane fails work whose executor disappears. See Control plane and executors.

Why is there a file size limit on connector uploads?

Uploads through the UI and POST /api/connectors/:id/files are capped by connectors.upload_max_bytes, defaulting to 25 MiB. Raise it in envoy-server.yaml (or ENVOY_CONNECTOR_UPLOAD_MAX_BYTES for generated Docker configs) if your deployment needs larger files.

Where do metrics go if I configure nothing?

A new server creates a default durable backend matching its state configuration — SQLite deployments get a sqlite metrics backend, MSSQL deployments an mssql one. A task run with no backend at all uses a no-op collector and records nothing. See Metrics and observability.

Do old runs and logs get cleaned up automatically?

Yes, when retention is configured: runs.retention.max_age_days (default 30) with a nightly cleanup_cron (default 0 3 * * *) prunes logs of terminal runs, and delete_runs: true also removes run records and metrics. Set max_age_days to 0 or less to disable. See Retention.

Related

• Common errors — symptom-first error entries
• Server configuration — the full configuration schema
• Commands and flags — the standalone CLI surface