Run a native sidecar
Download the sidecar, run it beside your application, and check that it has loaded your rules.
A native sidecar runs directly on your computer or server as a separate program. Choose it when your protected Node, Go or Python application also runs on that host. It checks the same rules as the Docker installation.
Download the executable for your computer, give it your deployment settings,
then leave it running while the application makes checks. You do not need Go
to use a release download. The commands below use a macOS or Linux terminal,
curl and tar.
First complete the dashboard setup and connection details, including the registered public key and private token files. If you are replacing a running installation, follow the upgrade instructions at the end of this page before replacing its executable.
1. Download the sidecar
Choose your operating system and processor. On a Mac, About This Mac shows
an Apple chip or an Intel processor. On Linux, uname -m prints aarch64 for
arm64 or x86_64 for amd64.
The commands download the release archive and its checksum, check that the archive matches, then unpack it. Stop if the checksum check fails.
mkdir -p "$HOME/Downloads/authrail-sidecar" &&
cd "$HOME/Downloads/authrail-sidecar" &&
curl --fail --location --remote-name https://github.com/AuthRail/authrail-sidecar/releases/download/v0.1.0/authrail-sidecar-0.1.0-darwin-arm64.tar.gz &&
curl --fail --location --remote-name https://github.com/AuthRail/authrail-sidecar/releases/download/v0.1.0/authrail-sidecar-0.1.0-darwin-arm64.tar.gz.sha256 &&
shasum -a 256 -c authrail-sidecar-0.1.0-darwin-arm64.tar.gz.sha256 &&
tar -xzf authrail-sidecar-0.1.0-darwin-arm64.tar.gz &&
cd authrail-sidecar-0.1.0-darwin-arm64 &&
./authrail-sidecar --versionThe final command prints the version and build revision, then exits. It does not start the sidecar. Keep this terminal in the extracted directory for the next steps. The download also contains the licence and implementation guides.
Build from source when contributing
With Git and Go 1.26 or newer:
git clone --branch v0.1.0 https://github.com/AuthRail/authrail-sidecar.git
cd authrail-sidecar
go build -o authrail-sidecar ./cmd/authrail-sidecarThis compiles an executable in the checkout. It has not started the sidecar. Use the source checkout as your working directory for the commands below.
2. Give it the deployment settings
In the same terminal, replace the YOUR_... values with those from the
deployment's Integration setup → Configure the sidecar. Use your own API
address if it differs from this example:
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_EXECUTOR_PUBLIC_KEY_FILE="$HOME/.local/share/authrail/my-deployment/executor-public.pem"
export AUTHRAIL_DEPLOYMENT_TOKEN="$(cat "$HOME/.local/share/authrail/my-deployment/deployment-token")"
export AUTHRAIL_ADAPTER_TOKEN="$(cat "$HOME/.local/share/authrail/my-deployment/adapter-token")"
umask 077
mkdir -p "$HOME/.local/state/authrail/my-deployment"
chmod 700 "$HOME/.local/state/authrail/my-deployment"
export AUTHRAIL_STATE_FILE="$HOME/.local/state/authrail/my-deployment/state.json"The token and key paths refer to the files from the connection guide. The state directory stores the sidecar's rules, report queue and recovery history. Keep it private and use a separate directory for each sidecar instance.
These settings include private credentials. Keep the terminal and process environment outside the agent's reach. The application's private key and provider credentials do not belong in the sidecar.
3. Start it
Run:
./authrail-sidecarThe sidecar stays in the foreground and prints startup and service messages. Leave this terminal open. Use another terminal to start your application and check the local service:
curl --fail --silent --show-error http://127.0.0.1:7078/healthLook for bundleValid: true and the mode selected for this deployment. The
response also shows the loaded bundle, application-key fingerprints and pending
report counts. HTTP success alone only means the endpoint responded.
If there is no valid bundle, check the copied settings, deployment token, registered application key and selected Rails. The deployment's Overview → Connection health should also show a recent update after the sidecar connects.
4. Connect the SDK
Follow the Node, Go or Python guide in your protected application.
Use http://127.0.0.1:7078 as its sidecar URL, the same adapter token, and the
application's private key. These processes must run on the same host; keep the
sidecar listener private.
After a safe request, the terminal shows decision events. The Runtime walkthrough includes an actual native status check and operation logs. Monitoring explains how to read those events.
Stop or remove the native sidecar
Pause the protected application or move its traffic to a replacement first. If you started the sidecar in this terminal, press Ctrl+C. If a service manager starts it, stop that specific service. Disable its automatic startup when removing the installation.
For a background process, find its listener:
lsof -nP -iTCP:7078 -sTCP:LISTENUse the configured port if different. Confirm that the process belongs to this
sidecar, then send SIGTERM with kill -TERM PID, using the confirmed numeric
PID. Allow it to exit and run the listener check again. Do not stop unrelated
processes or use a broad process-name kill command.
For permanent removal, remove the stopped executable and its service-manager entry. Keep private state and credentials until queued reports, blocked reports and unknown effects are resolved and retained as required. Deleting the program does not erase AuthRail's retained Actions. Do not delete state to clear a warning.
Package, maintain or upgrade an installation
For a maintained installation, have a service manager or secret store supply the credentials rather than relying on an interactive terminal. Keep the instance's identity and complete private state through restarts.
To build a local archive for another installation of the same OS and CPU, run this from the source checkout:
sh scripts/package.sh development ./distIt creates an archive and adjacent SHA-256 checksum. Verify the checksum before unpacking. Choose a reviewed source commit when you need a repeatable build.
Before an upgrade, pause the application, stop the sidecar with Ctrl+C or SIGTERM, and allow its bounded shutdown to complete. Preserve the entire state directory and credential files. Replace the executable and restart with the same settings, then check valid rules and report queues before accepting work. Never restore an older state copy or delete rejected state to make startup succeed. Follow recovery for unresolved reports and effects.