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

# cordon setup

> Interactive setup — generates certificates, creates config, and configures integrations.

Interactive setup wizard that detects your project type, generates CA certificates, creates a `cordon.toml` config file, and configures supported integrations. Prefer `cordon setup` over creating `cordon.toml` by hand; setup allocates ports, writes absolute TLS paths, and applies safer defaults consistently.

## Usage

```bash theme={null}
cordon setup [OPTIONS]
cordon setup <claude-code|codex|hermes> [OPTIONS]
```

## Options

| Option            | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `--config`, `-c`  | Path to `cordon.toml` (default: `./cordon.toml`)                            |
| `--yes`           | Skip confirmation prompts (useful for automation and non-interactive setup) |
| `--regenerate-ca` | Regenerate the CA certificate                                               |
| `--trust`         | Add CA to system trust store                                                |
| `--no-trust`      | Skip trust store prompt                                                     |

Bare `cordon setup` is project-scope only. Integration subcommands add their own `--scope` option where supported.

## Examples

```bash theme={null}
# Interactive setup
cordon setup

# Non-interactive setup with trust
cordon setup --yes --trust
```

## Project setup and services

Cordon is project-first. By default, each project has its own `cordon.toml` with its own routes and credentials. A [user scope](/configuration/overview#scopes) is also available for tools that operate across projects.

`cordon setup` writes `./cordon.toml` in the current directory by default, or to the path specified by `--config`. Certificates are stored outside the project tree; see [Scopes](/configuration/overview#scopes) for exact paths.

Setup does not install a background service automatically. In interactive mode it may offer to install one; `--yes` skips service install by default. To run cordon as a launchd/systemd service for a project, install the service explicitly after setup:

```bash theme={null}
cordon service install my-project --config ./cordon.toml
```

See [process management](/guides/process-management) for more on running cordon as a service.

## Integration subcommands

Integrations configure cordon for Claude Code, Codex, or Hermes — setting up the proxy env vars and CA trust settings each integration needs. Each integration knows where that application stores configuration (for example, Claude Code settings, project-local or user Codex config, and Hermes `.env`) and handles setup and teardown automatically.

Currently supported: `claude-code`, `codex`, `hermes`.

<Warning>
  For Codex, Cordon supports API-key authentication only. ChatGPT/OAuth-based Codex sessions may still route through the proxy transport, but Cordon does not replace or manage Codex's ChatGPT auth state.
</Warning>

### `cordon setup claude-code`

Configure cordon for [Claude Code](/guides/claude-code). Runs the [base setup](#what-setup-does) automatically, then writes the standard proxy and CA env vars to Claude Code settings.

```bash theme={null}
cordon setup claude-code
```

To manage the integration later, see [`cordon integration`](/cli/integration).

| Option            | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `--config`, `-c`  | Path to `cordon.toml` (defaults to selected scope's config path)            |
| `--yes`           | Skip confirmation prompts (useful for automation and non-interactive setup) |
| `--trust`         | Add the CA cert to the OS trust store                                       |
| `--no-trust`      | Skip trust store prompt                                                     |
| `--regenerate-ca` | Regenerate the CA certificate                                               |
| `--service`       | Install cordon as a background service at the end of setup                  |
| `--no-service`    | Skip the end-of-setup service install prompt                                |
| `--scope`         | `project` (default) or `user`                                               |

`--service` and `--no-service` are mutually exclusive.

### `cordon setup codex`

Configure cordon for [OpenAI Codex](/guides/codex). Runs the [base setup](#what-setup-does) automatically, then writes the standard proxy and CA env vars to Codex's `.env` and `shell_environment_policy.set` entries in Codex's `config.toml`.

```bash theme={null}
cordon setup codex
```

To manage the integration later, see [`cordon integration`](/cli/integration).

| Option            | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `--config`, `-c`  | Path to `cordon.toml` (defaults to selected scope's config path)            |
| `--yes`           | Skip confirmation prompts (useful for automation and non-interactive setup) |
| `--trust`         | Add the CA cert to the OS trust store                                       |
| `--no-trust`      | Skip trust store prompt                                                     |
| `--regenerate-ca` | Regenerate the CA certificate                                               |
| `--service`       | Install cordon as a background service at the end of setup                  |
| `--no-service`    | Skip the end-of-setup service install prompt                                |
| `--scope`         | `project` (default) or `user`                                               |

`--service` and `--no-service` are mutually exclusive.

<Note>
  Codex filters out `CODEX_*` prefixed variables from its `.env` file, so the setup uses `SSL_CERT_FILE` instead of `CODEX_CA_CERTIFICATE`. The `CODEX_HOME` env var can override the default `~/.codex/` path. For project scope, set `CODEX_HOME="$PWD/.codex"` if you want Codex to load the project-local `.env` for its own startup-time network traffic.
</Note>

When you want Codex to run outside its command sandbox, launch it with:

```bash theme={null}
export CODEX_HOME="$PWD/.codex"
codex --dangerously-bypass-approvals-and-sandbox
```

<Warning>
  Running Codex with `--dangerously-bypass-approvals-and-sandbox` is inherently riskier because model-generated commands run without Codex's normal sandbox boundary.

  We are working on a path that preserves credential protection while supporting fully sandboxed Codex sessions.
</Warning>

### `cordon setup hermes`

Configure cordon for [Hermes Agent](/guides/hermes). Runs the [base setup](#what-setup-does) automatically, then writes the standard proxy and CA env vars to Hermes's `~/.hermes/.env` or `$HERMES_HOME/.env`.

```bash theme={null}
cordon setup hermes
```

To manage the integration later, see [`cordon integration`](/cli/integration).

| Option            | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `--config`, `-c`  | Path to `cordon.toml` (defaults to the user-scope config path)              |
| `--yes`           | Skip confirmation prompts (useful for automation and non-interactive setup) |
| `--trust`         | Add the CA cert to the OS trust store                                       |
| `--no-trust`      | Skip trust store prompt                                                     |
| `--regenerate-ca` | Regenerate the CA certificate                                               |
| `--service`       | Install cordon as a background service at the end of setup                  |
| `--no-service`    | Skip the end-of-setup service install prompt                                |
| `--scope`         | `user` (default). `project` is rejected for Hermes.                         |

`--service` and `--no-service` are mutually exclusive.

<Note>
  The `HERMES_HOME` env var can override the default `~/.hermes/` path. If the directory doesn't exist, setup will warn but still write the `.env` file.
</Note>

## What setup does

Running `cordon setup` without an integration performs the base setup only:

1. Checks platform dependencies — verifies that secret providers can function at runtime (e.g., D-Bus session on Linux for keyring, 1Password CLI sign-in status). Issues are reported as warnings but do not block setup.
2. Detects the project type and language ecosystem
3. Allocates a free listen port and writes it to `cordon.toml`
4. Generates CA certificates at `~/.config/cordon/projects/<namespace>/certs/`
5. Detects available secret providers and adds them to the config (OS Keyring, 1Password CLI)
6. Creates `cordon.toml` with absolute cert paths
7. Prints follow-up guidance for proxy env vars and CA trust

<Tip>
  If you're using Claude Code, Codex, or Hermes, use the [integration subcommands](#integration-subcommands) instead — they run the base setup automatically and then configure the tool's proxy settings in one step.
</Tip>

Use [`cordon env`](/cli/env) for the generated proxy and CA variables, [TLS](/configuration/tls) for trust behavior, and [SDK Compatibility](/guides/sdk-compatibility#runtime-ca-and-proxy-notes) for language-specific runtime notes.

## Certificate storage

Certificates are stored outside your project directory, so they are not at risk of being committed to git with your app code. See [Scopes](/configuration/overview#scopes) for the canonical path table and [TLS](/configuration/tls#security-considerations) for CA private-key handling.

## Multiple projects

Each project gets its own `cordon.toml` with its own listen port, routes, and certificate namespace. Setup allocates a free port automatically; inspect the generated `listen = ...` line in each `cordon.toml` if you need the exact port.

Certificate namespaces are derived from the project directory path, so two projects with the same directory name in different locations get separate cert stores automatically.

If you install background services for multiple projects, use distinct names:

```bash theme={null}
cd ~/project-a && cordon service install project-a --config ./cordon.toml
cd ~/project-b && cordon service install project-b --config ./cordon.toml
```

## Removal recipes

To disable an integration, see [`cordon integration disable`](/cli/integration#cordon-integration-disable).

To remove cordon itself from a machine after all integrations are disabled:

```bash theme={null}
# Remove CA from the system trust store, if present
cordon untrust --config /path/to/cordon.toml

# Remove any installed services
cordon service uninstall my-project
cordon service uninstall                      # uninstalls the current project's service

# Delete cordon-managed data
rm -rf ~/.config/cordon/
```

<Note>
  If you've already deleted `cordon.toml` and the cert files, `cordon untrust` won't be able to locate the CA to remove. In that case, remove it manually — on macOS, open Keychain Access and search for "cordon"; on Linux, remove the cert from `/usr/local/share/ca-certificates/` and run `update-ca-certificates`.
</Note>