Release and deploy (operator)

For whoever runs the box. Casual users don’t need to manage updates.

Keeping your Lowkey box up to date follows a simple, two-step pattern that separates code preparation from the actual live update. Decoupling these steps ensures you never push half-finished code to a live system by accident.

Land and deploy

Updates reach your box in two stages:

1. Landing a change: When a new capability is built or fixed, the code is first merged into the main branch. This process, called landing, runs build checks and automated tests. Once they pass, the code sits safely on the remote server (origin/main). The feature is now ready, but it is not yet running on your box.
2. Deploying the change: To make the landed changes live, you run a deployment. This pulls the latest code from origin/main, builds the web container, compiles the system code, and restarts the Lowkey daemon.

If you are running your own box as a self-serve operator, you control this cycle. In a managed fleet setup, a central fleet operator handles these updates for you, rolling them out across multiple boxes.

Running a deploy

To update your box, you run the deploy script from your project root:

./deploy.sh

Because deploying restarts the Lowkey daemon, it will briefly disconnect anyone using the box. To protect active turns, the script automatically checks for running tasks (like an active chat turn, agent run, or scheduled automation).

If the script detects active work, it will warn you and ask to confirm. If you are deploying via chat and need the restart to not interrupt the deploy script itself, you can run:

LOWKEY_DEPLOY_DETACH=1 ./deploy.sh

For emergency updates where you need to force the deploy even with active sessions, you can override the safety gate by setting:

LOWKEY_DEPLOY_FORCE=1 ./deploy.sh

The deploy ledger

Lowkey keeps a permanent audit trail of every update that runs on your box. This is stored in a line-by-line JSON file:

~/.lowkey/deploy-history.jsonl

Every time the Lowkey daemon starts up, it reads the current build identifier (the Git commit SHA). If it is different from the last recorded version, it appends a new entry to the ledger. This entry includes:

• The new commit SHA.
• The previous commit SHA.
• The timestamp of the build.
• The user who triggered the update.

This history makes it easy to confirm exactly when an update went live or to look back if you need to roll back to a previous version.

Staying in control

Because updates restart services, Lowkey never auto-deploys. You decide when a deploy happens. It is always safest to check the status of your box first and run updates during a quiet window. If an update goes wrong, you can revert by checking out a previous Git commit tag and running the deploy script again.

What to read next

• Standing up your box for the first time → /operator/provisioning/
• Connecting AI engines for your agents → /operator/providers/
• Defining agents and personalities → /operator/agents-config/