OpenTag
Supported route
Slack Source App
-> self-hosted Control Plane
-> paired local Runner
-> ACP Agent in one local checkout
-> GitHub Project Target/publication
-> truthful result in the originating Slack thread
Slack is the only Source App. GitHub is the Project Target and
publication/evidence provider. The Control Plane owns Slack ingress, custody,
and projection; the Runner owns local execution.
Load the needed reference
- Compose deployment, Slack bootstrap, TLS, or pairing authority:
references/control-plane.md
- Slack app URLs, events, scopes, channel binding, or missing mentions:
references/slack-setup.md
- GitHub target, local checkout, publication, or readback:
references/github-setup.md
- Codex or another supported ACP executor:
references/codex-runner.md
- Any failed readiness, pairing, Run, or delivery step:
references/troubleshooting.md
Load only the references whose branch applies.
Guardrails
- Pair only with the exact HTTPS Control Plane origin the user operates or
explicitly trusts.
- Keep Slack signing and bot secrets in Control Plane secret files. Its
.env
contains only their host-side file paths and non-secret Slack identifiers.
- Enter the bootstrap pairing authority and GitHub token through local secret
input. Keep them out of chat, command arguments, logs, screenshots, and git.
- The ACP Agent edits only the assigned local checkout. OpenTag performs Slack
delivery and GitHub publication through governed provider boundaries.
- Preserve unrelated working-tree changes. Confirm the checkout and target
before enabling write-capable work.
- Run completion, enqueue, approval, and provider acceptance are separate
facts. Preserve
outcome_unknown until the original provider operation is
reconciled.
Paired workflow
Bootstrap the Control Plane and Slack installation from
deploy/compose/.env.example, using file-backed Slack secrets, then start
Compose behind TLS.
Completion: the Compose project reports healthy, /readyz succeeds, and
bootstrap logs show the intended Slack binding without secret plaintext.
Install the reviewed CLI and verify the local checkout and ACP login.
npm install -g @opentag/cli@0.11.0
opentag --version
git -C /absolute/path/to/checkout status --short
Completion: the CLI reports 0.11.0, the user has accepted the checkout
state, and the chosen ACP executor is locally authenticated.
Configure the Runner, trusted relay, checkout, ACP executor, and GitHub
Project Target. Omit secret flags so the CLI prompts locally.
opentag setup \
--relay https://control.example.com \
--project /absolute/path/to/checkout \
--executor codex \
--github-repository owner/repo \
--project-target-id target_team
Replace target_team with the active Slack binding's Project Target ID from
Compose. Do not require a duplicate Runner environment variable for it.
Setup performs the initial pair. For an existing configuration that is
still unpaired, complete that same pairing with:
opentag pair \
--relay https://control.example.com \
--trust-relay-origin https://control.example.com
Completion: redacted config shows paired_relay, the exact trusted origin,
a paired Runner registration, and the intended GitHub target ID; pairing has
registered that target through the active Slack binding and verified exact
Control Plane readback. The bootstrap token is not retained in Runner config.
Keep the Runner active in one supported mode.
opentag start
# or, after a global install:
opentag service install
opentag service start
opentag service status
Completion: the service reports running and ready, the runtime credential
is accepted by the Runner Control Context endpoint, and the configured ACP
executor is ready.
Verify before inviting work.
opentag doctor
opentag status
opentag config show
Completion: required checks pass, the relay and Runner identities match,
the checkout maps to the intended GitHub target, and displayed secrets are
redacted.
Mention the installed OpenTag app in the bootstrapped Slack channel with one
bounded task.
Completion: the signed Slack event creates one WorkThread and Run, the
paired Runner claims one fenced Attempt, and the originating thread receives
a concise result or an explicit actionable failure.
The setup is complete only when every completion criterion above holds on the
paired route. A local process exit, queued delivery, generated pull-request URL,
or Slack acknowledgement alone is insufficient.
1---
2name: opentag
3description: Deploy or operate OpenTag's supported paired setup when a user needs to bootstrap the self-hosted Docker Compose Control Plane and Slack Source App, configure or pair a local ACP Runner with a GitHub Project Target, start the Runner service, verify readiness, or diagnose a Slack mention that did not complete.
4---56
7# OpenTag
8
9## Supported route
10
11```text
12Slack Source App
13 -> self-hosted Control Plane
14 -> paired local Runner
15 -> ACP Agent in one local checkout
16 -> GitHub Project Target/publication
17 -> truthful result in the originating Slack thread
18```
19
20Slack is the only Source App. GitHub is the Project Target and
21publication/evidence provider. The Control Plane owns Slack ingress, custody,
22and projection; the Runner owns local execution.
23
24## Load the needed reference
25
26- Compose deployment, Slack bootstrap, TLS, or pairing authority:
27 `references/control-plane.md`
28- Slack app URLs, events, scopes, channel binding, or missing mentions:
29 `references/slack-setup.md`
30- GitHub target, local checkout, publication, or readback:
31 `references/github-setup.md`
32- Codex or another supported ACP executor:
33 `references/codex-runner.md`
34- Any failed readiness, pairing, Run, or delivery step:
35 `references/troubleshooting.md`
36
37Load only the references whose branch applies.
38
39## Guardrails
40
41- Pair only with the exact HTTPS Control Plane origin the user operates or
42 explicitly trusts.
43- Keep Slack signing and bot secrets in Control Plane secret files. Its `.env`
44 contains only their host-side file paths and non-secret Slack identifiers.
45- Enter the bootstrap pairing authority and GitHub token through local secret
46 input. Keep them out of chat, command arguments, logs, screenshots, and git.
47- The ACP Agent edits only the assigned local checkout. OpenTag performs Slack
48 delivery and GitHub publication through governed provider boundaries.
49- Preserve unrelated working-tree changes. Confirm the checkout and target
50 before enabling write-capable work.
51- Run completion, enqueue, approval, and provider acceptance are separate
52 facts. Preserve `outcome_unknown` until the original provider operation is
53 reconciled.
54
55## Paired workflow
56
571. Bootstrap the Control Plane and Slack installation from
58 `deploy/compose/.env.example`, using file-backed Slack secrets, then start
59 Compose behind TLS.
60 Completion: the Compose project reports healthy, `/readyz` succeeds, and
61 bootstrap logs show the intended Slack binding without secret plaintext.
62
632. Install the reviewed CLI and verify the local checkout and ACP login.
64
65 ```bash
66 npm install -g @opentag/cli@0.11.0
67 opentag --version
68 git -C /absolute/path/to/checkout status --short
69 ```
70
71 Completion: the CLI reports `0.11.0`, the user has accepted the checkout
72 state, and the chosen ACP executor is locally authenticated.
73
743. Configure the Runner, trusted relay, checkout, ACP executor, and GitHub
75 Project Target. Omit secret flags so the CLI prompts locally.
76
77 ```bash
78 opentag setup \
79 --relay https://control.example.com \
80 --project /absolute/path/to/checkout \
81 --executor codex \
82 --github-repository owner/repo \
83 --project-target-id target_team
84 ```
85
86 Replace `target_team` with the active Slack binding's Project Target ID from
87 Compose. Do not require a duplicate Runner environment variable for it.
88
89 Setup performs the initial pair. For an existing configuration that is
90 still unpaired, complete that same pairing with:
91
92 ```bash
93 opentag pair \
94 --relay https://control.example.com \
95 --trust-relay-origin https://control.example.com
96 ```
97
98 Completion: redacted config shows `paired_relay`, the exact trusted origin,
99 a paired Runner registration, and the intended GitHub target ID; pairing has
100 registered that target through the active Slack binding and verified exact
101 Control Plane readback. The bootstrap token is not retained in Runner config.
102
1034. Keep the Runner active in one supported mode.
104
105 ```bash
106 opentag start
107 # or, after a global install:
108 opentag service install
109 opentag service start
110 opentag service status
111 ```
112
113 Completion: the service reports running and ready, the runtime credential
114 is accepted by the Runner Control Context endpoint, and the configured ACP
115 executor is ready.
116
1175. Verify before inviting work.
118
119 ```bash
120 opentag doctor
121 opentag status
122 opentag config show
123 ```
124
125 Completion: required checks pass, the relay and Runner identities match,
126 the checkout maps to the intended GitHub target, and displayed secrets are
127 redacted.
128
1296. Mention the installed OpenTag app in the bootstrapped Slack channel with one
130 bounded task.
131 Completion: the signed Slack event creates one WorkThread and Run, the
132 paired Runner claims one fenced Attempt, and the originating thread receives
133 a concise result or an explicit actionable failure.
134
135The setup is complete only when every completion criterion above holds on the
136paired route. A local process exit, queued delivery, generated pull-request URL,
137or Slack acknowledgement alone is insufficient.
amplifthq