Connect your first host

Enroll a machine you operate as an OpenComputer. Your first success is a completed hostname command on that exact machine, followed by a verified service restart. A saved key or an online badge alone is not the finish line.

Before you start

• Outbound HTTPS and WebSocket access on port 443, including access to GitHub release downloads and api.miosa.ai.
• Shell access as the user that should run the agent, plus curl and a POSIX shell on Linux or macOS.
• A MIOSA account with access to OpenComputers, and either the miosa CLI or a platform API key authorized for the intended organization.
• sudo access and systemd if you follow the Linux background-service section.

Choose the agent’s OS user deliberately: its permissions determine which local files and services the host can reach. See the security model before connecting sensitive workloads.

1. Install the agent on the machine

2. Register the host and save its key

The host key authenticates this machine’s agent. Your platform API key authorizes REST requests from your terminal or backend. They are different credentials and are not interchangeable.

3. Point the agent at MIOSA

On the machine itself, configure the connection with the OSA agent:

osa opencomputers login
osa opencomputers enable --no-profile

Paste the host key when prompted by login. The prompt accepts the credential as terminal input; use a private terminal session. Configuration is written under the agent user’s ~/.osa directory, including open_computers.toml and the open_computers.ed25519 identity file. Preserve that identity when updating the agent.

login saves the key and enable enables host mode. Neither command proves that a live session has started.

4. Start the host session

Start the headless agent in the machine’s terminal:

OSA_OPEN_COMPUTERS_ENABLED=true osa serve

Keep it running while completing the first check from another terminal. The agent initiates an authenticated outbound WebSocket connection to MIOSA. No inbound management port or public IP is required.

Open the host in MIOSA, or list it from your terminal, and confirm a fresh heartbeat and the capability needed for command execution:

miosa host list --tag studio
miosa host get <host>

If the host does not connect, follow Host stays offline.

5. Complete a command on the selected host

Use the IDs from your own request and the same authorized organization context. An accepted request is not proof that the command completed. Keep the API key in your backend or terminal environment.

6. Run the agent as a service

After the command passes, stop the foreground osa serve process before starting a second instance.

Expect an active service, then verify a new heartbeat in MIOSA and repeat the hostname request. An enabled service should start at boot, but verify that behavior after a scheduled reboot before relying on unattended work.

7. Disconnect or retire the host

For temporary maintenance, stop dispatching new work, inspect running jobs, and stop the agent:

miosa host jobs <host>
sudo systemctl stop osa-opencomputers.service

The unit remains enabled for the next boot. For retirement, disable startup, log the agent out, and revoke the host:

sudo systemctl disable --now osa-opencomputers.service
osa opencomputers logout
miosa host rm <host> --yes

Revocation and logout do not erase the machine’s files, and they do not prove that every child process has stopped. Verify active work before removing access or retrying it elsewhere.