Client access

What an approved CLI client or a connected assistant can do, and how to end its access.

Connect your computer

Each connection needs your approval on your computer. Your computer's Home page shows the setup steps with your own address filled in. The rest of this page explains what each connection can do and how to revoke it.

Chat assistant

Claude, ChatGPT, Grok Bot, and more. No install.

Claude

In Claude, open Customize › Connectors and choose Add custom connector.
Name it EmptyOS and paste your connector address. If Claude asks for an OAuth client, choose Use Claude's published identity. Leave the client ID and secret blank.
```
https://yourname.emptyos.com/mcp
```
Choose Add, then Connect. Claude opens your computer in a tab. Choose Read-only or Full access, then approve.

The connector works on claude.ai, in the desktop and mobile apps, and in Cowork. The Free plan allows one custom connector. On Team and Enterprise plans, an Owner adds it for the organization, and each member then chooses Connect.

ChatGPT

Open ChatGPT's Plugins page. Choose Add, then Add custom MCP server.
Name it EmptyOS. Under Connection, paste your connector address. Choose OAuth for authentication and leave the client fields blank, then choose Create as a plugin.
```
https://yourname.emptyos.com/mcp
```
ChatGPT opens your computer in a tab. Choose Read-only or Full access, then approve.

Dots use the plugins in your ChatGPT account, so a Dot can use EmptyOS after this setup.

Grok Bot

Paste this into a chat with Grok Bot:

Add a custom MCP server named EmptyOS at https://yourname.emptyos.com/mcp

Open the sign-in link that Grok Bot gives you.
Choose Read-only or Full access, then approve.

Other MCP client

Add a remote MCP server at your connector address, and choose OAuth. The server uses Streamable HTTP.

https://yourname.emptyos.com/mcp

The client must publish a Client ID Metadata Document and use PKCE S256 with an HTTPS callback. EmptyOS does not issue a client ID or a client secret, so a client that asks for one cannot connect. Client access lists the full requirements.

Coding agent

An agent on your machine with a shell. Best for services, files, Git, and Databases.

Paste this into your agent. It installs the empty client, helps you get a computer if you need one, and asks you to approve the pairing.

Fetch https://emptyos.com/docs/agent-setup.md directly and follow it. Install the EmptyOS client here and help me create or connect my cloud computer.

If you already have an EmptyOS computer, add its address to the prompt. You sign in, choose a name, and approve the connection yourself.

Or set it up yourself

You need macOS or Linux, a currently supported Node.js release with npm, git, and ssh.

1. Install the client and its skill. The skill tells your agent how to operate the computer. For Claude Code, run empty skill install --dir ~/.claude/skills instead. See The empty skill.

$ npm install -g @emptyos/client
$ empty --version
empty client 0.1.25 (protocol 3)
$ empty skill install

2. Connect. Name the client with --label: lead with the agent, then the machine.

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

Approve the request only if the code and key on the page match what your terminal printed. You make that check and the approval yourself; your agent must not approve the request or tell you the values match. On a machine without a browser, add --no-browser and open the printed URL yourself.

3. 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 yourname.emptyos.com
View it (owner sign-in): https://hello.yourname.emptyos.com/
Only you can open it until you share it
Share it: `empty share hello --with <email>`
Make it public: `empty expose hello`
See all Things: `empty things`

It is now at https://hello.yourname.emptyos.com/, visible only to you until you share it.

Compare connections

