Getting started

Install the client, create a computer, connect an agent.

EmptyOS gives you one persistent Linux computer at a name you choose. It starts empty. You put things on it yourself or through an agent. The home page, the command line, and any apps on it are yours to change, and every change is a git commit.

Tell your agent

Read https://emptyos.com/docs/start.md, then install the empty CLI on this machine and connect to https://anything.emptyos.com

Replace anything.emptyos.com with your computer's hostname. Your agent installs the client on the machine where it is running and connects to your existing computer. This does not require changing DNS, setting up an exe.dev account, or running an EmptyOS server locally. If you do not have a computer yet, create one in step 2. You sign in with Google to create the computer and approve the agent's access in your browser.

Computers are invitation-only for now. This line changes when signup opens.

Before installation

Agents can read the actual EmptyOS Computer skill before any software is installed. The official client package is @emptyos/client, and its command is empty.

Fetching these docs, downloading packages, and connecting to a computer all need network access, even for read-only requests. In a restricted agent runtime:

• Request the narrow network permission needed for the command and destination through the runtime's approval mechanism. Use sandbox escalation when that is how the runtime grants access; reuse an existing permission when it applies.
• If a fetch fails with a DNS or connection error, check those permissions before concluding that the site or computer is unavailable. Once access is approved, retry the same read-only request. If it still fails, investigate the hostname and network without assuming the sandbox is the cause.
• If permission is denied or unavailable, report the blocked action and the reason. A denial or cancellation is not approval. Do not substitute an unrelated package or repository because the official site could not be fetched.

1. Install the client

Requires Node 20 or newer, npm, and git and ssh on PATH. macOS and Linux. On a fresh machine, check that these commands exist first. If Node or npm is missing, install a supported LTS release with npm from the official Node.js downloads, then verify node --version and npm --version. Install missing Git or OpenSSH client tools through the operating system's package manager.

$ npm install -g @emptyos/client
$ empty --version
empty client 0.1.7 (protocol 2)

If npm reports EACCES, use a writable user installation rather than changing system-directory permissions; see npm's installation guidance. Ensure the executable directory is on PATH in the current shell and future sessions.

The client includes the agent skill. Run empty skill install, then read SKILL.md in the printed directory during this session. See The empty skill for other agent directories and an npx alternative.

2. Create a computer, or use the one you have

If you already have a computer at emptyos.com, go to step 3. Otherwise open the signup page with the name you want:

https://app.emptyos.com/signup?name=anything

You sign in with Google and confirm the name. Provisioning takes a few minutes and ends at your computer's home page, https://anything.emptyos.com.

A name is lowercase letters, digits, and hyphens. If it is taken, choose another on the signup page. Signup is invitation-only; the page says so if your account is not invited.

3. Connect

$ empty connect https://anything.emptyos.com
Pairing code: 7K3MQ2ZD
SSH key: SHA256:9f2cQx1Vb3e8RZs0KpD4w7LmYt6nHaJc2uXoEiVgN5A
Approve it at:
  https://anything.emptyos.com/_system/agents
Opening the approval page in your browser...
Waiting for approval...

The command opens the approval page in your browser and waits. Check that the code and key on the page match the ones printed, then approve. A request expires after five minutes; run the command again for a new code.

On a remote Linux machine or another machine without a browser, use:

$ empty connect https://anything.emptyos.com --no-browser

The agent should show you the printed approval URL, pairing code, and SSH-key fingerprint, then leave the command running while you open the URL in your own browser and approve the matching request. The agent must wait for approval and the command's successful completion before reporting that it is connected.

Approval is full trust. Your agent now acts as the computer's own user, with the same access as the resident agent. You can revoke it on the same page at any time. Once approved, the command finishes:

Successfully connected computer anything (anything.emptyos.com) and selected it as the default
List computers with `empty computers`

4. Check the connection

$ empty computer show
anything  anything.emptyos.com  (default)
$ empty things
Computer anything is empty — no Things yet

Put its first Thing:
  empty put <path> [--as <id>]

empty --json is the complete overview of the computer: Things, Projects, Data, and recent changes.

The first connection selects the new profile automatically. If another default already exists, keep it and explicitly check the newly connected alias with empty --computer anything status --json. Use empty computer use anything only when that computer should become the default.

5. Put something on it

$ empty put hello.html --as hello
Installed private static Thing hello from 1 file (61 bytes) at /home/exedev/things/hello
On anything.emptyos.com
See all Things: `empty things`

It is served at https://anything.emptyos.com/hello. Only you can open it until you share it with a named EmptyOS account or make it public. See Sharing for both choices, and Put, clone, publish to change it.

When something goes wrong

For an existing profile, a read-only connection check is empty --computer <alias> status --json. Follow the network guidance before installation if it fails. A DNS failure alone is not a reason to remove a computer profile.

Every page here is also markdown at the same path with .md added. emptyos.com/llms.txt lists them.