ecko
Environment variables
Configuration is environment variables, never code. There is no config file to load, no Ecko.configure(...) call, and no way for a library to change your provider behind your back. A program's behaviour is a function of its source and its environment.
A project can pin its own environment in the environment block of ecko.json, which is applied before evaluation and overrides the surrounding shell - so a checkout runs the way its author intended rather than the way your terminal happens to be set up.
The global flags --key, --provider, --model, --trace and --cache are one-run overrides of the matching variable.
AI and LLM
| variable | meaning |
|---|---|
ECKO_API_KEY | Provider API key. ECKO_LLM_API_KEY is also accepted. Unset means mock mode. |
ECKO_AI_PROVIDER | openai (default), openrouter, ollama |
ECKO_AI_MODEL | Model name; each provider has a default |
ECKO_AI_BASE_URL | Override the provider endpoint, for a proxy or a compatible server. Must be https, or http to a loopback host, since the API key travels on it; ECKO_ALLOW_HTTP=1 overrides |
ECKO_AI_EMBED_MODEL | Embedding model; defaults per provider |
ECKO_AI_MAX_RETRIES | Retries for typed and contract calls. Default 3 |
ECKO_AI_MAX_CALLS | Hard cap on total ai calls per process. Unset means unlimited |
ECKO_AI_MAX_TOOL_ROUNDS | Tool-call rounds per ai ... using. Default 8 |
ECKO_AI_TOOL_TIMEOUT_MS | Per-round tool timeout. Default 30000; 0 disables |
ECKO_AI_TOOL_MAX_RESULT | Max bytes of one tool result fed back to the model. Default 32768; 0 disables |
ECKO_AI_CACHE | Directory for the prompt cache |
ECKO_TRACE | 1 traces to stderr; a path writes JSONL |
ECKO_RETRY_BASE_MS | Base backoff for retry. Default 50 |
ECKO_AI_MAX_CALLS is the one to set in anything unattended. It is a hard budget: the call that would exceed it fails rather than spending.
Concurrency
| variable | meaning |
|---|---|
ECKO_MAX_PARALLEL | Concurrent workers in pmap and tool rounds. Default: all cores |
ECKO_MAX_TASKS | Cap on running async tasks. Default 256 |
HTTP and WebSocket server
| variable | meaning |
|---|---|
ECKO_HTTP_WORKERS | How many http.serve handler invocations run at once. Default 8. Worth tuning: leave it alone for handlers that compute, raise it for handlers that wait on a database, a service or ai - see sizing the pool |
ECKO_MAX_STREAMS | Concurrent streaming/SSE responses. Default 1024; past it a stream is refused with 503 |
ECKO_HTTP_REQUEST_TIMEOUT_MS | Per-request handler timeout. 0 or unset means unlimited |
ECKO_HTTP_MAX_BODY | Max request body in bytes; a larger one is answered 413 rather than truncated. Default 10 MiB |
ECKO_NET_TIMEOUT_MS | Read and write deadline on a std.net socket, so a silent peer surfaces an error rather than blocking forever. 0 disables it. Default 30000 |
ECKO_HTTP_READ_TIMEOUT_MS | The slow-client deadline: how long a connection may take to send its request headers, and thereafter how long it may go silent mid-body before the server answers 408. Applied per body frame, so a slow but steady upload of any size completes. Default 30000 |
ECKO_MAX_WS_CONNS | Max concurrent WebSocket connections. Default 1024 |
Runtime limits
| variable | meaning | ||
|---|---|---|---|
ECKO_MAX_DEPTH | Call and recursion depth. Default 2000 | ||
ECKO_MAX_PARSE_DEPTH | How deep an expression tree may nest, by brackets or by chaining (a + b + c, `x | > f | > g, else if arms). Default 128` |
ECKO_MAX_STEPS | Opt-in loop and step budget. Unset means unlimited | ||
ECKO_MAX_ALLOC | Bytes one value built from a count may hold, and the most one read from a stream may return: a string from *, repeat or the pad family, bytes from random.bytes or io.read_exact, a whole-file fs.read, a buffered HTTP body. Default 256 MiB | ||
ECKO_ARCHIVE_MAX_UNPACKED | Total bytes an std.archive extraction or a std.zlib decompression may produce. Default 1 GiB |
These exist so that adversarial or accidental input degrades into a catchable error instead of exhausting the machine - see Resource limits.
Logging and terminal
| variable | meaning |
|---|---|
ECKO_LOG | Level filter for the default std.log sink: debug < info < warn < error. Default info |
ECKO_BACKTRACE | Show Rust's own panic output when the interpreter hits an internal fault. Off by default: the fault is reported as a message and exit 70 either way, and this adds the raw detail for diagnosing it. |
NO_COLOR | Any value disables terminal colour (the convention) |
CLICOLOR_FORCE | Force colour on even when stdout is not a TTY |
Packages
| variable | meaning |
|---|---|
ECKO_PKG_MAX_BYTES | Max download size for a package. Default 50 MiB |
ECKO_PKG_MAX_UNPACKED | Max unpacked size. Default 200 MiB |
ECKO_ALLOW_HTTP | 1 or true permits plain-http package sources from non-loopback hosts |
ECKO_GIT_BASE | Override the forge base URL, for a private mirror |
ECKO_NET_TOKEN | Bearer token attached to package fetches, for a private repository |
The two size caps and the https default are there because fetching a package is the moment a program trusts something it did not write. ECKO_ALLOW_HTTP exists for a local registry; needing it against a real host is a warning sign.
Scaffolding
| variable | meaning |
|---|---|
ECKO_TEMPLATES_REPO | Where ecko scaffold gets templates: an owner/repo, an archive URL, or a local directory read with no network and no cache. Default ecko-lang/templates |
ECKO_TEMPLATES_DIR | Where they are cached. Default: the platform cache directory |
Secrets
Nothing here should hold a secret except ECKO_API_KEY and ECKO_NET_TOKEN, and neither belongs in a committed file. Put them in your shell, your CI secret store, or a secret manager. Inside a program, wrap sensitive values in secret so they cannot be printed or logged by accident, and reach for std.config when you want layered configuration with declared secret fields.