Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Meza-dev/Ghostly/llms.txt

Use this file to discover all available pages before exploring further.

Ghostly’s configuration is split across two surfaces: ~/.ghostly/auth.json, which the CLI writes during ghostly keygen / ghostly install / ghostly config, and environment variables injected at runtime. When you run ghostly up, the CLI reads auth.json, converts it to the environment variable map via authToEnv(), then spawns the API process with those variables already set. You only need to set variables manually when building a custom deployment or overriding specific values.
Most variables below are automatically injected by ghostly up from ~/.ghostly/auth.json. Manual configuration is only needed for custom or non-standard deployments.

​
Server

These variables control the HTTP server that powers both the REST API and the static dashboard frontend.
​
API_PORT
number
default:"3000"
TCP port the API server listens on. The raw env var default is 3000, but ghostly up always passes --port 4000 (or the value of the --port flag) explicitly, so the effective default when using the CLI is 4000. Override with ghostly up --port <number>.
​
PORT
number
Fallback port variable. config.ts reads API_PORT ?? PORT ?? "3000". Prefer API_PORT for explicit configuration; PORT is supported for compatibility with hosting platforms that inject it automatically.
​
HOST
string
default:"0.0.0.0"
Network interface the server binds to. The env var default is 0.0.0.0. ghostly up always hardcodes HOST=127.0.0.1 (loopback only) for the spawned process. If you launch the API directly without ghostly up, HOST defaults to 0.0.0.0 — set it explicitly to 127.0.0.1 unless you intend to bind to all interfaces.
Only bind to 0.0.0.0 on a fully trusted, isolated network. The API has no TLS and serves credentials directly.
​
NODE_ENV
string
Runtime mode. Accepts development or production. ghostly up always sets this to production for the spawned server process.
​
DATABASE_URL
string
SQLite connection string in the format file:/absolute/path/to/ghostly.db. Auto-set by ghostly up to the path returned by getDbPath() (typically ~/.ghostly/ghostly.db). Must begin with file:.
​
JWT_SECRET
string
default:"ghostly-secret"
HMAC-SHA256 secret used to sign and verify JWT bearer tokens. The default value is intentionally weak and must be changed in any deployment accessible beyond localhost.
Leaving JWT_SECRET as ghostly-secret in a network-exposed deployment allows anyone who knows the default to forge authentication tokens. Set a high-entropy random string in production.
​
GHOST_WEB_DIR
string
Absolute path to the built web frontend asset directory. Served as static files by the API. Auto-set by ghostly up to the path returned by getWebDistDir().

​
Authentication

These variables identify the local CLI user to the API and configure the API base URL for outbound CLI requests.
​
GHOST_API_KEY
string
The API key used by the CLI and MCP server to authenticate requests against the Ghostly API via the X-Api-Key header. Written to ~/.ghostly/auth.json by ghostly keygen or ghostly install, then injected into the server process environment by ghostly up.
​
GHOST_API_URL
string
default:"http://localhost:4000"
Base URL of the Ghostly API as seen by CLI commands and the MCP server. Stored in ~/.ghostly/auth.json and injected at startup. Change this if you run the server on a non-default port.
​
X_API_KEY
string
Alias for GHOST_API_KEY used specifically by the MCP server process. The server’s auth middleware validates the X-Api-Key request header against the key stored in ~/.ghostly/auth.json; this variable is the environment-level source of that value for MCP tooling.

​
LLM / AI Provider

Ghostly’s AI-assisted E2E engine supports two LLM backends: an HTTP provider (any OpenAI-compatible endpoint) and the Cursor Agent CLI. The variables below configure which is used and how. Many have dual names for backward compatibility — both names are accepted and the primary name takes precedence.
​
ASSIST_LLM_PROVIDER
string
default:"http"
Selects the LLM backend. Accepts http (any OpenAI-compatible REST endpoint) or cursor-cli (local Cursor Agent CLI binary). Stored in ~/.ghostly/auth.json under llm.provider and mapped here by authToEnv(). The alias LLM_PROVIDER is also accepted; ASSIST_LLM_PROVIDER takes precedence.
​
LLM_PROVIDER
string
Backward-compatible alias for ASSIST_LLM_PROVIDER. Set by authToEnv() alongside ASSIST_LLM_PROVIDER. Prefer ASSIST_LLM_PROVIDER in new deployments.
​
ASSIST_LLM_API_URL
string
Base URL of the OpenAI-compatible API when using the http provider. Examples: https://api.openai.com/v1, http://localhost:11434/v1 (Ollama), or an OpenRouter / Azure proxy base URL. Mapped from auth.llm.baseUrl. The alias LLM_BASE_URL is also accepted; ASSIST_LLM_API_URL takes precedence.
​
LLM_BASE_URL
string
Backward-compatible alias for ASSIST_LLM_API_URL. Set by authToEnv() alongside ASSIST_LLM_API_URL. Prefer ASSIST_LLM_API_URL in new deployments.
​
ASSIST_LLM_API_KEY
string
Bearer token sent in the Authorization header for the http provider. Mapped from auth.llm.apiKey. Not required (and not stored) when using the cursor-cli provider. The alias OPENAI_API_KEY is also accepted; ASSIST_LLM_API_KEY takes precedence.
​
OPENAI_API_KEY
string
Backward-compatible alias for ASSIST_LLM_API_KEY. Set by authToEnv() alongside ASSIST_LLM_API_KEY for compatibility with tools that expect the standard OpenAI variable name.
​
ASSIST_LLM_MODEL
string
Model identifier forwarded to the LLM endpoint or Cursor Agent CLI. Examples: gpt-4o, claude-3-5-sonnet-20241022, composer-2.5. Mapped from auth.llm.model. The alias LLM_MODEL is also accepted; ASSIST_LLM_MODEL takes precedence.
​
LLM_MODEL
string
Backward-compatible alias for ASSIST_LLM_MODEL. Set by authToEnv() alongside ASSIST_LLM_MODEL.
​
ASSIST_LLM_TIMEOUT_MS
number
default:"45000"
Per-call timeout in milliseconds for LLM requests. If a call exceeds this duration the provider raises an error and the orchestrator falls back to local heuristics. Consider increasing this to 90000 or more when using the cursor-cli provider, which requires spawning a subprocess.
​
CURSOR_AGENT_BIN
string
default:"agent"
Path to the Cursor Agent CLI binary. Defaults to agent (resolved from PATH). On Windows the typical install path is %LOCALAPPDATA%\cursor-agent\cursor-agent.cmd — set this variable if agent is not on your PATH.
​
CURSOR_AGENT_WORKSPACE
string
default:"process.cwd()"
Working directory passed to the Cursor Agent CLI via --workspace. Defaults to the current working directory of the API process. Set this to your project root if you want the agent to have access to source context.
​
CURSOR_API_KEY
string
Alternative authentication token for the Cursor Agent CLI. When set, this bypasses the requirement for an active agent login session. Useful in CI environments or on Windows where agent login sessions may not persist across terminal restarts.

