What you can change

What you can edit, what you add under local/, and what you cannot change.

An EmptyOS computer is an ordinary Linux computer that belongs to you. The software that makes it an EmptyOS computer is a Git repository in your home directory. Your agent can edit that repository.

What is where

Each location holds a different part of the computer:

• ~/emptyos holds the platform software. This includes Home, Gateway, the resident empty CLI, EMPTY.md, and the resident skills. You can edit these files. Each platform change is recorded as a commit.
• ~/things/<id> holds your software, with one Git repository per Thing.
• ~/projects and ~/data hold your Projects and Databases. Updates never write to these directories.
• The emptyos-* systemd units run the system services. Your agent has a shell and sudo. Every platform name contains emptyos, so grep -ri emptyos over system configuration finds the platform configuration.
• /opt/emptyos-recovery holds sign-in, /_system, and recovery. These files are root-owned and not for direct editing. Only a signed release replaces them. The host owns TLS.

How to change something

Ask your agent. It works inside with empty ssh, reads ~/EMPTY.md, and commits to the repository that owns the change. Agents change ~/emptyos only when you ask for that change.

Platform commits show in Changes as history. Undo covers Thing changes. Reversing a platform edit is a Git operation.

A site's or service's ID determines its stable hostname. You can change its display name without changing that URL. Sharing and public/private changes also keep the address. Undo/Redo of an eligible private site-to-service conversion keeps the same hostname and browser storage; it does not revert Databases. Retired hostname reservations live outside Thing Git, so Undo cannot free a deleted Thing's hostname for a different Thing.

Add without editing platform files

~/emptyos/local/ is reserved for you. No release ships a file there, so files there cannot conflict with an update.

Custom CLI commands

Add a custom command when you need an empty command the CLI does not ship. Editing a shipped platform file can conflict with a later release. Releases do not replace files under local/commands/.

An executable regular file at ~/emptyos/local/commands/empty-<name> becomes empty <name>. Hyphens after empty- become spaces. empty-thing-backup becomes empty thing backup. Use lowercase letters or digits within each word, separated by single hyphens. The CLI ignores symlinks in that directory.

empty commands lists built-in commands and your custom commands. A built-in name always wins. If a custom command uses a built-in name, empty commands reports the collision. The custom file does not run.

Write the file on the computer. Make it executable with chmod +x <path>. Commit it in ~/emptyos to record the change. The custom command runs as your user.

Hooks

Add a hook when you want your own script to run after a change, without editing the code that made the change. Hooks run after the change is applied. A failing hook does not undo that change.

empty hooks lists the events and the hooks you have installed. The events are:

• post-update after a platform update
• thing-installed after a new Thing is installed
• thing-activated after a Thing activation succeeds
• thing-activation-failed after a Thing activation changes the live state and fails
• thing-exposed after a Thing becomes public
• thing-unexposed after a Thing becomes private
• post-undo after Undo

Commands that change nothing do not fire hooks. Redo does not fire post-undo.

Each event has a directory ~/emptyos/local/hooks/<event>.d/. Every executable regular file in that directory runs after the event, in filename order.

To install a hook from a file on the computer, run empty hook install <event> <path>. The command copies the script into the event directory, makes it executable, and commits it.

Home

Home links local/home/home.css at the end of the page if the file exists. If local/home/fragment.html exists, Home includes it at the end of the page too.

How updates keep your changes

For each platform file, the updater compares three versions: the last release, your copy, and the new release.

• If you did not change a file, the updater installs the release version.
• If you changed a file that the release did not change, the updater keeps your copy.
• If you and the release changed the same file, the update stops and asks your agent to merge only those files. The updater checks the result before installation.

See Updates for the commands.

What you cannot change

The empty CLI cannot change sign-in and recovery, the release signing key, your computer's address, or the Linux distribution. The machine underneath is still a normal Linux machine, hosted on exe.dev.