jpicklyk/task-orchestrator/configure-server

Configure Server — Runtime & Transport Setup

Decides how the MCP Task Orchestrator container is launched and reached: transport, REST API mode, port publishing, config mount, and config-sync. This is a runtime/deployment concern, distinct from quick-start (first-time onboarding narrative) and manage-schemas (workflow gates/traits/ resources: content inside .taskorchestrator/config.yaml). Who a caller is comes from API_AUTH_MODE and its credentials; this skill renders none and bearer, and links jwks (fleet deployment, REST API, authentication) without rendering it; no config key sets it. If the user wants schema or gate changes — including resource-lease declarations — redirect to /manage-schemas instead of proceeding here.

One operator escape hatch worth knowing when launching the container: RESOURCE_LEASES_ENFORCED=false (env, default true) disables resource-lease gate enforcement server-wide — a kill switch for lease contention incidents. Configuring which resources exist and which traits declare them stays in /manage-schemas; this skill only knows the switch.

Not a director-mode skill: run it outside director mode (/task-orchestrator:director off); director-guard denies its file, shell and config steps partway through.

The full fragment catalog (exact env tuples, loopback caveat, Windows/MSYS caveat, .mcp.json shapes) lives in references/runtime-config.md — this skill's job is the decision flow and rendering, not re-deriving that catalog. Read it before rendering any command.

Step 0 - Upgrading from 3.x (only when it applies)

Enter this step when the user mentions upgrading, or an existing mcp-task-data volume or container is in play. Ask; docker ps -a and docker volume ls are allowed to look (outside director mode). A new install skips to Step 1. The image tag :latest moves to 4.x, so a 3.x install that pulls latest upgrades whether or not anyone planned it: run this step first. The plugin and the server majors must match: a 4.x plugin needs a 4.x server that advertises seats.

In order:

1. Stop every 3.x process that uses the volume, stdio sessions included.
2. Back up the whole volume off-volume. The automatic .pre-4.0.*.bak copy sits on the same volume, so it is not a backup.
3. Clear the settings that fail startup: remove a leftover actor_authentication: or auditing: key from the mounted global config, and unset DEGRADED_MODE_POLICY. The legacy schema_resolution, orchestration, retrospective and actor_attribution keys only warn; USE_FLYWAY is ignored.
4. Start ONE detached 4.0 container and wait until it is healthy (the docker inspect health loop of the fleet guide; raise --start-period for a large database). The once-only data steps, including the irreversible type-backfill, run at this first boot.
5. When REST is on, read `/api/v1/info` and check configWarnings.
6. Then register the clients (Steps 1-6).

Commands and rollback are in fleet deployment, Upgrading from 3.x; do not copy them here.

Step 1 — Offer the recommended default first

Before walking the full decision tree, offer the one-tap recommended path via AskUserQuestion:

AskUserQuestion(questions: [{
  question: "How do you want to run the server?",
  header: "Server setup",
  multiSelect: false,
  options: [
    { label: "Recommended default", description: "HTTP + REST API enabled, unauthenticated, loopback-bound (127.0.0.1). Enables config-sync out of the box. Best for a single developer working across multiple projects." },
    { label: "Customize", description: "Walk through transport, REST mode, config mount, and debug logging one at a time." }
  ]
}])

Recommended default → skip straight to Step 5 (Render — HTTP) with: REST = unauthenticated, config mount = process-schema floor, debug = off. Customize → Step 2.

Why this is the default: it is the majority deployment shape for a single developer who wants config-sync (per-project config that hot-reloads without a restart) to just work across every project they open, without hand-managing tokens. The image itself still ships conservative (STDIO, REST off, 0.0.0.0 bind) — this posture is entirely rendered by this skill, never an image change.

Step 2 — Transport

AskUserQuestion(questions: [{
  question: "Which transport?", header: "Transport", multiSelect: false,
  options: [
    { label: "HTTP (Recommended)", description: "Detached daemon, serves /mcp on a published port. Required for REST API and config-sync." },
    { label: "STDIO", description: "Per-session process, no port, no REST API, no config-sync. Simpler, no persistent daemon." }
  ]
}])

STDIO ⊥ REST — hard constraint: if the user picks STDIO, skip Steps 3-4 entirely (REST mode and port are incoherent for a --rm -i per-session process) and go straight to Step 5 (Render — STDIO). Tell the user plainly: "STDIO has no REST API and no config-sync — those require a persistent HTTP daemon. If you want config-sync later, re-run this skill and choose HTTP."

HTTP → Step 3.

Step 3 — REST API mode (HTTP only)

AskUserQuestion(questions: [{
  question: "REST API mode?", header: "REST API", multiSelect: false,
  options: [
    { label: "Unauthenticated (Recommended)", description: "No token needed. Loopback-bound only. Enables config-sync with zero extra setup. Every caller is the local agent principal, so human-only decisions cannot be answered." },
    { label: "Bearer token", description: "Token-authenticated. For shared/multi-user setups. The same token also guards /mcp." },
    { label: "Off", description: "MCP only, no REST, no config-sync. /mcp then serves every caller unauthenticated, so it needs an explicit opt-in." }
  ]
}])

• Unauthenticated → always render the loopback SECURITY caveat from references/runtime-config.md

("Loopback footgun") before the command, and force -p 127.0.0.1:3001:3001 in the render — never a wider publish.

