Skip to content

configuration.md

Latest commit

 

History

History
204 lines (154 loc) · 7.42 KB

configuration.md

File metadata and controls

204 lines (154 loc) · 7.42 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.

Native Artifact Download

Native-file download is disabled by default. Enable it when ChatGPT needs to hand an attached or generated file into an already-open workspace:

DEVSPACE_ARTIFACTS=1 npx @waishnav/devspace serve

This feature supports Linux, macOS, and Windows. Linux uses procfs-backed directory descriptors, macOS uses descriptor-relative filesystem operations, and Windows pins each destination directory with a non-delete-sharing handle while rejecting junctions and other reparse points. The tool is not registered on the remaining BSD platforms.

Variable Default Purpose
DEVSPACE_ARTIFACTS 0 Expose download_artifact for trusted native files.
DEVSPACE_ARTIFACT_MAX_FILE_BYTES 104857600 Maximum streamed size of one file (100 MiB).

The same settings may be persisted in ~/.devspace/config.json as artifactsEnabled and artifactMaxFileBytes.

download_artifact accepts the native file object supplied by the MCP connector, a workspaceId returned by open_workspace, and a relative workspace path. DevSpace safely creates missing parent directories, refuses to overwrite an existing destination, and returns only the normalized workspace-relative path. Windows alternate data streams, device names, ambiguous trailing dots or spaces, and other reserved path segments are rejected. It does not accept conflict modes, expected hashes, arbitrary URL strings, local paths, embedded credentials, or extra object fields.

There is no artifact root, total quota, TTL, pinning, persistent database record, or background artifact cleanup service. See Native File Download for the supported connector shape and security boundaries.

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, file, edit, and shell tools.
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_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 keeps compatibility with:

  • the bundled subagent-delegation skill when DEVSPACE_SUBAGENTS=1, unless ~/.devspace/skills/subagent-delegation/SKILL.md exists
  • DEVSPACE_AGENT_DIR/skills, defaulting to ~/.codex/skills
  • additional paths from DEVSPACE_SKILL_PATHS

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/thinking 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 subagent-delegation skill teaches the model to use only the minimal devspace agents ls, devspace agents run, and devspace agents show workflow.

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_ARTIFACTS="1" \
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.