Your computer lists every connection on Client access (https://yourname.emptyos.com/_system/agents): CLI clients under Workstation clients, and assistants under Connected assistants. The computer verifies your sign-in with your Google account.

	CLI client	Assistant
Connects with	`empty connect`, an SSH key, and a tunnel token	An MCP connector that signs in with OAuth
Access	Full: it works as your computer's own user	Read-only or Full access, chosen when you approve
Credentials	Stay on your workstation	Held by the assistant's service; your computer stores only a hash
Revoke	Revoke on Client access, or `empty computer remove <alias> --revoke`	Revoke on Client access
When unused	Stays approved until you revoke it	Signs itself out after 30 days

CLI clients

Approval covers the local empty client and its SSH key, not a particular agent. An agent that uses that client has the same access.

What approval grants

Approval gives the local empty client installation and its SSH key full trust to work as your computer's own user. Any program that can use that key can read and write your data, run commands, and change configuration.

The approval page shows a client label, a pairing code, and an SSH-key fingerprint. The pairing code and fingerprint must match what empty connect printed.

What stays where

The client creates its private key and tunnel token on your workstation. Both stay on the workstation. Pairing sends the public key and a hash of the token. The computer pins that public key. Only the approved key can use the tunnel. The client connects to your computer over HTTPS.

Revoke a client

Revoking removes the key, invalidates the token, and closes live connections. On Client access, find the client under Workstation clients and choose Revoke. A client can also retire itself: empty computer remove <alias> --revoke revokes only that client's own credential and then removes its local profile. Revocation does not undo work that an agent or another program did while the client had access.

A revoked client's next connection is refused with HTTP 401, and the computer records the refusal in its system log with the client's address, never the token.

Assistants

Your computer hosts an MCP server at your address plus /mcp. An assistant that supports remote MCP with OAuth can connect to it. The assistant opens your computer in a browser tab. If you are not signed in, sign in with your Google account. The request continues after you sign in.

Approve the connection

Your computer shows the service name, the client metadata URL, the callback origin, and what the connection can do. The service supplies its name. Check that you recognize both domains. The callback can use a different domain from the metadata document.

Read-only lets the assistant view status, the software version, Things and their settings, service logs, Projects, and Database names. The assistant cannot change the computer or read a Database's contents.
Full access lets the assistant act as the computer's owner, as an approved empty client does. The assistant can create, edit, and publish Things, including services. It can read and change Databases, manage sharing, and run code.

Code the assistant runs can access files and credentials, change settings, and affect other Things. Give Full access only to an assistant account you trust. A build command is not sandboxed.

Approve only if you just clicked Connect in your own assistant. If someone sent you a link to this page, choose Deny. Approving would give their assistant the access you select. The page cannot tell whose account started the request. You know whether you clicked Connect.

After you approve, the assistant finishes connecting. In Claude, a read tool is marked read-only. Claude uses that tool without asking each time. Claude asks before a tool that changes something, unless you chose Always allow. That prompt is Claude's. Your computer still refuses a change the connection is not allowed to make.

What an assistant can read

Tool	What it reads
`get_status`	Hostname, EmptyOS version, counts of Things, Projects, and Databases, and anything needing attention
`list_things`, `describe_thing`	Each Thing's type, route, URL, visibility, viewers, Project, linked Databases, service state, and Git state
`get_thing_logs`	Up to 1,000 recent journal lines of a service Thing
`list_projects`	Projects with descriptions and Thing counts
`list_datasets`, `describe_dataset`	Database names, types, sizes, the service variable, and which Things use each one

These tools return the same information as the matching empty commands. Either access level can call them. Querying a Database needs Full access.

The MCP reference lists every tool and its parameters.

What an assistant can change

All these tools need Full access:

Tool	What it does
`read_skill`	Reads the installed operating or build skill and its listed references without running a command
`start_command`	Runs a shell command as the owner; can wait up to 10 seconds for its result
`read_command`, `cancel_command`	Reads a command's output and result, or cancels the command
`publish_page`	Publishes one HTML document as a new private page
`read_page`, `update_page`	Reads a generated page's files, then replaces, adds, or removes some of them
`create_project`, `assign_project`	Creates a Project, or moves a page into one
`share_thing`, `unshare_thing`	Shares a Thing with one person by email, or stops sharing it
`set_thing_visibility`	Makes a Thing public or private

read_page and update_page work only with generated static pages (type: static) created by publish_page or empty put. They read or change committed files in public/. A service (type: service) can show a web page, but its source files go through start_command. The assistant first calls describe_thing to check the type and find the source directory. Custom static layouts, other files, and Databases also go through a command.

For short commands, start_command accepts wait_seconds from 0 to 10; the default is 0. If the command finishes during the wait, its result comes back in the same call. If the returned state is starting or running, continue with read_command using the returned operation ID. The wait does not stop the command or change its execution timeout.

A command keeps running if Gateway restarts. Undo in Home's Recent list restores the previous page. You cannot undo a command, a Database change, or a share from Home. When you share a Thing, EmptyOS emails the person a link to it. If EmptyOS sent no new email, the assistant gives you the link to send. The person opens it and signs in with Google as the email address you shared. Stopping the share does not remove what they already opened. Ask the assistant to stop sharing, or run empty unshare.

The MCP reference lists each tool's parameters and limits.

Change what a connection can do

Open Client access (https://yourname.emptyos.com/_system/agents). Choose Change access for an assistant. Select Read-only or Full access, then save. Choosing Full access requires Allow full access. The new access applies on the assistant's next request. When a tool needs Full access, the computer refuses the call and returns the Client access address.

A connection that previously had permission to edit pages or manage sharing stays Read-only until you approve Full access for it. A local empty client keeps Full access.

Revoke an assistant

On Client access, each assistant is listed under Connected assistants with the time it connected and the time it was last used. Choose Revoke. The computer refuses that assistant's next request. The assistant then asks you to reconnect. A connection that goes unused for 30 days signs itself out.

Revoke does not undo a change the assistant already made. It does not remove what the assistant already read. A command already accepted can still finish after you revoke the connection, lower its access, or turn connectors off. Revoke does not stop a process the assistant already started, or close a path it already opened. Deleting the connector in the assistant does not revoke it on your computer. Delete the connector in the assistant, and revoke it on Client access.

Turn connectors off

Connectors are on by default. To turn them off, open Settings (https://yourname.emptyos.com/_system) and turn the Assistant connectors switch to Off.

While connectors are off, the connector address returns not found. A request that starts in that time cannot connect, read, or change anything. Your computer stops telling visiting agents about the connector. Each existing connection keeps its access. Turn the switch back On, and each assistant resumes without a new approval, unless it has gone unused for 30 days. To end a connection for good, revoke it on Client access.

How sign-in works

Your computer is its own authorization server. A connection does not pass through EmptyOS's control plane. A token is random, expires after an hour, and refreshes while the connection is in use. The computer stores only the token's hash. Each connection's access is stored with its credentials and checked on every request.

Assistant requirements

An assistant identifies itself with a published HTTPS client metadata document. The computer fetches that document before showing the approval page. The client ID and the callback must match the document exactly. A metadata URL and a callback must be canonical HTTPS URLs on DNS names. Neither URL may include credentials, a fragment, or a custom port. A metadata URL needs a path to a document. The computer refuses a local hostname and an IP address. The metadata host must resolve to a public address. The computer does not support a native loopback callback, dynamic client registration, or client-secret authentication. It does not accept a pre-registered client ID either, so an assistant that asks you for a client ID cannot connect.

An invalid or unavailable document shows an error on your computer. The computer does not redirect to an unverified callback. An approved connection keeps working without fetching the document again. Revoke the connection if you no longer trust its service.