Skip to content

configuration.md

Latest commit

 

History

History
178 lines (134 loc) · 6.43 KB

configuration.md

File metadata and controls

178 lines (134 loc) · 6.43 KB
Raw

Configuration Reference

DevSpace can be configured through devspace init, persisted config files, or environment variables.

The default files are:

~/.devspace/config.json
~/.devspace/auth.json

Use another config directory with:

DEVSPACE_CONFIG_DIR=/path/to/config npx @waishnav/devspace serve

Commands

npx @waishnav/devspace init
npx @waishnav/devspace serve
npx @waishnav/devspace doctor
npx @waishnav/devspace config get
npx @waishnav/devspace config set publicBaseUrl https://devspace.example.com

Core Environment Variables

Variable Purpose
HOST Local bind host. Defaults to 127.0.0.1.
PORT Local port. Defaults to 7676.
DEVSPACE_ALLOWED_ROOTS Comma-separated local roots that workspaces may open.
DEVSPACE_PUBLIC_BASE_URL Public origin for the server, without /mcp.
DEVSPACE_ALLOWED_HOSTS Optional Host header allowlist override.
DEVSPACE_OAUTH_OWNER_TOKEN Owner password for OAuth approval. Must be at least 16 characters.
DEVSPACE_WORKTREE_ROOT Directory for managed Git worktrees. Defaults to ~/.devspace/worktrees.
DEVSPACE_STATE_DIR Directory for SQLite state. Defaults to ~/.local/share/devspace.

OAuth

DevSpace uses a single-user OAuth approval flow.

Variable Default
DEVSPACE_OAUTH_ACCESS_TOKEN_TTL_SECONDS 3600
DEVSPACE_OAUTH_REFRESH_TOKEN_TTL_SECONDS 2592000
DEVSPACE_OAUTH_SCOPES devspace
DEVSPACE_OAUTH_ALLOWED_REDIRECT_HOSTS chatgpt.com,localhost,127.0.0.1

MCP clients discover metadata from:

/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server

Tool Modes

DEVSPACE_TOOL_MODE controls the tool surface.

Value Behavior
minimal Default. Exposes open_workspace, read, write, edit, and bash. Clients use bash with tools such as rg, find, and ls for inspection.
full Exposes the minimal tools plus dedicated grep, glob, and ls tools.
codex Experimental. Exposes open_workspace, read, apply_patch, exec_command, and write_stdin. Existing mutation and shell tools are hidden.

DEVSPACE_MINIMAL_TOOLS remains a backward-compatible alias when DEVSPACE_TOOL_MODE is unset: 1 selects minimal and 0 selects full. The codex mode must be selected through DEVSPACE_TOOL_MODE and always uses its fixed short tool names regardless of DEVSPACE_TOOL_NAMING.

Codex-mode commands run without a PTY by default. Set tty: true on exec_command for interactive terminal programs. PTY support uses the optional node-pty dependency; write_stdin can send input, poll output, and resize PTY sessions.

Widgets

DEVSPACE_WIDGETS controls ChatGPT Apps iframe usage.

Value Behavior
full Default. Widget UI is attached to exposed workspace, workflow, file, edit, and shell tools, including read-only live workflow dashboards.
changes Enables the aggregate show_changes tool and attaches widget UI to open_workspace and show_changes.
off Disables widget UI.

Skills

Variable Purpose
DEVSPACE_SKILLS Set to 0 to hide skills. Enabled by default.
DEVSPACE_SUBAGENTS Set to 1 to expose configured agent profiles as Subagents. Experimental and disabled by default.
DEVSPACE_WORKFLOWS Experimental Dynamic Workflows gate. When unset, it follows the effective Subagents setting, including persisted config and any environment override.
DEVSPACE_AGENT_DIR Defaults to ~/.codex; its skills child is loaded for compatibility.
DEVSPACE_SKILL_PATHS Optional comma-separated additional skill directories.

DevSpace discovers standard Agent Skills from:

  • ~/.agents/skills
  • project .agents/skills
  • ~/.devspace/skills

It also includes:

  • the package-managed subagents skill when the Subagents capability is enabled
  • the package-managed dynamic-workflows skill when the Dynamic Workflows capability is enabled
  • DEVSPACE_AGENT_DIR/skills, defaulting to ~/.codex/skills
  • additional paths from DEVSPACE_SKILL_PATHS

User and project skills with the same name take precedence over bundled skills. DevSpace does not copy bundled skills into ~/.devspace/skills during setup.

When Subagents are enabled, DevSpace discovers agent profiles from:

  • ~/.devspace/agents/*.md
  • project .devspace/agents/*.md

open_workspace returns a compact catalog containing profile names, descriptions, providers, and optional models/effort levels so the host model can choose an agent without reading provider-specific launch details. devspace agents ls lists existing subagent sessions for the current workspace, scoped by the workspace environment injected into shell commands. The subagents skill teaches the model to discover targets with devspace agents targets, then use the minimal devspace agents run, devspace agents show, and devspace agents ls workflow.

Provider availability is detected at runtime. DevSpace does not persist probe timestamps, availability snapshots, or an experimental provider enable-list in config.json. Final provider policy and onboarding are deferred until the Subagents and Dynamic Workflows features are finalized.

Starter profile templates are available under examples/agents/. Copy or adapt them into one of the active profile directories before use.

Legacy project paths such as .pi/skills can be added through DEVSPACE_SKILL_PATHS when needed.

Example:

DEVSPACE_SKILL_PATHS="$HOME/.claude/skills,$HOME/company/skills" \
npx @waishnav/devspace serve

Logging

Variable Default
DEVSPACE_LOG_LEVEL info
DEVSPACE_LOG_FORMAT json
DEVSPACE_LOG_REQUESTS 1
DEVSPACE_LOG_ASSETS 0
DEVSPACE_LOG_TOOL_CALLS 1
DEVSPACE_LOG_SHELL_COMMANDS 0
DEVSPACE_TRUST_PROXY 0

Set DEVSPACE_LOG_FORMAT=pretty for local debugging.

Set DEVSPACE_LOG_SHELL_COMMANDS=1 only when you intentionally want command previews in logs.

Env-Only Example

DEVSPACE_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" \
DEVSPACE_ALLOWED_ROOTS="$HOME/personal,$HOME/work" \
DEVSPACE_PUBLIC_BASE_URL="https://devspace.example.com" \
DEVSPACE_WORKTREE_ROOT="$HOME/.devspace/worktrees" \
DEVSPACE_TOOL_MODE="minimal" \
DEVSPACE_WIDGETS="full" \
npx @waishnav/devspace serve

The environment assignments must be part of the same command invocation, or exported first.