Self-Host OpenTag with Docker Compose and Localtonet

How the OpenTag deployment works

OpenTag is a persistent AI teammate for a Slack engineering channel. A request begins when someone mentions the configured OpenTag identity in Slack. The self-hosted Control Plane receives and coordinates the request, while a paired Runner performs the work on a computer that has the approved local checkout and coding-agent environment.

The current supported product path is deliberately narrow: Slack presence, a self-hosted Control Plane, one paired Runner, one ACP coding agent, optional GitHub draft pull request or evidence, and a response in the originating Slack thread. Slack is the Source App for this profile. GitHub is a Project Target and an optional publication and evidence provider, not a second request inbox.

The architecture separates sensitive material by role. Source code, local checkouts and worktrees, the coding-agent login or session, and GitHub credentials stay on the Runner. Slack credentials and Control Plane service credentials stay on the Control Plane. The Control Plane keeps coordination truth rather than becoming a copy of the development computer.

OpenTag also separates different kinds of evidence. Executor output does not automatically prove that a pull request exists, checks passed, or Slack received the final result. Provider actions are represented through Effect evidence, while terminal assessment is a separate conclusion based on the available facts. This distinction matters when a provider request times out or a side effect has an uncertain outcome.

Prerequisites and deployment decisions

Prepare the Control Plane host, Runner computer, Slack application, credentials, and ingress path before starting. The Control Plane and Runner have different responsibilities and do not need to run on the same machine. The Localtonet client must run on a device that can reach the Control Plane's published host address and port.

Choose the Control Plane host

Use a machine that can run the Docker Compose stack reliably and retain its database and secret files. Because the Control Plane is the persistent Slack-facing presence, it should remain available independently of the Runner whenever practical. When the Runner is unavailable, the Control Plane can keep a request visibly queued instead of disappearing with the development computer.

Choose the Runner computer

Place the Runner on the computer where the approved source checkout, coding-agent login or session, and any required GitHub credential should remain. Pairing should be performed by an operator who understands which Project Target is being made available to the OpenTag workflow.

Choose the Localtonet client location

The simplest Linux arrangement is to install Localtonet on the same Debian or Ubuntu host as the Control Plane. The tunnel can then target the host-published OpenTag port through a loopback or host-local address, subject to the binding defined by the Compose deployment. The client may instead run on another LAN device, but that device must be able to route to the Control Plane address and published port.

Pin and inspect the OpenTag Compose revision

OpenTag's current repository README provides the supported quick-start shape. The version-sensitive deployment files live in the repository's Compose deployment directory. Clone the repository, record the revision, and treat files from that same revision as one configuration set.

git clone https://github.com/amplifthq/opentag.git
cd opentag
git rev-parse HEAD
git status --short
cd deploy/compose

Save the commit identifier in your deployment notes. A branch such as main moves over time, so the commit is the stable identifier needed to reproduce or troubleshoot the installation later.

Render the effective Compose configuration

Before starting containers, copy the supplied environment template and inspect the files included with your checkout:

cp .env.example .env
find . -maxdepth 2 -type f -print
docker compose --env-file .env config

The final command resolves the Compose model and reports interpolation errors without starting the stack. Review its service definitions, published ports, volumes, secret mounts, profiles, health checks, and environment mappings. Do not publish the rendered output because it may contain sensitive resolved values.

The current README explicitly identifies OPENTAG_SLACK_PROJECT_TARGET_ID as the identifier that must match the active Slack binding and later be entered during Runner setup. It also requires every placeholder in .env to be replaced and requires file-backed Slack and relay-content secrets described by the Compose guide.

Create the exact file-backed secrets declared by the checkout

Secret filenames and mount locations are deployment interface details. They must match the checked-out Compose files exactly. Use the following inspection commands from deploy/compose to locate the declarations before creating any files:

grep -RInE 'secrets:|_FILE|SLACK|relay.content|relay_content' .
grep -RInE 'file:|source:|target:' .
grep -RInE 'placeholder|replace|example' .env.example . 2>/dev/null

Create each declared host-side secret file at the exact path referenced by the Compose configuration, write only the required secret value, terminate it with a newline unless the checked-out guide states otherwise, and restrict its permissions:

chmod 600 .env
chmod 600 PATH_TO_EACH_DECLARED_SECRET_FILE

PATH_TO_EACH_DECLARED_SECRET_FILE is intentionally a placeholder. Replace it with each filename actually declared by your selected OpenTag revision. The supplied evidence confirms the requirement for file-backed Slack and relay-content secrets but does not expose their current filenames or values. Inventing names would create an unsafe and non-reproducible deployment.

Record the published port and verification endpoint

Inspect the effective model for the Control Plane's ports mapping and any declared health check:

docker compose --env-file .env config | grep -nE 'ports:|published:|target:|healthcheck:|test:'

