Config

Using the Dropstone JSON config.

You can configure Dropstone using a JSON config file.

Format

Dropstone supports both JSON and JSONC (JSON with Comments) formats.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

Locations

You can place your config in a couple of different locations and they have a different order of precedence.

Note:

Configuration files are merged together, not replaced. Settings from the following config locations are combined. Later configs override earlier ones only for conflicting keys. Non-conflicting settings from all configs are preserved.

For example, if your global config sets autoupdate: true and your project config sets model: "dropstone/dropstone-pro", the final configuration will include both settings.

Precedence order

Config sources are loaded in this order (later sources override earlier ones):

Remote config (from .well-known/dropstone) - organizational defaults
Global config (~/.config/dropstone/dropstone.json) - user preferences
Custom config (DROPSTONE_CONFIG env var) - custom overrides
Project config (dropstone.json in project) - project-specific settings
.dropstone directories - agents, commands, plugins
Managed config files (/Library/Application Support/dropstone/ on macOS) - admin-controlled
macOS managed preferences (.mobileconfig via MDM) - highest priority, not user-overridable

This means project configs can override global defaults, and global configs can override remote organizational defaults. Managed settings override everything.

Note:

The .dropstone and ~/.config/dropstone directories use plural names for subdirectories: agents/, commands/, modes/, plugins/, skills/, tools/. Singular names (e.g. agent/) are also supported for backwards compatibility.

Remote

Organizations can provide default configuration via a .well-known/dropstone endpoint on their domain. Dropstone fetches this automatically on first sign-in for users whose account is enrolled with that organization.

Remote config is loaded first, serving as the base layer. All other config sources (global, project) can override these defaults.

For example, if your organization provides MCP servers that are disabled by default:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

You can enable specific servers in your local config:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global

Place your global Dropstone config in ~/.config/dropstone/dropstone.json. Use global config for user-wide preferences like models and permissions.

For session-level settings (keybinds, scroll, mouse capture), use ~/.config/dropstone/tui.json.

Global config overrides remote organizational defaults.

Per project

Add dropstone.json in your project root. Project config has the highest precedence among standard config files - it overrides both global and remote configs.

For project-specific session settings, add tui.json alongside it.

Tip:

Place project-specific config in the root of your project.

When Dropstone starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.

This is also safe to be checked into Git and uses the same schema as the global one.

Custom path

Specify a custom config file path using the DROPSTONE_CONFIG environment variable.

export DROPSTONE_CONFIG=/path/to/my/custom-config.json
dropstone run "Hello world"

Custom config is loaded between global and project configs in the precedence order.

Managed settings

Organizations can enforce configuration that users cannot override. Managed settings are loaded at the highest priority tier.

File-based

Drop an dropstone.json or dropstone.jsonc file in the system managed config directory:

Platform	Path
macOS	`/Library/Application Support/dropstone/`
Linux	`/etc/dropstone/`
Windows	`%ProgramData%\dropstone`

These directories require admin/root access to write, so users cannot modify them.

macOS managed preferences

On macOS, Dropstone reads managed preferences from the ai.dropstone.managed preference domain. Deploy a .mobileconfig via MDM (Jamf, Kandji, FleetDM) and the settings are enforced automatically.

Dropstone checks these paths:

/Library/Managed Preferences/<user>/ai.dropstone.managed.plist
/Library/Managed Preferences/ai.dropstone.managed.plist

The plist keys map directly to dropstone.json fields. MDM metadata keys (PayloadUUID, PayloadType, etc.) are stripped automatically.

Creating a .mobileconfig

