> ## Documentation Index
> Fetch the complete documentation index at: https://docs.randomlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
> Customize Slate's behavior with slate.json
We support `--dangerously-skip-permissions` (alias: `--yolo`) to bypass permission prompts. See **Permissions** at the bottom of this page.
Slate can be configured using a `slate.json` (or `slate.jsonc`) file placed in your project root or global config directory.
```jsonc theme={null}
{
"$schema": "https://randomlabs.ai/config.json",
"permission": {
"*": "allow",
"bash": "ask"
}
}
```
## File locations
Configuration files are **merged together**, not replaced. Settings from all sources are combined — later sources override only conflicting keys.
User-wide preferences at `~/.config/slate/slate.json`. Applies to all projects.
`slate.json` in your project root (or any parent up to the git root). Safe to check into git.
`SLATE_CONFIG_CONTENT` env var as a JSON string. Highest precedence.
Project config applies only to that project. Global config applies everywhere.
## Options
Keybind syntax supports `ctrl`, `alt` (also `meta`/`option`), `shift`, and `super`, plus `` combos. Use commas for alternatives (for example, `ctrl+n,down`), `none` to disable a binding, and note leader mode times out after 2s.
Theme config supports built-in `dark` and `light`, with `/theme` as the in-app picker. Advanced theme JSON can define `defs` and `theme` with `$ref` values and per-token `dark`/`light` variants.
| Field | Type | Description |
| --------- | --------- | ------------------------------------------- |
| `privacy` | `boolean` | Disables telemetry and logging when `true`. |
Control which actions require your approval before Slate proceeds.
```json theme={null}
{
"$schema": "https://randomlabs.ai/config.json",
"permission": {
"*": "allow",
"bash": "ask",
"read": {
"*.env": "ask",
"*": "allow"
}
}
}
```
Each permission key maps to an action (`"allow"`, `"ask"`, or `"deny"`), or a pattern object for fine-grained control.
| Permission | Description |
| ----------- | ----------------------------------------- |
| `*` | Wildcard — sets the default for all tools |
| `read` | Reading files |
| `edit` | Writing / editing files |
| `bash` | Running shell commands |
| `grep` | Searching file contents |
| `webfetch` | Fetching web pages |
| `websearch` | Web searches |
Set preferred default models for each slot.
```json theme={null}
{
"$schema": "https://randomlabs.ai/config.json",
"models": {
"main": { "default": "anthropic/claude-opus-4.6" },
"subagent": { "default": "anthropic/claude-sonnet-4.6" },
"search": { "default": "anthropic/claude-haiku-4.5" },
"reasoning": { "default": "openai/gpt-5.3-codex" }
}
}
```
| Slot | Config key | Description |
| ------------------ | ------------------ | -------------------------------------------------------------------------- |
| Main | `models.main` | Primary model for the main agent |
| Subagent (Execute) | `models.subagent` | Execution-oriented subagents — edits, commands, task completion |
| Subagent (Search) | `models.search` | Search-oriented subagents — exploration, retrieval, codebase investigation |
| Reasoning | `models.reasoning` | Complex reasoning tasks |
| Vision | `models.vision` | Vision-enabled multimodal tasks |
| Image Gen | `models.image_gen` | Image generation tasks |
Connect Model Context Protocol servers for additional tools.
```json Local Server theme={null}
{
"$schema": "https://randomlabs.ai/config.json",
"mcp": {
"my-tool": {
"type": "local",
"command": ["npx", "-y", "@my-org/mcp-server"],
"environment": { "API_KEY": "{env:MY_API_KEY}" },
"enabled": true
}
}
}
```
```json Remote Server theme={null}
{
"$schema": "https://randomlabs.ai/config.json",
"mcp": {
"my-remote": {
"type": "remote",
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer {env:MY_TOKEN}" },
"enabled": true
}
}
}
```
Define custom `/commands` for repetitive tasks.
```jsonc theme={null}
{
"$schema": "https://randomlabs.ai/config.json",
"command": {
"commit": {
"description": "Write a commit message for staged changes",
"template": "Write a concise git commit message for these changes: $ARGUMENTS",
"agent": "build"
},
"review": {
"description": "Review the code in a file",
"template": "Review @$ARGUMENTS for correctness, clarity, and edge cases."
}
}
}
```
Invoke with `/commit` or `/review` in the TUI. `$ARGUMENTS` captures text typed after the command name.
Additional configuration keys supported in `slate.json`. Some are partially wired and may evolve.
| Key | Type | Description |
| -------------------- | ----------------------- | ------------------------------------------------------------------ |
| `terminal` | `object` | Terminal/PTY settings (e.g., `maxConcurrent`) |
| `externalWorkspaces` | `string[]` | Default external workspace paths attached to new sessions |
| `experimental` | `object` | Experimental toggles and feature flags |
| `dataTier` | `"normal" \| "privacy"` | Data retention tier |
| `autoupdate` | `boolean \| "notify"` | Auto-update behavior |
| `server` | `object` | Server-mode configuration (forward-compatibility, partially wired) |
| `modelSets` | `object[]` | Named presets bundling model + thinking level per slot |
| `skills` | `object` | Additional skill folder paths |
| `watcher` | `object` | File watcher ignore patterns |
| `instructions` | `string[]` | Extra instruction files or patterns to include |
***
## Environment variables
| Variable | Description |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SLATE_API_KEY` | Skip the authentication dialog on launch |
| `SLATE_CONFIG` | Path to a custom config file |
| `SLATE_CONFIG_DIR` | Path to a custom config directory |
| `SLATE_CONFIG_CONTENT` | Inline JSON config (highest precedence) |
| `SLATE_PERMISSION` | JSON permission config override |
| `SLATE_DISABLE_PROJECT_CONFIG` | Disable project-level `slate.json` discovery |
| `SLATE_DANGEROUSLY_SKIP_PERMISSIONS` | Set to `1` to bypass all permission checks (hard bypass). Also set automatically by `--dangerously-skip-permissions` / `--yolo`. To restore normal permissions, restart without `--yolo` and set this env var to `0` (or unset it). ⚠️ Skips all safeguards including destructive operations. |
***
## CLI flags
Run `slate --help` to see all available flags.
| Flag | Alias | Description |
| --------------- | ----- | ------------------------------------------------------------------------------------------------------- |
| `--continue` | `-c` | Resume the most recent session instead of starting a new one. Useful for picking up where you left off. |
| `--resume ` | | Resume a specific session by its session ID. |
| `--recent` | `-r` | Open the session picker on launch so you can choose which past session to load. |
| Flag | Alias | Description |
| ----------------- | ----- | -------------------------------------------------------------------------------------------------- |
| `` | | Pass a prompt directly as a positional argument. Slate runs the prompt and exits after completion. |
| `--prompt ` | `-p` | Start interactive mode with an initial prompt. |
| Flag | Alias | Description |
| ---------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `--queue ` | `-q` | Load a markdown file and queue messages separated by `---` delimiters. Each block between `---` lines becomes a separate queued message. |
| Flag | Alias | Description |
| -------------------- | ----- | --------------------------------------------------------------------------------------------------------- |
| `--workspace ` | `-w` | Add a directory to Slate's workspace. Can be specified multiple times to add several directories at once. |
Headless mode lets you use Slate non-interactively — pipe in prompts, pipe out structured results — useful for CI or scripting.
| Command / Flag | Description |
| ------------------------------------ | ----------------------------------------------------------------- |
| `run [prompt]` | Run a one-shot prompt non-interactively. |
| `run --output-format ` | Set output format: `text`, `json`, or `stream-json`. |
| `run --input-format ` | Set stdin format: `text` or `stream-json`. |
| `run --workspace ` | Add one or more workspace directories for this run. |
| `run --dangerously-skip-permissions` | Bypass permission checks for automation/CI runs. Alias: `--yolo`. |
Note: use `--output-format stream-json` for JSONL output in this CLI. The standalone `--stream-json` flag is not supported on `run`.
```bash theme={null}
# Run a one-shot prompt and get JSONL output
slate run "Summarize the changes in the last commit" --output-format stream-json
# Pipe a prompt in as plain text
echo "What does this codebase do?" | slate run --output-format json --input-format text
# Pipe JSONL stdin and interpret it as stream-json input
printf '{"role":"user","content":"What changed in the last commit?"}\n' | slate run --output-format json --input-format stream-json
```
Server mode is command-based. Start the server with `serve`, then connect with `attach`.
Upgrade command: `slate upgrade [target]` (optional target version). Use `--method` / `-m` to choose install method: `curl`, `npm`, `pnpm`, `bun`, `brew`, `choco`, or `scoop`.
| Command / Flag | Default | Description |
| -------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| `serve` | | Start Slate as an HTTP API server instead of launching the TUI. |
| `serve --port ` | `7777` | Port to listen on in server mode. |
| `serve --host ` | `0.0.0.0` | Host to bind to in server mode. |
| `attach ` | | Connect the TUI to an already-running Slate server (for example `http://localhost:7777`). |
| `attach --dir ` | local cwd | Set the local working directory while attached to a server. |
| `attach --session ` | | Resume a specific session while attached. |
| `attach --continue` | | Continue the latest session while attached. |
| `attach --fork` | `false` | Fork the session when continuing. Requires `--continue` or `--session`. |
| `attach --password ` | env | Basic auth password for server attach. Alias: `-p`. Defaults to `SLATE_SERVER_PASSWORD` when set. |
```bash theme={null}
# Terminal 1 — start the server
slate serve --port 7777
# Terminal 2 — connect the TUI to it
slate attach http://localhost:7777 --dir /path/to/workspace
```
| Flag | Default | Description |
| -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dangerously-skip-permissions` | `false` | Bypass all permission checks including config plan rules. Alias: `--yolo`. Sets `SLATE_DANGEROUSLY_SKIP_PERMISSIONS=1` internally. Intended for CI pipelines and automation where interactive prompts are not possible. ⚠️ Auto-allows all tool calls including destructive shell commands and file writes. |
Restart without `--yolo` and set `SLATE_DANGEROUSLY_SKIP_PERMISSIONS` to `0` (or unset it) to restore normal permission prompts.
```bash theme={null}
# Run non-interactively with all permissions bypassed
slate run "Run the test suite and fix any failures" --output-format stream-json --dangerously-skip-permissions
```