> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuple.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Config file

> Configure Tuple agent launches and custom harnesses.

<View title="macOS" icon="apple">
  The `tuple` CLI stores production preferences in `~/.tuple/cli.toml`. Use `tuple connect configure` to choose a default agent and edit launch settings interactively, or edit the file directly.

  Tuple creates the containing directory with permissions `0700` and writes the file with `0600`. A missing file is valid. On a terminal, `tuple connect` asks you to choose a default agent before its first launch. Invalid TOML returns an error with the file path. Saving through Tuple preserves the supported keys described here; keep a backup if you store additional keys in the file.

  ## Environment paths

  | Environment | Configuration |
  | - | - |
  | Production | `~/.tuple/cli.toml` |
  | Staging | `~/.tuplestaging/cli.toml` |
  | Development | `~/.tupledev/cli.toml` |

  The selected Tuple environment determines the file. Keep the executable, app socket, and configuration environment aligned.

  ## Launch settings

  `default_harness` selects an agent when `--harness` is omitted. Each `[harness.<key>]` table stores settings for a built-in agent or defines a custom agent.

  Built-in keys include `claude`, `codex`, `cursor`, `copilot`, `opencode`, `pi`, `droid`, and `prime-agent`.

  | Key | Value |
  | - | - |
  | `model` | Model name passed through the agent's supported model option |
  | `reasoning` | Reasoning setting passed through the agent's supported option |
  | `extra_args` | Array of additional arguments inserted before prompt arguments |
  | `command` | Custom executable and argument template |
  | `url` | Custom URL template |

  `--model` and `--reasoning` on `tuple connect` override saved values for one launch. Support depends on the chosen agent. Tuple warns on stderr when it cannot apply an option.

  Command-based agents can use saved `model`, `reasoning`, and `extra_args` settings. URL templates ignore these settings, so `tuple connect configure` skips their launch-setting questions.

  ```toml theme={null}
  default_harness = "claude"

  [harness.claude]
  model = "sonnet"
  extra_args = ["--verbose"]
  ```

  ## Harness entries

  For a built-in agent, set launch options without `command` or `url`. To define a custom agent, choose one template type. A custom entry using a built-in key overrides that built-in agent.

  An executable template replaces `{PROMPT}` with the generated prompt. If the placeholder is absent, Tuple appends the prompt as a final argument.

  ```toml theme={null}
  [harness.review]
  command = ["/usr/local/bin/review-agent", "--initial-message", "{PROMPT}"]
  ```

  Launch it with `tuple connect --harness review`.

  A URL template opens through the platform's URL handler. Tuple URL-encodes the prompt before substituting `{PROMPT}`:

  ```toml theme={null}
  [harness.custom-web-agent]
  url = "https://agent.example.com/new?prompt={PROMPT}"
  ```

  Set exactly one of `command` and `url` for a custom agent.
</View>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.