Run the sidecar with Docker

The sidecar is AuthRail's local rule checker. Docker builds it from source and runs it as a container beside your application. You do not build a native binary first, and the build command does not start the service.

This guide takes you from the source checkout to a running sidecar. Install Git, Docker Engine or Docker Desktop, and Docker Compose. You do not need Go on your computer; the Docker build includes it.

Before starting, finish the dashboard setup and connection details. You should have the deployment's copied settings and these files in your private my-deployment directory: deployment-token, adapter-token and executor-public.pem.

Your protected application must also run in Docker for this setup. It shares a private local connection with the sidecar. Keep the AI agent and its tools outside that connection and keep provider credentials in the application. If your application runs directly on your laptop, use the native guide.

1. Build the image

In a terminal, get the sidecar source and build it:

git clone --branch main https://github.com/AuthRail/authrail-sidecar.git
cd authrail-sidecar
docker build -t authrail-sidecar:development .

When the build finishes, your computer has an image named authrail-sidecar:development. An image is the packaged program. The next steps start a container, the running instance of that program.

2. Supply this deployment's settings

Keep this terminal open in the authrail-sidecar checkout. Replace the three YOUR_... values below with those from Integration setup → Configure the sidecar. The file paths refer to the private files you prepared in the connection guide:

export AUTHRAIL_CONTROL_PLANE_URL=https://api-staging.authrail.io
export AUTHRAIL_ORGANISATION_ID=YOUR_ORGANISATION_ID
export AUTHRAIL_DEPLOYMENT_ID=YOUR_DEPLOYMENT_ID
export AUTHRAIL_TRUSTED_KEY_SHA256=YOUR_TRUSTED_SIGNING_KEY
export AUTHRAIL_DEPLOYMENT_TOKEN_PATH="$HOME/.local/share/authrail/my-deployment/deployment-token"
export AUTHRAIL_ADAPTER_TOKEN_PATH="$HOME/.local/share/authrail/my-deployment/adapter-token"
export AUTHRAIL_EXECUTOR_PUBLIC_KEY_PATH="$HOME/.local/share/authrail/my-deployment/executor-public.pem"

Use the API address displayed by your deployment if it differs from the example. These shell settings tell Compose which deployment and files to use. They do not put the token values in your source code. Keep the files private; only the sidecar container's user should be able to read its mounted credentials.

3. Start the sidecar

Run:

docker compose -p authrail-runtime -f docker/compose.yaml up -d
docker compose -p authrail-runtime -f docker/compose.yaml ps

Compose starts the image you built and creates a private state volume that survives container restarts. The ps output should show sidecar running and, after it receives its rules, healthy.

Check that it has loaded valid rules:

docker compose -p authrail-runtime -f docker/compose.yaml exec sidecar /usr/local/bin/authrail-container health

Success returns to your shell without printing anything. A failure prints a message and exits unsuccessfully. If it fails, read the process output:

docker compose -p authrail-runtime -f docker/compose.yaml logs --tail 50 sidecar

Check that you copied the correct deployment settings, saved the token, and selected published Rails in the dashboard. Also check file permissions. A running container without valid rules is not ready to check your application.

4. Connect your application container

The sidecar accepts local requests at http://127.0.0.1:7078. This address is private to its container. Put your application beside it by adding an executor service under the existing services: key in docker/compose.yaml:

  executor:
    image: your-protected-application:reviewed-version
    network_mode: service:sidecar
    depends_on:
      sidecar:
        condition: service_healthy

Keep the existing sidecar, volume and secret definitions. Replace the application image name with the image you built for your own application. Mount its adapter-token and executor-private.pem privately, using the file paths expected by your application. The sidecar must not receive the private key.

Start the added service with the same command:

docker compose -p authrail-runtime -f docker/compose.yaml up -d

In your application's Node SDK or Go SDK configuration, use http://127.0.0.1:7078 as the sidecar URL. The application and sidecar share networking, while their files and credentials stay separate. Do not publish port 7078 or give the agent access to the sidecar's credentials.

You now have the local service ready for the SDK guide. After a safe request, use the Runtime walkthrough to compare its checks, logs and AuthRail history.

docker compose -p authrail-runtime -f docker/compose.yaml logs --tail 50 --follow sidecar

docker compose -p authrail-runtime -f docker/compose.yaml stop
docker compose -p authrail-runtime -f docker/compose.yaml start

docker compose -p authrail-runtime -f docker/compose.yaml down
docker compose -p authrail-runtime -f docker/compose.yaml ps

docker image rm authrail-sidecar:development