LiveLLM.Docs
Automate

Machine state

A machine's shape — cores, memory, disk, ports — is easy to write down. What is inside it usually is not: packages someone installed, a service someone enabled, a config file someone edited. That knowledge lives in the machine, so losing the machine loses it.

Machine state moves it into git. Every machine with an agent keeps its insides as code, and the platform replays that code whenever the machine is rebuilt. Agents work the same way — they diagnose freely, but changes they make to a machine land as commits you can read and revert.

1

Every machine with an agent has a blueprint

Turn on the agent for a VM and the workspace gains a repo named <machine>-state. It describes what the machine is — packages, services, config files, users — as declared state, not as a log of commands someone ran. Project code stays in its own repos; this one is the machine.

my-box-state
my-box-state/
  site.yml         the play (targets the machine, runs as root)
  tasks/main.yml   the tasks — what the machine should have
  README.md        the conventions
  CHANGELOG.md
2

Describe the machine, don't command it

Each task says what should be true, so applying it twice changes nothing the second time. That is what makes the file replayable months later — and readable in review, because a diff shows the machine changing rather than a shell transcript.

tasks/main.yml
- name: nginx is installed
  ansible.builtin.package:
    name: nginx
    state: present

- name: nginx runs at boot
  ansible.builtin.systemd_service:
    name: nginx
    enabled: true
    state: started
3

A push converges the machine

Commit and push, and within about a minute the machine matches what is committed. Removing a task is how you undo it — flip present to absent, or revert the commit, and the machine follows. The result shows up in your workspace Activity either way.

shell
$ git commit -m "install nginx: serves the API"
$ git push

# Activity:
#   applying machine state 4f2a1c9 to my-box
#   machine state 4f2a1c9 applied to my-box
4

Rebuild, and the machine comes back

This is the point of all of it. Delete a machine and its blueprint is kept on purpose. Create a machine with that name again — from the dashboard, the API, or Terraform — and the platform replays the blueprint onto it as it boots. New disk, same machine. Your machines stop being things you are afraid to lose.

shell
# Activity, on recreate:
#   deleted workload my-box — its machine state is kept in my-box-state
#   created workload my-box (vm-ubuntu)
#   rebuilding my-box from its machine state 4f2a1c9
#   machine state 4f2a1c9 applied to my-box
5

Ask whether a machine still matches

Someone logs in and changes something by hand; now the machine and its blueprint disagree. A check reports what would change without touching anything — and applying makes the machine match again.

shell
$ curl -X POST -H "x-api-key: $LIVELLM_API_KEY" \
    -d '{"plan":true}' \
    https://platform.live-llm.com/v1/me/tenant/workloads/my-box/state/apply

# Activity:
#   my-box has drifted from its machine state — 1 change(s) pending

# Drop "plan" to converge it back.
What this does and does not give you

It gives you reproducibility and a readable history: any machine can be rebuilt from its blueprint, and every change to it is a commit with a reason. It is not an undo button — reverting a commit converges the machine back, which is the right answer for packages, services and config, but not for something irreversible like dropping a database. Take a backup before that kind of change.

Machine shape as code →How agents use it →