​
Prisma / DB

​
PRISMA_QUERY_ENGINE_LIBRARY
string
Absolute path to the Prisma query engine .node native library. Auto-set by ghostly up via getPrismaEngineLibraryPath() for global npm installs where the engine is bundled inside the CLI package. Only required if Prisma cannot locate the engine automatically — this is rare in local development.

​
Additional Engine Tuning

These variables let you fine-tune the assisted execution engine. They are read directly from the environment by loadConfig() in apps/api/src/config.ts and are not surfaced through auth.json.
VariableDefaultDescription
ASSIST_ENABLEDtrueSet to false to disable the AI-assist pipeline entirely.
ASSIST_MAX_STEPS25Maximum number of steps the assist planner will generate per run.
ASSIST_MAX_TIMEOUT_MS120000Hard wall-clock timeout for an entire assist run, in milliseconds.
ASSIST_MAX_GOAL_CHARS2000Maximum character length accepted for a natural-language goal string.
VariableDefaultDescription
ASSIST_V2_ENABLEDtrueEnables the V2 horizon-based orchestration pipeline.
ASSIST_V2_CHUNK_SIZE3Number of steps per planning chunk sent to the strategist.
ASSIST_V2_HEALING_ATTEMPTS1Number of self-healing retries per failed selector.
ASSIST_V2_OBSERVER_MAX_NODES300Maximum DOM nodes captured by the observer after each action.
ASSIST_V2_MAX_HORIZONS12Maximum number of planning horizons per run.
ASSIST_V2_STEPS_PER_HORIZON3Target steps to plan within each horizon.
ASSIST_V2_MAX_LOOP_MS300000Maximum total duration of the V2 assist loop in milliseconds.
ASSIST_V2_MODAL_LOADER_MAX_MS180000Maximum wait time for modal/loader elements to settle between horizons.
ASSIST_V2_MEMORY_MODEruntimeMemory strategy: off, runtime (in-memory per run), or adaptive (persists across runs).

​
Example .env File

The following mirrors the structure of .env.example in the repository root. You do not need to create this file for a standard local install — ghostly up injects all required values automatically. 
# Server
API_PORT=3000
HOST=0.0.0.0
NODE_ENV=development
DATABASE_URL=file:/home/youruser/.ghostly/ghostly.db

# Security — change JWT_SECRET before exposing to any network
JWT_SECRET=ghostly-secret

# Frontend assets (auto-set by ghostly up)
# GHOST_WEB_DIR=/path/to/web/dist

# Authentication
GHOST_API_KEY=your-generated-api-key
GHOST_API_URL=http://localhost:4000

# LLM Provider — HTTP (OpenAI-compatible)
ASSIST_LLM_PROVIDER=http
ASSIST_LLM_API_URL=https://api.openai.com/v1
ASSIST_LLM_API_KEY=sk-...
ASSIST_LLM_MODEL=gpt-4o
ASSIST_LLM_TIMEOUT_MS=45000

# Backward-compatible aliases (set automatically by ghostly up via authToEnv())
# LLM_PROVIDER=http
# LLM_BASE_URL=https://api.openai.com/v1
# OPENAI_API_KEY=sk-...
# LLM_MODEL=gpt-4o

# LLM Provider — Cursor Agent CLI (alternative to HTTP)
# ASSIST_LLM_PROVIDER=cursor-cli
# CURSOR_AGENT_BIN=agent
# CURSOR_AGENT_WORKSPACE=/path/to/your/project
# CURSOR_API_KEY=

# Prisma (auto-set by ghostly up for global installs)
# PRISMA_QUERY_ENGINE_LIBRARY=/path/to/query_engine.node
Run ghostly config to configure your LLM provider interactively. The wizard writes the correct values to ~/.ghostly/auth.json and they are automatically picked up the next time you run ghostly up.

Build docs developers (and LLMs) love

Get started for freeTalk to us