Use the ai.dropstone.managed PayloadType. The Dropstone config keys go directly in the payload dict:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>ai.dropstone.managed</string>
      <key>PayloadIdentifier</key>
      <string>com.example.dropstone.config</string>
      <key>PayloadUUID</key>
      <string>GENERATE-YOUR-OWN-UUID</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>share</key>
      <string>disabled</string>
      <key>server</key>
      <dict>
        <key>hostname</key>
        <string>127.0.0.1</string>
      </dict>
      <key>permission</key>
      <dict>
        <key>*</key>
        <string>ask</string>
        <key>bash</key>
        <dict>
          <key>*</key>
          <string>ask</string>
          <key>rm -rf *</key>
          <string>deny</string>
        </dict>
      </dict>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadIdentifier</key>
  <string>com.example.dropstone</string>
  <key>PayloadUUID</key>
  <string>GENERATE-YOUR-OWN-UUID</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

Generate unique UUIDs with uuidgen. Customize the settings to match your organization's requirements.

Deploying via MDM

Jamf Pro: Computers > Configuration Profiles > Upload > scope to target devices or smart groups
FleetDM: Add the .mobileconfig to your gitops repo under mdm.macos_settings.custom_settings and run fleetctl apply

Verifying on a device

Double-click the .mobileconfig to install locally for testing (shows in System Settings > Privacy & Security > Profiles), then run:

dropstone debug config

All managed preference keys appear in the resolved config and cannot be overridden by user or project configuration.

Schema

The main config schema is defined in dropstone.io/config.json.

Session-level config (tui.json) uses dropstone.io/tui.json.

Your editor should be able to validate and autocomplete based on the schema.

Session config

Use a dedicated tui.json (or tui.jsonc) file for session-level settings: scroll behaviour, mouse capture, diff rendering, and so on.

{
  "$schema": "https://dropstone.io/schema/tui.json",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true
}

Legacy theme, keybinds, and session-related keys in dropstone.json are deprecated and automatically migrated when possible.

Server

You can configure server settings for the dropstone serve and dropstone web commands through the server option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Available options:

port - Port to listen on.
hostname - Hostname to listen on. When mdns is enabled and no hostname is set, defaults to 0.0.0.0.
mdns - Enable mDNS service discovery. This allows other devices on the network to discover your Dropstone server.
mdnsDomain - Custom domain name for mDNS service. Defaults to dropstone.local. Useful for running multiple instances on the same network.
cors - Additional origins to allow for CORS when using the HTTP server from a browser-based client. Values must be full origins (scheme + host + optional port), eg https://app.example.com.

Learn more about the server here.

Shell

You can configure the shell used for the interactive terminal using the shell option. Compatible shells are also used for agent tool calls.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "shell": "pwsh"
}

If not specified, Dropstone will automatically discover and use a sensible default based on your operating system (e.g. pwsh or cmd.exe on Windows, /bin/zsh or /bin/bash on macOS/Linux). You can provide an absolute path or a short name.

Tools

You can manage the tools an LLM can use through the tools option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Learn more about tools here.

Model

Set your default model with the model option. Dropstone ships three tiers:

Tier	Model ID
Fast	`dropstone/dropstone-fast`
Pro	`dropstone/dropstone-pro`
Heavy	`dropstone/dropstone-heavy`

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro"
}

Pin a default reasoning depth with variant:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "variant": "high"
}

Valid variant values are low, medium, high, xhigh. See Models for the full breakdown.

The small_model option configures a separate model for lightweight tasks like title generation. By default Dropstone picks an appropriate tier; you can override it explicitly:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "dropstone/dropstone-pro",
  "small_model": "dropstone/dropstone-fast"
}

Agents

You can configure specialized agents for specific tasks through the agent option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "dropstone/dropstone-pro",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

You can also define agents using markdown files in ~/.config/dropstone/agents/ or .dropstone/agents/. Learn more here.

Default agent

You can set the default agent using the default_agent option. This determines which agent is used when none is explicitly specified.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "default_agent": "plan"
}

The default agent must be a primary agent (not a subagent). This can be a built-in agent like "build" or "plan", or a custom agent you've defined. If the specified agent doesn't exist or is a subagent, Dropstone will fall back to "build" with a warning.

This setting applies across all interfaces: interactive sessions, one-shot runs (dropstone run), and the GitHub Action.

Commands

You can configure custom commands for repetitive tasks through the command option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "dropstone/dropstone-fast",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

