Configuration

Configuration

All configuration is by environment variable. There are no config files, databases or other services. For local stdio clients, set the variables in the client's env block. For Docker, put them in .env (see Docker Deployment). The template is .env.example.

Reference

Variable	Required	Default	Read by	Purpose
HULY_EMAIL	Option A	—	src/connection.ts	Account email for login
HULY_PASSWORD	Option A	—	src/connection.ts	Account password
HULY_TOKEN	Option B	—	src/connection.ts	Account token (SSO accounts); takes precedence over email/password when set
HULY_ACCOUNTS_URL	Self-hosted	https://account.huly.app	src/connection.ts, scripts/setup.js	Account service: login, workspace discovery, selectWorkspace, members
HULY_FRONT_URL	Self-hosted; optional on Cloud	—	src/tools/{documents,issues,organizations}.ts, src/utils/storage.ts	Front service: content downloads and blob uploads/deletes via /files
HULY_WORKSPACE	No (legacy)	—	src/connection.ts, helper scripts	Restrict the server to one workspace; fallback workspace for helper scripts

Exactly one auth option is needed: A (HULY_EMAIL + HULY_PASSWORD) or B (HULY_TOKEN). With neither, the first tool call fails with "Missing credentials. Provide HULY_TOKEN (for SSO accounts) or both HULY_EMAIL and HULY_PASSWORD." Empty strings count as unset.

Typical setups

Huly Cloud, password account

HULY_EMAIL=you@example.com
HULY_PASSWORD=your-password

Huly Cloud, SSO account

HULY_TOKEN=eyJ...          # from `npm run setup`

Self-hosted (see Self-Hosted Huly)

HULY_EMAIL=you@example.com
HULY_PASSWORD=your-password
HULY_ACCOUNTS_URL=https://huly.example.com/_accounts
HULY_FRONT_URL=https://huly.example.com

Restricted to one workspace (legacy)

HULY_EMAIL=you@example.com
HULY_PASSWORD=your-password
HULY_WORKSPACE=acmeteam

HULY_ACCOUNTS_URL vs. HULY_FRONT_URL

These two are easy to mix up. They point to different Huly services:

	HULY_ACCOUNTS_URL	HULY_FRONT_URL
Service	Account service	Front (web front + /files)
Needed for	Everything (login, discovery, workspace selection)	Reading document/issue/organization content; self-hosted uploads
Auth sent	Account token (discovery), workspace token (members)	Workspace token, Authorization: Bearer header
Default	https://account.huly.app	none
Workspace discovery	yes	no

The WebSocket endpoint of each workspace is not configured. It comes from selectWorkspace() (see Multi-Workspace).

HULY_FRONT_URL has two effects

1. Reading content: get_document, get_issue and get_organization only fetch document/description content if it is set. Otherwise they show only the blob reference (get_document/get_issue add a hint to set it).

2. Where uploads go: update_document, create_issue/update_issue with description, update_organization and attach_file/delete_attachment upload/delete blobs:

   • HULY_FRONT_URL set → self-hosted contract POST|DELETE {HULY_FRONT_URL}/files
   • HULY_FRONT_URL unset → Huly Cloud datalake https://dl-eu.huly.app

   On Huly Cloud, setting HULY_FRONT_URL (e.g. https://front.huly.app) to enable content reading therefore also switches uploads to the /files contract. That is how src/utils/storage.ts works today. See Storage / /files.

What is not configurable

• No workspace list and no default workspace: workspaces are discovered, and writes always name theirs.
• No ports for the stdio server. The Docker image's HTTP port is set in the Dockerfile/compose file (8000).
• No logging level. The Huly SDK writes its own diagnostics to stderr (see Troubleshooting).