Skip to main content

Manual Linux systemd deployment

This guide covers manual setup of the service user, prebuilt release, environment file, systemd unit, and HTTPS reverse proxy.

MCP client -> HTTPS reverse proxy -> 127.0.0.1:8765 -> AgentDock

AgentDock listens only on a loopback address. Caddy, Nginx, or another reverse proxy provides TLS and the public endpoint.

Create the service user and directories​

sudo useradd --system --create-home --home-dir /srv/agentdock agentdock
sudo install -d -o agentdock -g agentdock /srv/agentdock/AgentDock
sudo install -d -m 0755 /opt/agentdock/bin
sudo install -d -m 0750 /etc/agentdock

Download and install the release binary​

case "$(uname -m)" in
  x86_64|amd64) ARCH=amd64 ;;
  aarch64|arm64) ARCH=arm64 ;;
  *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
esac

ASSET="agentdock_linux_${ARCH}.tar.gz"
BASE_URL="https://github.com/uvwt/agentdock/releases/latest/download"
TMP_DIR="$(mktemp -d)"

curl -fL "$BASE_URL/$ASSET" -o "$TMP_DIR/$ASSET"
curl -fL "$BASE_URL/$ASSET.sha256" -o "$TMP_DIR/$ASSET.sha256"
(
  cd "$TMP_DIR"
  sha256sum -c "$ASSET.sha256"
  tar -xzf "$ASSET"
)

sudo install -m 0755 "$TMP_DIR/bin/agentdock" /opt/agentdock/bin/agentdock
rm -rf "$TMP_DIR"

In production, replace BASE_URL with a fixed release:

BASE_URL="https://github.com/uvwt/agentdock/releases/download/vX.Y.Z"

Environment file​

Create /etc/agentdock/agentdock.env:

AGENTDOCK_HOST=127.0.0.1
AGENTDOCK_PORT=8765
AGENTDOCK_LOG_LEVEL=info
AGENTDOCK_AUTH_TOKEN=<replace-with-a-random-secret>

Restrict its permissions:

sudo chown root:agentdock /etc/agentdock/agentdock.env
sudo chmod 0640 /etc/agentdock/agentdock.env

Add these variables when NexusDock Recall or workflow templates are required:

AGENTDOCK_NEXUS_ENDPOINT=https://nexus.example.com
AGENTDOCK_NEXUS_TOKEN=<replace-with-a-secret>

systemd unit​

Create /etc/systemd/system/agentdock.service:

[Unit]
Description=AgentDock MCP server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=agentdock
Group=agentdock
WorkingDirectory=/srv/agentdock/AgentDock
EnvironmentFile=/etc/agentdock/agentdock.env
ExecStart=/opt/agentdock/bin/agentdock \
  --host ${AGENTDOCK_HOST} \
  --port ${AGENTDOCK_PORT} \
  --log-level ${AGENTDOCK_LOG_LEVEL}
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

Start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now agentdock

HTTPS reverse proxy​

Caddy example:

agentdock.example.com {
  reverse_proxy 127.0.0.1:8765
}

Client URL:

https://agentdock.example.com/mcp

Do not log the Authorization header at the proxy. Configure AGENTDOCK_TRUSTED_PROXY_CIDRS only when the proxy is on a trusted network and rewrites X-Forwarded-For correctly.

OAuth (optional)​

For browser-authorized clients such as ChatGPT, enable OAuth:

AGENTDOCK_OAUTH_ENABLED=true
AGENTDOCK_SERVER_URL=https://agentdock.example.com
AGENTDOCK_OAUTH_PASSWORD=<authorization-password-at-least-12-characters>
AGENTDOCK_OAUTH_TOKEN_SECRET=<random-signing-key-at-least-32-bytes>

AGENTDOCK_SERVER_URL is the HTTPS origin without /mcp. Keep the password and signing key out of version control. See Connect ChatGPT to AgentDock for connection and endpoint checks.

Update​

Download and verify the target release again, replace /opt/agentdock/bin/agentdock, then restart:

sudo systemctl restart agentdock
sudo systemctl status agentdock --no-pager

Runtime data and the environment file live in separate directories and are not deleted when the binary is replaced.

Verification​

sudo systemctl status agentdock --no-pager
sudo journalctl -u agentdock -n 100 --no-pager
curl -fsS http://127.0.0.1:8765/healthz

Use the Bearer Token from the environment file when verifying MCP, and confirm that the public reverse proxy preserves the Authorization header. Source builds are for contributors only; see the Contributor guide.