Environment Variables

Copy .env.example to .env at the project root:

bash

cp .env.example .env   # macOS/Linux
copy .env.example .env  # Windows

Every variable has a working default — the app boots without any configuration.

Server

`PORT`

Default: 9425

HTTP listen port. 9425 spells "WICK" on a T9 keypad — picked to avoid collisions with common dev ports (3000 React, 5173 Vite, 5432 Postgres).

env

PORT=9425

When running under the desktop tray, the resolution order is PORT env → port in config.json → built-in default. See Desktop Tray ▶ Port.

Database

`DATABASE_URL`

Default: wick.db (SQLite file in the project root)

Leave blank to use SQLite — no database setup required. SQLite is fine for local development and small deployments.

env

# SQLite (default — no config needed)
DATABASE_URL=

# PostgreSQL
DATABASE_URL=postgres://user:password@localhost:5432/myapp?sslmode=disable

App

`APP_NAME`

Default: (empty — falls back to "Wick")

App name shown in the UI and used to namespace per-app paths (~/.<app>/) for config / DB / logs / agents. Only used on first boot to seed the database display name; the ~/.<app>/ directory layout is fixed for the life of the install. After first boot the display name can be changed from /admin/configs — the database value always wins.

At build time (wick build) the same variable bakes the app name into the binary via app.BuildAppName, used as the default MCP server name and the per-app data dir.

The ~/.<app>/ tree currently includes:

Path	What lives there
`~/.<app>/wick.db`	SQLite database (when `DATABASE_URL` is blank)
`~/.<app>/config.json`	Userconfig — provider instances, status cache, misc kv
`~/.<app>/INITIAL_CREDENTIALS.txt`	Auto-generated admin passphrase (deleted on first password rotation)
`~/.<app>/logs/{app,server,worker,gate}-YYYY-MM-DD.log`	Daily tail logs
`~/.<app>/agents/`	Agents subsystem state — projects, sessions, presets, gate spec/socket

env

APP_NAME=My Internal Tools

`APP_URL`

Default: http://localhost:9425

Base URL used for SSO callbacks and absolute links. Also drives the host allowlist — requests whose Host header (or X-Forwarded-Host) doesn't match this URL's host get a 403. /health is exempt.

The env var overrides the DB value at read time (and read-only-locks the row in /admin/variables). Useful for bootstrapping on a remote host where the seeded localhost value would block your first login.

env

APP_URL=https://tools.example.com

`ALLOWED_ORIGINS`

Default: (empty — only APP_URL is allowed)

Comma-separated list of extra URLs (or bare host:port) added to the host allowlist alongside APP_URL. Overrides the allowed_origins kvlist in /admin/variables at read time.

env

ALLOWED_ORIGINS=http://192.168.1.42:9425,http://10.0.0.5:9425

LAN / Termux access

