Keystone

A small program that keeps other programs running on a machine far away.

That is the whole idea. You write down which programs a device should be running. Keystone reads your list, installs what is missing, starts everything in the right order, watches it, restarts what dies, and tells you honestly what is actually alive.

Like you’re five

Imagine a box of toys in another city, and you cannot go there.

You write a note: “Toy train first, then the tracks, then the little station.” You post the note through the letterbox. Somebody inside the box reads it, takes each toy out in the right order, sets it up, and then watches them play. If the train falls over, they stand it back up. If you ask “is everything okay?”, they look at the toys and tell you the truth — they never say “all fine” while the train is lying on the floor.

Keystone is the somebody inside the box.

Why it exists

Edge devices are not cloud servers. They have little memory, sometimes no container runtime, flaky networks, and nobody nearby to reboot them. Keystone is built for that:

  • Processes first, containers when needed. A native process costs almost nothing. Containers are supported when you want them, not required.
  • One static binary. No daemon zoo, no Kubernetes, no Python runtime.
  • Atomic deployments with rollback. A deployment either lands or is undone.
  • Honest state. If a component is dead, the API says so. This is a design guarantee, not an aspiration — see Component state.
  • Secure by default. Signed artifacts and recipes, loopback-only API unless you provide a token, and per-component privilege dropping.

Where to start

  • Basics

    Start here. What Keystone is, the four words you need, how to install it, and your first deployment on your own machine. What is Keystone? The problem it solves, and what it deliberately is not. The four words Recipe, plan, component, agent — everything else is detail. Install Get the binaries, or build them from source. Your first deployment A two-component stack on your own machine, start to finish. {class=“children children-type-flat children-sort-”}

  • Core concepts

    The model Keystone works with: what you write, what it builds from it, and the rules it follows when reality and your plan disagree. Recipes The complete recipe format, field by field. Plans The device's desired state, and how applying one works. Dependencies Start order, restart cascades, and the three dependency types. Component state What each state means, and the liveness guarantees you can rely on. Reconcile and reuse Why re-applying a plan does not restart your stack.

  • Examples

    Complete, copy-pasteable deployments: the recipes, the plan, and the exact calls to get them onto a device over each control plane. Everything here uses one fictional stack, built up across the pages: a time-series database, an HTTP API that depends on it, a telemetry agent, and a static web front end in a container. It is deliberately the shape of a real edge deployment rather than a hello-world. A service from a GitHub release

  • How it works inside

    What the agent is made of, and what actually happens between “plan received” and “everything running”. Architecture The three interfaces the whole design hangs from. Supervisor The state machine and the layered, parallel start. Runners How processes and containers are actually started, watched and stopped. Artifacts Downloading, verifying and caching, on a network that drops. State and recovery What survives a reboot, and what happens when the agent is killed. {class=“children children-type-flat children-sort-”}

  • Security

    Keystone runs arbitrary software on machines you cannot physically reach. The security model is therefore not decoration — this chapter is the part to read before a device leaves your desk. Secure by default What is locked down out of the box, and the one escape hatch. Signing How trust reaches the device, and how to set it up. API authentication Why the agent refuses to listen on 0.0.0.0 without a token.

  • Control planes

    Three ways to drive the same agent. They are adapters over one shared CommandHandler, so any of them can do anything the others can — no feature drifts between transports. Adapter Best for On by default HTTP Local management, debugging, Prometheus yes (loopback) MQTT IoT platforms, constrained devices, existing brokers no You can run several at once — HTTP on loopback for local debugging while MQTT carries fleet commands is a common combination:

  • Operations

    Running Keystone on real devices: what to watch, what to do when something is wrong, and how to install it properly. Metrics and alerting What Keystone exports, and the alerts actually worth having. Troubleshooting Symptoms, causes and the log line that tells you which. Running under systemd A hardened unit, and why the agent is confined too. {class=“children children-type-flat children-sort-”}

  • Reference

    Flags, environment variables, endpoints and the full TOML schemas. Look things up here; the reasoning lives in the other chapters. Agent flags Every flag the keystone agent accepts. keystonectl The command-line client: every command, its flags, and how to reach an agent over SSH. Environment variables Every KEYSTONE_* variable, grouped by what it affects. HTTP API Endpoints, parameters and response shapes. TOML cheat sheet The four constructs every recipe and plan is made of, and where a misspelled field shows up. {class=“children children-type-list children-sort-”}

The shape of it in one picture

flowchart TB
    OP["You"]
    AG["keystone agent"]
    DB["database"]
    CA["cache"]
    API["api"]

    OP -- "the plan" --> AG
    AG -- "what is really running" --> OP
    AG --> DB
    AG --> CA
    AG --> API

You send a plan. The agent turns it into running components. It keeps answering what is true, and it keeps them alive.