Environments

An environment is a named bundle of how values — env vars, model defaults, permission overrides, and secret references — that layers and profiles satisfy at apply time. Environments do not replace layers; they parameterize the same context stack for different machines, accounts, or deployment targets.

Context vs environment

See Resources for the full resource-type split.

Cascade (last wins)

On layer apply and profile use, environment values merge with this precedence:

home environment  ◂  layer default environment  ◂  deck active environment

• Home — fragments under ~/.harnesstap/environments/ (optional)
• Layer default — default_environment_id on a configured layer
• Deck active — pointer from environment use (global) or environment use --local (terminal session)

Switch the active environment to change secrets and env vars without rebuilding the layer stack:

ht environment create work --from-layer my-setup --bind
ht environment edit work --secret SLACK_TOKEN:keychain:harnesstap/slack-work
ht environment use work
ht profile use default --reapply

Use environment status to see the active pointer and terminal drift. Use environment show <name> --layer <selector> to find missing keys required by a layer's MCP env vars or plugin needs[].

Environment resource types

Secret ref providers

ht environment edit staging --secret GITHUB_TOKEN:env:GITHUB_TOKEN
ht environment edit staging --secret SLACK_TOKEN:keychain:harnesstap/slack-staging
ht environment edit staging --secret API_KEY:file:/run/secrets/api-key

Secret values are resolved when the cascade is built, merged into the substitution vars map, and never written into layer exports or migrate archives.

MCP servers and environments

MCP server resources are context-side (server URL, command, args). Sensitive values belong in the environment, referenced from MCP metadata with ${VAR} placeholders:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": { "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}" }
    }
  }
}

At apply time, HarnessTap substitutes ${VAR} in MCP command, args, env, url, headers, and auth fields from the resolved cascade (substituteMcpServerMetadata in mcp-config-bridge).

Recommended workflow for switching accounts (static tokens):

1. Create one environment per account (work, personal).
2. Set a secret_ref (or env_var) for each token key the MCP server expects.
3. environment use <name> then profile use / layer apply --reapply (or environment use --reapply when only env changed).

MCP authentication limitations

MCP auth falls into two models. HarnessTap only controls the first.

Static auth (supported)

Credentials live in config or environment variables: API keys, bot tokens, Bearer headers, ${ENV_VAR} / ${env:VAR} expansion.

HarnessTap can switch these across environments via secret_ref + apply. Keep tokens out of committed layers — use placeholders and resolve at apply time.

OAuth 2.1 (host-managed, not switchable via environments)

Remote MCP servers (Linear, Slack hosted MCP, GitHub Copilot MCP, etc.) often use browser OAuth. The host application runs the flow and stores tokens outside MCP config:

OAuth config entries contain server URL and transport only — no access token. HarnessTap cannot swap OAuth sessions by changing environments because:

1. Tokens are not in files HarnessTap materializes.
2. Each host uses a private, undocumented credential schema.
3. OAuth sessions are per host app, not shared across Cursor, Claude Code, and Copilot.
4. Re-auth often requires interactive browser login inside the host.

flowchart LR
  subgraph HD[HarnessTap controls]
    Env[Environment secret_refs]
    McpDef[MCP resource definitions]
    Apply[profile use / layer apply]
  end

  subgraph Disk[On disk]
    McpJson[mcp.json — URL, env placeholders]
  end

  subgraph Host[Host runtime — outside HarnessTap]
    OAuth[OAuth browser flow]
    Store[OS Keychain / host token files]
  end

  Env --> Apply
  McpDef --> Apply
  Apply --> McpJson
  McpJson --> OAuth
  OAuth --> Store

Workarounds for OAuth-heavy setups

Cursor behavior (official docs)

Confirmed against Cursor's published MCP reference:

Cursor's docs state that MCP servers "use environment variables for authentication" and that you should pass API keys through config — consistent with HarnessTap's static-auth / environment model. For SSE and Streamable HTTP, Cursor lists OAuth as the auth column; that session is separate from values in mcp.json.

Harness coverage for environments

Full environment emission (env_var, model_config, permission written to harness settings files) is implemented for Claude Code and Codex only.

Other harnesses still benefit from the cascade for MCP ${VAR} substitution at apply time when their serializer emits MCP config (including Cursor — scan/emit of .cursor/mcp.json and global ~/.cursor/mcp.json). See Known gaps for remaining limitations.

Related

• Resources — context vs environment resource types
• Layers — default_environment_id and needs[]
• Profiles — global apply and home environment pointer
• Portability limits — MCP auth
• Supported harnesses — per-harness MCP and environment matrix
• Command reference — environment

Known gaps and fix plan

Tracked limitations as of the current CLI. Shipped items are resolved in the CLI; medium items extend coverage or UX; hard items need host integration or new product surface.

Shipped — Cursor MCP parity

Medium — coverage and UX

Hard — out of scope for near term

Suggested implementation order

1. Claude global MCP scan (if path is stable).
2. Environment create secret promotion UX.
3. Copilot HTTP MCP auth field audit (if round-trip gaps remain).