Record four values in your deployment notes: the Control Plane service name, host bind address, published host port, and supported local verification path. Use the published host port for Localtonet, not the container-only target port.

Install the OpenTag Control Plane with Docker Compose

After replacing every placeholder and creating every declared file-backed secret, start the deployment from deploy/compose. The current repository quick start uses the following sequence.

git clone https://github.com/amplifthq/opentag.git

cd opentag/deploy/compose

cp .env.example .env
docker compose --env-file .env config

docker compose --env-file .env up --build

Foreground startup is useful because configuration errors, missing secret files, failed image builds, unavailable ports, and database startup problems remain visible. Once the initial launch is understood, use the startup mode supported by your operational policy. Do not change the documented configuration merely to hide a startup failure.

Confirm that the declared services started

In a second terminal, return to the Compose directory and inspect service state:

docker compose --env-file .env ps
docker compose --env-file .env logs --tail=200

Confirm that the Control Plane and included PostgreSQL service do not remain in a restart loop. If a service declares a health check, inspect the health result shown by Docker rather than assuming that a running process is ready.

Verify the local HTTP boundary

Use the host address, published port, and supported verification path recorded from the checked-out deployment. The command shape is:

curl -i http://HOST_ADDRESS:PUBLISHED_PORT/SUPPORTED_PATH

Replace all three uppercase placeholders. Run this check from the device that will host the Localtonet client. A request that succeeds only inside a container does not prove that a host-installed tunnel client can reach the service. Record the expected status and response for the OpenTag endpoint so that the same application boundary can be tested through Localtonet later.

Install and pair the OpenTag Runner

Pair the Runner after the Control Plane is reachable through the trusted origin that the Runner will use. If Localtonet will provide that origin, complete the Localtonet section first and then return here. If you already have another trusted HTTPS origin, pairing can use it.

The current repository README pins the CLI command to @opentag/cli@0.11.0. Separately, the GitHub releases page displayed v0.10.0 as the latest tagged GitHub release in the supplied evidence. These are different publication surfaces and should not be treated as proof of universal compatibility. The moving README on main can describe an npm CLI newer than the latest displayed GitHub release.

npm install -g @opentag/cli@0.11.0

opentag setup --relay https://relay.example.com

opentag start

Verify the Control Plane and Runner

Verify the deployment in layers. First confirm the Compose services and local HTTP endpoint. Next run the OpenTag CLI diagnostics. Then test the same service through its public URL. Finally send a controlled Slack request. This sequence identifies which boundary failed instead of treating every problem as an ingress issue.

Run the supported CLI checks

opentag doctor
opentag status

opentag doctor checks the installation, while opentag status reports the Runner's current OpenTag status. Resolve failures before asking a team to rely on the integration. Check the configured Control Plane origin, pairing state, Project Target, and ACP executor instead of repeatedly restarting an unknown configuration.

Interpret the current Teammate work states

OpenTag exposes each active Slack binding as a long-lived Teammate. Its work state is derived from facts that already exist, including the Project Target, fresh Runner readiness, and the binding's current Work. OpenTag does not add a separate mutable presence lifecycle.

These states are projections, not commands. They cannot claim, retry, cancel, or settle Work. A displayed state should not be interpreted as proof that an operator action or provider side effect already occurred.

Publish the Control Plane with a Localtonet HTTP tunnel

Once OpenTag works locally, Localtonet can provide its public internet entry point. Our client establishes an outbound connection from the selected device to a Localtonet relay server. The HTTP tunnel provides a public HTTPS address and forwards requests to the verified local IP address and port without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

This is standard HTTP tunneling, not VPN functionality. Localtonet VPN Manager is a separate private mesh VPN feature. For Slack ingress to the OpenTag web service, create an HTTP tunnel targeting the verified host-published Control Plane endpoint.

Install Localtonet on Debian or Ubuntu

Our current Linux package path supports x64 and ARM64 Debian or Ubuntu systems with systemd 247 or newer and OpenSSL 3, including Debian 12 and Ubuntu 22.04 or newer. Download the package matching the machine architecture from the Localtonet download and installation documentation.

sudo apt install ./localtonet-linux-x64.deb

sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config

sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service

Do not use the separate VPN service for this HTTP tunnel. Confirm that the standard Localtonet service remains active:

sudo systemctl status localtonet.service

Create and verify the HTTP tunnel

Follow the current Localtonet HTTP tunnel documentation while using the OpenTag target values recorded from the checked-out Compose deployment.

curl -i http://HOST_ADDRESS:PUBLISHED_PORT/SUPPORTED_PATH

curl -i https://ASSIGNED_PUBLIC_HOST/SUPPORTED_PATH

Connect Slack to the public origin safely

Configure Slack with the exact event, callback, interactivity, or request paths declared by the selected OpenTag deployment revision. The supplied repository evidence confirms that Slack needs a public HTTPS origin, but it does not include the current Compose guide's route strings or Slack dashboard field mapping.

