Skip to content

Arc Environment Variable Update Runbook

Arc runs as a single long-lived Docker container on a Proxmox VM. This runbook describes how to change Arc's environment variables or secrets and apply them safely.

Overview

  • Host: Proxmox node PVE4, VM 406
  • Access credentials: stored in Bitwarden
  • Configuration file: /opt/appcircle/config/arc.env
  • Compose directory: /opt/appcircle/compose
  • Compose project name: arc
  • Service name: arc

arc.env holds Arc's secrets and runtime overrides in KEY=value form. Compose loads it through env_file, so its values reach the container as environment variables. Non-secret defaults live in the repository (config/index.js) and are overridden by arc.env, which is in turn overridden by OS environment variables.

Prerequisites

  • SSH access to VM 406 on the PVE4 Proxmox node, with a user that can run docker compose. Credentials are stored in Bitwarden.
  • The new value for the key you are changing, for example a rotated token

Update the configuration

  1. Open the configuration file:
nano /opt/appcircle/config/arc.env

  1. Add or edit the key and save the file. Keep the KEY=value format, one key per line, and do not quote values unless the value itself contains spaces.

  2. Apply the change by recreating the container:

cd /opt/appcircle/compose
docker compose --project-name arc up -d --force-recreate arc

A restart is not enough

Environment variables are injected when a container is created, not when it starts. Commands such as docker compose restart arc or docker restart reuse the existing container, so the old values stay in effect and the change appears to have been ignored. Always recreate the container with up -d --force-recreate.

Verify

  1. Confirm the container was recreated and is running:
docker compose --project-name arc ps
  1. Follow the startup logs until Arc reports that it is connected:
docker compose --project-name arc logs -f arc
  1. Send Arc a direct message in Slack and confirm it replies. If the change involved an integration token, exercise that integration specifically.

Startup takes a few minutes

On every start Arc wipes the per-user session workspaces, refreshes the cloned repositories, and downloads the prebuilt code index before it accepts messages. In-flight conversations are not lost: thread transcripts persist across a restart.

Rollback

Restore the previous value in /opt/appcircle/config/arc.env and run the same up -d --force-recreate command.

Security notes

  • arc.env contains secrets. Keep it out of version control and readable only by the user that runs Arc.
  • Rotate a leaked token at its source (Slack, GitHub, Linear, Anthropic) before updating arc.env.

Checklist

  • Key added or edited in /opt/appcircle/config/arc.env
  • Container recreated with up -d --force-recreate
  • docker compose --project-name arc ps shows the container running
  • Logs are clean and Arc replies in Slack
  • Affected integration verified