Configuration

AgentHub configuration is split by responsibility. Keep local execution settings close to Desktop/Edge, keep identity and team settings in Hub, and keep provider credentials out of frontend code.

Configuration Layers

Local Desktop And Edge

For local preview, Desktop should point to a loopback Local Edge endpoint such as 127.0.0.1:3210. Edge should be configured with an explicit workspace allowlist before it starts a runtime adapter.

Recommended local defaults:

• bind Local Edge to loopback only;
• use a mock runtime for UI and event verification;
• use Claude Code, Codex, or OpenCode only after the CLI is installed and authenticated locally;
• emit run events even when a runtime fails, times out, or requires approval;
• keep local workspace paths out of screenshots, public docs, issue comments, and browser storage.

Hub And Web

Hub is the product boundary for identity sessions, projects, devices, routing, and audit. Web is a Hub-backed collaboration surface and must not bypass Hub to reach Local Edge or local files.

Hub/Web configuration should answer:

Runtime Profiles

A runtime profile connects an Agent Profile to an adapter implementation. A useful profile should declare:

• display name and purpose;
• adapter kind, such as mock, Claude Code, Codex, OpenCode, or custom;
• allowed workspaces and approval policy;
• model/provider requirements without exposing the actual key;
• timeout, cancellation, and retry behavior;
• event capabilities, including messages, tool calls, diffs, artifacts, and approvals.

Profiles should be small enough to review. If a profile needs broad filesystem access, privileged commands, or hidden provider credentials, treat it as a security review item, not a normal preset.

A public-doc-safe profile example should show structure only, without real paths or secrets:

{
  "id": "codex-local",
  "label": "Codex Local",
  "adapter": "codex",
  "edge": "http://127.0.0.1:3210",
  "workspacePolicy": "allowlist",
  "approval": {
    "write": "ask",
    "shell": "ask"
  },
  "events": ["run.message.delta", "run.tool.call", "run.diff.ready", "run.approval.requested", "run.completed"]
}

Real profiles may add a local adapter path or provider environment variable names, but never the actual key values. Do not put those values in configuration files, public docs, or browser storage.

Configuration Inventory

Use this inventory when wiring the local path or reviewing a PR. Exact source filenames may change with implementation; ownership and validation should not.

Environment Ownership

Keep environment variables separated by owner. Do not use a single .env file to carry every website, Hub, Edge, and runtime secret:

Example Local Configuration

A public-safe local example can show intent without exposing private paths or secrets:

{
  "desktop": {
    "edgeUrl": "http://127.0.0.1:3210",
    "language": "auto",
    "theme": "system"
  },
  "edge": {
    "bind": "127.0.0.1:3210",
    "workspacePolicy": "allowlist",
    "workspaces": ["workspace_123"],
    "defaultRuntime": "mock"
  },
  "profiles": [
    {
      "id": "mock-local",
      "adapter": "mock",
      "approval": { "write": "ask", "shell": "deny" }
    }
  ]
}

When replacing the mock runtime with Claude Code, Codex, or OpenCode, keep the CLI login and provider credentials in the local environment or secret store owned by that runtime. The AgentHub profile should reference only the adapter and the required environment variable names.

Feature Flags

Feature flags should be explicit because several product surfaces are at different maturity stages.

Avoid hidden flags that silently enable local filesystem access, shell commands, provider credentials, or remote routing. Any feature that changes the trust boundary should be documented in Security, Product Status, and Roadmap.

Secrets

Never store these in public docs, frontend bundles, browser storage, screenshots, or Feishu/Lark card payloads:

• model provider API keys;
• TokenDance ID client secrets;
• Hub session signing secrets;
• Feishu/Lark verification token, encrypt key, app secret, tenant token, or OAuth refresh token;
• production host names, SSH aliases, web roots, backup paths, and rollback commands.

TokenDance API keys authenticate model API calls. They are not AgentHub login credentials and must not be used as browser sessions.

Validation

Before sharing a configuration with another team member:

1. Start Local Edge and confirm the health check succeeds.
2. Start Desktop and confirm it connects to the expected Edge.
3. Run a mock task and verify run.started, run.message.delta, and terminal run state events.
4. Run a real runtime only after local credentials are already configured outside the repo.
5. Confirm Web uses Hub as its boundary and does not request local file access directly.
6. Review logs and screenshots for secrets, private absolute paths, and raw model output that should not be published.

Continue with Quickstart for the first local flow, then Security for permission and secret boundaries.