You can also define commands using markdown files in ~/.config/dropstone/commands/ or .dropstone/commands/. Learn more here.

Keymap

Customize keyboard shortcuts in tui.json with keymap.

{
  "$schema": "https://dropstone.io/schema/tui.json",
  "keymap": {
    "sections": {
      "global": {
        "command.palette.show": "ctrl+p"
      }
    }
  }
}

keymap is merged with built-in defaults, so you only need to configure the shortcuts you want to change.

The older keybinds field is deprecated and only applies when keymap is not present.

Learn more here.

Snapshot

Dropstone uses snapshots to track file changes during agent operations, enabling you to undo and revert changes within a session. Snapshots are enabled by default.

For large repositories or projects with many submodules, the snapshot system can cause slow indexing and significant disk usage. You can disable snapshots using the snapshot option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "snapshot": false
}

Note that disabling snapshots means changes made by the agent cannot be rolled back through the UI.

Autoupdate

Dropstone will automatically download any new updates when it starts up. You can disable this with the autoupdate option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "autoupdate": false
}

If you don't want updates but want to be notified when a new version is available, set autoupdate to "notify". Notice that this only works if it was not installed using a package manager such as Homebrew.

Formatters

You can enable and configure code formatters through the formatter option. Omit it to keep formatters disabled.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "formatter": true
}

Use an object to keep built-ins enabled while configuring overrides or custom formatters.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Learn more about formatters here.

LSP Servers

You can enable and configure LSP servers through the lsp option. Omit it to keep LSP disabled.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "lsp": true
}

Use an object to keep built-ins enabled while configuring overrides or custom LSP servers.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

Learn more about LSP servers here.

Permissions

By default, dropstone allows all operations without requiring explicit approval. You can change this using the permission option.

For example, to ensure that the edit and bash tools require user approval:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Learn more about permissions here.

Compaction

You can control context compaction behavior through the compaction option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

auto - Automatically compact the session when context is full (default: true).
prune - Remove old tool outputs to save tokens (default: true).
reserved - Token buffer for compaction. Leaves enough window to avoid overflow during compaction

Watcher

You can configure file watcher ignore patterns through the watcher option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Patterns follow glob syntax. Use this to exclude noisy directories from file watching.

MCP servers

You can configure MCP servers you want to use through the mcp option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "mcp": {}
}

Learn more here.

Plugins

Plugins extend Dropstone with custom tools, hooks, and integrations.

Place plugin files in .dropstone/plugins/ or ~/.config/dropstone/plugins/. You can also load plugins from npm through the plugin option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "plugin": ["@my-org/custom-plugin", "./local-plugin.ts"]
}

Learn more here.

Instructions

You can configure the instructions for the model you're using through the instructions option.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

This takes an array of paths and glob patterns to instruction files. Learn more about rules here.

Experimental

The experimental key contains options that are under active development.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "experimental": {}
}

Unstable:

Experimental options are not stable. They may change or be removed without notice.

Variables

You can use variable substitution in your config files to reference environment variables and file contents.

Env vars

Use {env:VARIABLE_NAME} to substitute environment variables:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "model": "{env:DROPSTONE_MODEL}"
}

If the environment variable is not set, it will be replaced with an empty string.

Files

Use {file:path/to/file} to substitute the contents of a file:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "instructions": ["./custom-instructions.md"]
}

File paths can be:

Relative to the config file directory
Or absolute paths starting with / or ~

These are useful for:

Including large instruction files without cluttering your config.
Sharing common configuration snippets across multiple config files.

Keybindings

Models

Config

Format

Locations

Precedence order

Remote

Global

Per project

Custom path

Managed settings

File-based

macOS managed preferences

Schema

Session config

Server

Shell

Tools

Model

Agents

Default agent

Commands

Keymap

Snapshot

Autoupdate

Formatters

LSP Servers

Permissions

Compaction

Watcher

MCP servers

Plugins

Instructions

Experimental

Variables

Env vars

Files

On this page