Locate those paths in the checked-out deployment before changing Slack:

grep -RInE 'callback|events|interactivity|slack|public.*url|origin' .

Combine each documented path with the tested Localtonet origin. Do not send Slack to the generic root path unless the checked-out OpenTag guide explicitly requires it. Save Slack's configuration, then watch the Control Plane logs while Slack performs any endpoint validation.

Keep the public origin stable while Slack depends on it. If a generated Localtonet hostname changes because the tunnel is recreated or its Process Type changes, update every OpenTag and Slack setting that references the old origin. A Custom Sub Domain or Custom Domain may provide a more stable naming workflow where currently available, but availability and plan access must be checked in the dashboard.

Perform an end-to-end Slack test

Send a small, non-destructive request in the intended channel:

@OpenTag investigate the failing check and propose a fix

Confirm each layer separately: Slack accepts the mention, the Control Plane creates or projects the Work, the paired Runner receives an Attempt, the ACP coding agent operates against the intended checkout, and status returns to the same thread. Begin with investigation or proposal work rather than a request that modifies a production system.

If GitHub publication is enabled, test with a repository and permissions appropriate for controlled validation. Draft pull request publication is a distinct governed stage. A successful executor message does not independently prove publication, observed checks, provider delivery, or terminal success.

Routine operations and troubleshooting

Operate the deployment as three independently testable layers: the OpenTag Control Plane stack, the paired Runner, and the Localtonet HTTP tunnel. Add Slack as the final integration test only after those layers pass their own checks.

Recommended verification sequence

1. Run docker compose --env-file .env ps and inspect recent logs.
2. Request the supported OpenTag path through the local host address and published port.
3. Run opentag doctor and opentag status on the Runner.
4. Confirm that localtonet.service is active and the HTTP tunnel is running.
5. Request the same supported path through the public HTTPS origin.
6. Send a controlled Slack mention and observe its progress in the original thread.

The Compose stack does not start

Compare .env with .env.example from the same commit. Look for unresolved placeholders, malformed values, missing file-backed Slack or relay-content secrets, incorrect paths, permission errors, port conflicts, and a PostgreSQL service that cannot become ready.

docker compose --env-file .env config
docker compose --env-file .env ps
docker compose --env-file .env logs --tail=200

Do not respond to an application startup failure by exposing more ports. Public ingress cannot repair a service that never begins listening.

The service works inside Docker but not on the host

Confirm that the Compose configuration publishes the Control Plane port to the host. A container-only expose declaration or internal target port is not the same as a host-published port. Use the effective configuration and docker compose ps to identify the actual mapping.

The host can reach OpenTag, but the Localtonet client cannot

Check where our client runs. An address such as 127.0.0.1 refers to the client device itself. If Localtonet runs on another LAN machine, configure a reachable address for the Control Plane host and apply local firewall rules according to your network policy. Confirm the path from the client device before testing the public URL.

The public URL is unavailable

Verify that localtonet.service is active, the selected device is connected, and the tunnel was explicitly started. Recheck the selected device, current relay selection, local IP address, and published host port. If the local endpoint fails from the client device, repair that path first.

The public origin responds, but Slack requests fail

A response from the root URL proves only that some HTTP route is reachable. Recheck the exact OpenTag route required for Slack, Slack-side callback configuration, Control Plane Slack credentials, and request-validation settings. Watch the Control Plane logs while Slack sends a test request, but redact credentials before sharing logs.

The state is setup_required

Verify that the Slack binding, GitHub Project Target, and Runner pairing are complete. The identifier entered during setup must exactly match OPENTAG_SLACK_PROJECT_TARGET_ID in the active Slack binding. Also verify the trusted Control Plane origin and bootstrap pairing process.

The state is runner_offline or Work remains queued

Confirm that opentag start is running and the Runner can reach the trusted Control Plane origin. Run opentag doctor and opentag status. Do not create duplicate requests merely because the Runner was temporarily unavailable. Queued Work is intended to remain visible until a ready Runner can process it.

Pairing fails after an earlier checkout

Point OPENTAG_CONFIG_HOME and OPENTAG_STATE_DIR to new empty directories, then repeat the setup supported by the selected revision. Preserve previous data separately. Use opentag pair only to finish interrupted pairing or pair an existing unpaired configuration.

A provider result is uncertain

Keep Work, Attempt, Effect evidence, channel projection, and terminal assessment separate. If OpenTag reports outcome_unknown, inspect the provider before retrying an action that may already have occurred. Blind replay can create duplicate side effects.

Changing or removing public access

Stop the Localtonet tunnel when Slack ingress should no longer be available. Delete it when the configuration is obsolete. If the public origin changes, update OpenTag and Slack, then repeat local, public, CLI, and Slack verification.

Frequently asked questions