• Bearer → ask for the host path to the token YAML (free-text/"Other" answer), e.g.

~/.taskorchestrator-secrets/api-tokens.yaml. If the file doesn't exist yet, point at current/docs/api-rest.md §1 for the token-generation snippet — this skill does not generate tokens.

• Unauthenticated and Off both: every caller is the local agent principal (proof none), so a human-only decision class can never be answered; director-or-human classes (run budget, attempt cap, deviation) can, through the director entry. A user who wants human sign-off needs Bearer with a kind: human token (see "Director credential").
• Off → REST fragment is -e API_ENABLED=false -e MCP_ALLOW_UNAUTHENTICATED=true; config-sync will

no-op (tell the user). Without the opt-in, an HTTP server with the API off refuses to start (MCP_AUTH, fleet deployment); with it, /mcp serves every caller as the local principal, so render the loopback SECURITY caveat here too and keep -p 127.0.0.1:3001:3001. The recommended default keeps the API on and needs no opt-in.

Step 4 — Config mount and debug (HTTP only)

AskUserQuestion(questions: [{
  question: "Mount the process-schema floor as the server's global config?", header: "Config mount", multiSelect: false,
  options: [
    { label: "Process-schema floor (Recommended)", description: "Mount the floor config read-only as AGENT_CONFIG_DIR: the shared process schemas (project anchor, observations, retrospectives, proposals, containers). Per-project config still flows in via config-sync per root." },
    { label: "None", description: "No mount. Warning: with no server config a depth-0 create (and any root with no config of its own) accepts every type schema-free, so a project anchor can auto-complete and retrospective/proposal items have no required notes." }
  ]
}])

Do not offer to mount a project's own .taskorchestrator as a fallback: a mounted file that carries project.rootId is imported into that root, not the server scope, and fails startup when the database lacks that root. Project config reaches the server through config-sync, never the mount.

The floor directory (<FLOOR_DIR>) is resolved in Step 5 (it is needed on every path that mounts the floor, including the recommended default).

Then ask Yes/No for debug logging (LOG_LEVEL=DEBUG + DATABASE_SHOW_SQL=true).

Step 5 — Render

Look up the exact fragments in references/runtime-config.md — do not improvise env values.

Resolve `<FLOOR_DIR>` first whenever the floor is mounted (the recommended default, a Step 4 "Process-schema floor" answer, or STDIO). It is <checkout>/deploy/global-config/.taskorchestrator in a source checkout. Otherwise it is a host directory the user downloads the file into (the image bakes no config); render the command for them, for example:

mkdir -p <FLOOR_DIR> && curl -fsSL -o <FLOOR_DIR>/config.yaml https://raw.githubusercontent.com/jpicklyk/task-orchestrator/main/deploy/global-config/.taskorchestrator/config.yaml

On Windows (PowerShell):

New-Item -ItemType Directory -Force <FLOOR_DIR>; Invoke-WebRequest -Uri https://raw.githubusercontent.com/jpicklyk/task-orchestrator/main/deploy/global-config/.taskorchestrator/config.yaml -OutFile <FLOOR_DIR>/config.yaml

STDIO

Render the .mcp.json args array shape (see reference doc, ".mcp.json shapes"):

{
  "mcpServers": {
    "mcp-task-orchestrator": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "mcp-task-data:/app/data", "ghcr.io/jpicklyk/task-orchestrator:latest"]
    }
  }
}

Add the floor config-mount fragment (as args entries, not env flags: "-v", "<FLOOR_DIR>:/project/.taskorchestrator:ro", "-e", "AGENT_CONFIG_DIR=/project") by default (Step 4's config-mount question is HTTP only and is not asked here); leave it out only if the user asks for no mount. No REST, no port, no config-sync — say so. When asked, or when this skill runs standalone, also render the stdio director entry from references/runtime-config.md (.mcp.json shapes): the same docker run args with -e MCP_TOOL_PROFILE=director before the image, under the key mcp-task-orchestrator-director. A stdio server has no credentials, so the entry carries no header; the caller is the local agent principal.

HTTP — three coordinated pieces (all required, this is the default path now)

1. The detached docker run command — compose the recommended-default tuple (or the customized

equivalent) from references/runtime-config.md:

`` docker run -d --name mcp-task-orchestrator-http --restart unless-stopped \ -v mcp-task-data:/app/data \ -v "<FLOOR_DIR>:/project/.taskorchestrator:ro" -e AGENT_CONFIG_DIR=/project \ -e MCP_TRANSPORT=http -e API_ENABLED=true -e API_AUTH_MODE=none -e API_ALLOW_UNAUTHENTICATED=true \ -p 127.0.0.1:3001:3001 \ ghcr.io/jpicklyk/task-orchestrator:latest ``

(Substitute the REST-off or bearer fragment per the user's Step 3 answer, drop the config-mount line (-v "<FLOOR_DIR>..." and -e AGENT_CONFIG_DIR) when the user chose None in Step 4, and add the debug fragment when they chose it.) On Windows, run this via PowerShell with ${PWD} for volume paths — see "Windows / MSYS path caveat" in the reference doc.

1. The `.mcp.json` HTTP entry (NOT an args array):

``json { "mcpServers": { "mcp-task-orchestrator": { "type": "http", "url": "http://localhost:3001/mcp" } } } ``

In bearer mode the entry carries the token as a header, written as the placeholder (Claude Code expands it from the environment; never write the token itself into the file):