On Termux (and any host where localhost isn't enough) open /admin/variables, click Detect LAN URLs to see your reachable IPv4 addresses, and paste them into the allowed_origins row. The install.sh script also prints your private-range IPs at the end of a Termux install — copy from there if the admin UI isn't reachable yet, and bootstrap with ALLOWED_ORIGINS=http://<ip>:9425 ./<app> server.

Suggestions are read-only by design: the install script never writes the allowlist for you because a phone may be on public Wi-Fi where exposing the manager to every device on the SSID would be unsafe.

Loopback /mcp is always allowed

The internal agent MCP connects to /mcp over loopback (127.0.0.1:<PORT>). That endpoint is exempt from the host allowlist regardless of APP_URL / ALLOWED_ORIGINS, so workflow & agent connectors work out of the box — you do not need to add 127.0.0.1 here for them. The exemption is scoped to /mcp from loopback hosts only, and /mcp stays bearer-authed.

Admin

`APP_ADMIN_EMAILS`

Default: admin@admin.com

Comma-separated list of emails automatically granted the admin role on first login. Env-only by design — admins cannot remove themselves from this list via the UI.

env

APP_ADMIN_EMAILS=alice@example.com,bob@example.com

`APP_ADMIN_PASSWORD`

Default: (empty — auto-generated 5-word passphrase)

Seeds the password for the admin account created on first boot. When unset (or left as the historical "admin") wick generates a 5-word passphrase and writes it to ~/.<app>/INITIAL_CREDENTIALS.txt — operators can recover it from disk, the tray menu (About → Open default password), or the stdout banner on headless runs.

Re-seeded on every boot until the admin completes /profile/setup (which sets admin_password_changed=true and deletes the credentials file). After that, this env is ignored.

env

APP_ADMIN_PASSWORD=changeme

Agent MCP

When a workflow agent node (or a chat agent) spawns Claude, wick points it at the live MCP server over loopback (http://127.0.0.1:<PORT>/mcp) so it can use connectors without cold-starting a separate mcp serve process per run. These two vars tune that behavior.

`WICK_DISABLE_SHARED_MCP`

Default: unset (shared MCP enabled)

Set to any non-empty value to stop wick from injecting the loopback MCP config into spawned Claude agents. They then fall back to whatever MCP servers the user's own config (~/.claude.json, .mcp.json) provides.

env

WICK_DISABLE_SHARED_MCP=1

`WICK_STRICT_MCP`

Default: unset (merge mode)

By default the injected wick MCP server is merged with the user's existing MCP servers (no --strict-mcp-config), so their own connectors keep working. Set this to pass --strict-mcp-config, isolating the agent to only the wick MCP server.

env

WICK_STRICT_MCP=1

`WICK_PROVIDERSYNC_DISABLE`

Default: unset (sync enabled when the job is enabled)

Set to true to disable the Provider Storage Sync subsystem for this instance. When set, the cron job exits immediately on every tick, boot restore is skipped, and the realtime watcher is never started. Useful when multiple server instances share one database and only one should perform sync.

env

WICK_PROVIDERSYNC_DISABLE=true

See Provider Storage → Per-instance kill switch.

Build-time

These are read by wick build, not by the running binary. They populate app.BuildAppName / BuildAppVersion / GitHubPAT / GitHubRepo via Go ldflags. Each falls back to the matching field in wick.yml (or empty for the GitHub pair) when not set.

`APP_NAME`

Default: name: from wick.yml (else "app")

Doubles as runtime display name (see above) and build-time bake. At build time it's stamped into app.BuildAppName — used to namespace config / DB / log paths and as the default MCP server name.

env

APP_NAME=myapp

`APP_VERSION`

Default: version: from wick.yml (else "dev")

Bakes the app version. Shown in the tray title and About menu, advertised by MCP.

env

APP_VERSION=1.2.0

`RELEASE_GITHUB_PAT`

Default: (empty — self-updater disabled)

GitHub fine-grained PAT with Contents: read on the releases repo. Embedded into the binary so it can poll releases/latest. Pair with RELEASE_GITHUB_REPOSITORY.

See wick build reference ▶ PAT setup for scopes and rotation.

`RELEASE_GITHUB_REPOSITORY`

Default: (empty — self-updater disabled)

Releases repo in owner/repo form. Named RELEASE_GITHUB_REPOSITORY (not GITHUB_REPOSITORY) because GitHub Actions auto-injects GITHUB_REPOSITORY to the source repo and silently blocks step-level overrides — using the prefixed name keeps CI working.

env

RELEASE_GITHUB_REPOSITORY=acme/myapp-releases

UI Stack

Wick uses Tailwind CSS for styling and templ for HTML templating. Both are set up automatically by go run . setup — no manual configuration needed.

Tool	What it does	Managed by
Tailwind CSS	Utility-first CSS	`wick.yml` setup task downloads the standalone CLI
templ	Type-safe Go HTML templates	`wick.yml` setup task installs `templ` via `go install`

The go run . dev command runs templ generate and rebuilds CSS automatically before starting the server.

For AI agents

Tailwind classes live in .templ files only. Never edit *_templ.go by hand — it is regenerated by templ generate.

Diagnostics

`WICK_PPROF`

Default: unset (profiling disabled)

Set to any non-empty value to start a Go pprof HTTP server on 127.0.0.1:6060. Exposes the standard /debug/pprof/ endpoints (heap, goroutine, CPU profile) for diagnosing memory or CPU issues. The listener is bound to loopback only and is never reachable through the public HTTP port.

env

WICK_PPROF=1

Access profiles with go tool pprof http://127.0.0.1:6060/debug/pprof/heap or curl http://127.0.0.1:6060/debug/pprof/goroutine?debug=1. Do not set this in production unless actively profiling — the endpoint has no authentication.

`WICK_MEMORY_LIMIT`

Default: unset (no soft limit — Go runtime default behavior)

Sets a soft memory limit for the wick process via runtime/debug.SetMemoryLimit. When the live heap approaches this value, the GC becomes more aggressive and returns memory to the OS rather than holding it at the high-water mark. Useful on small VMs or containers where the boot-time provider-storage restore would otherwise pin RSS until the next major GC.

Accepted formats match the GOMEMLIMIT convention:

Format	Example	Meaning
Binary suffixes	`1200MiB`, `2GiB`, `512KiB`	1 MiB = 1 048 576 bytes
Decimal suffixes	`500MB`, `1GB`	1 MB = 1 000 000 bytes
Raw bytes	`1258291200`	exact byte count

env

WICK_MEMORY_LIMIT=1200MiB
WICK_MEMORY_LIMIT=2GiB

This is independent of the standard GOMEMLIMIT environment variable — both can coexist, with WICK_MEMORY_LIMIT applied at server startup. If the value cannot be parsed, a warning is logged and no limit is set. Off by default; do not set it lower than your expected working-set size or GC pressure will spike.

Network

`WICK_DNS_SERVERS`

Default: unset

Comma- or space-separated list of nameservers the binary uses for DNS when /etc/resolv.conf configures no usable nameserver (the Termux/Android case). Port defaults to 53 if omitted.

env

WICK_DNS_SERVERS=1.1.1.1,8.8.8.8
WICK_DNS_SERVERS=192.168.1.1:53 8.8.4.4

This override is checked before $PREFIX/etc/resolv.conf and Android system properties (net.dns1/net.dns2). A configured loopback resolver (e.g. systemd-resolved's 127.0.0.53) is always left alone — this var has no effect on normal Linux/macOS hosts.

Command Gate

The Command Gate sidecar (<app>-gate) reads no environment variables. Earlier iterations had WICK_GATE_BIN / GATE_BIN / WICK_GATE_SPEC / GATE_SPEC — all dropped. Resolution is automatic:

Sibling-of-executable: <app>-gate[.exe] next to the main binary (shipped by wick build --installer).
Embedded extract: unpacked from the main binary on first use.
PATH: last-ditch lookup of <app>-gate.

Override the binary location only by placing your replacement in one of those three spots — there's no env var fallback.

Environment Variables ​

Server ​

PORT ​

Database ​

DATABASE_URL ​

App ​

APP_NAME ​

APP_URL ​

ALLOWED_ORIGINS ​

Admin ​

APP_ADMIN_EMAILS ​

APP_ADMIN_PASSWORD ​

Agent MCP ​

WICK_DISABLE_SHARED_MCP ​

WICK_STRICT_MCP ​

WICK_PROVIDERSYNC_DISABLE ​

Build-time ​

APP_NAME ​

APP_VERSION ​

RELEASE_GITHUB_PAT ​

RELEASE_GITHUB_REPOSITORY ​

UI Stack ​

Diagnostics ​

WICK_PPROF ​

WICK_MEMORY_LIMIT ​

Network ​

WICK_DNS_SERVERS ​

Command Gate ​

Environment Variables

Server

`PORT`

Database

`DATABASE_URL`

App

`APP_NAME`

`APP_URL`

`ALLOWED_ORIGINS`

Admin

`APP_ADMIN_EMAILS`

`APP_ADMIN_PASSWORD`

Agent MCP

`WICK_DISABLE_SHARED_MCP`

`WICK_STRICT_MCP`

`WICK_PROVIDERSYNC_DISABLE`

Build-time

`APP_NAME`

`APP_VERSION`

`RELEASE_GITHUB_PAT`

`RELEASE_GITHUB_REPOSITORY`

UI Stack

Diagnostics

`WICK_PPROF`

`WICK_MEMORY_LIMIT`

Network

`WICK_DNS_SERVERS`

Command Gate