Environment Variables
Common environment variables used by Federation.
| Variable | Purpose |
|---|---|
DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY | Lets Federation issue and validate user_token internally |
DOWNCITY_CITY_DATABASE_URL | Optional. Specifies the database URL used by Federation |
OPENAI_API_KEY | Example provider key; recommended to write it into the Federation database through Admin env |
OPENAI_BASE_URL | Example provider base URL; recommended to write it into the Federation database through Admin env |
fed deploy interactively provisions the administrator ID and password. The password is stored as a PBKDF2 digest and administrator sessions are stored server-side; there is no administrator key environment variable. DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY and BETTER_AUTH_SECRET are generated automatically on first boot and stored in Federation's env table.
If DOWNCITY_CITY_DATABASE_URL is omitted, the default database path is:
.base/downcity.sqliteOfficial local-node configuration
These settings belong to the private/services/local-node host, whose default development port is 3000. Use that service's .env.example to prepare project configuration. The development entry reads the project .env; standalone mode with DOWNCITY_DATA_DIR uses the CLI's persisted runtime snapshot.
| Variable | Default | Constraint |
|---|---|---|
HOST | 127.0.0.1 | Only 127.0.0.1, ::1, or localhost; no wildcard or public address |
PORT | 3000 | Integer from 1 to 65535 |
PUBLIC_URL | http://localhost:${PORT} | Canonical HTTP(S) loopback origin with the same effective port as PORT; falls back to DOWNCITY_FEDERATION_BASE_URL before the default |
DOWNCITY_LOCAL_ALLOWED_ORIGINS | Empty | Comma-separated additional exact trusted HTTP(S) origins; no additional cross-origin pages by default |
DOWNCITY_FEDERATION_DATABASE_URL | Unset | A file: SQLite URL, taking precedence over DATABASE_PATH |
DATABASE_PATH | ./data/local.db | SQLite file path; defaults to data.sqlite inside DOWNCITY_DATA_DIR when that directory is set |
Origins must have no trailing slash, path, query, fragment, credentials, or explicit default port. *, null, and inputs requiring URL normalization are rejected. Canonical origins using default ports 80/443 omit the port. Valid examples: PUBLIC_URL=http://localhost:3000 and DOWNCITY_LOCAL_ALLOWED_ORIGINS=http://localhost:5173,https://client.example.com.
User sessions own identity, permissions, and Credits. City automatically carries optional city_id for logs, usage, and job source only. Business calls use federation.user.service(name) on the current Federation; administrators use a separate Session.
How provider env is used
The model handler reads directly from input.env:
import {
AIChannel,
stream_openai_compatible_model,
type AIChannelStreamInput,
type AIChannelStreamResult,
} from "@downcity/federation";
class DeepSeekChannel extends AIChannel {
constructor() {
super({
id: "deepseek",
env: { DEEPSEEK_API_KEY: "DeepSeek API Key" },
base_url: "https://api.deepseek.com",
});
}
protected async stream(
input: AIChannelStreamInput,
): Promise<AIChannelStreamResult> {
const api_key = input.env("DEEPSEEK_API_KEY");
if (!api_key) throw new Error("DEEPSEEK_API_KEY is required");
return stream_openai_compatible_model(input, {
api_key,
base_url: this.base_url ?? "https://api.deepseek.com/v1",
});
}
}
const deepseek = new DeepSeekChannel();So the practical rules are simple:
- you choose the env key names yourself
- uppercase snake case is recommended
- read values through
input.env(key)insidestream()
Write values into the database
A trusted backend can write provider keys through Federation Admin:
await federation.admin.env.upsert({
key: "DEEPSEEK_API_KEY",
value: "sk-xxx",
});These values are stored in the env table inside the Federation database. Business runtime reads only from that Federation-managed env table and no longer falls back to .env or process environment variables.
See also AIChannel environment variables.