Connect your first server

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

Before you start

• A Linux x86-64 server with 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.
• A MIOSA account with access to OpenComputers and a platform API key authorized for the intended organization.
• sudo access and systemd if you follow the background-service section below.

The OSA prebuilt Linux target is x86-64. For Linux ARM64, follow the OSA source installation instructions rather than assuming the prebuilt installer supports it. This walkthrough uses command execution; it does not require a desktop or GPU.

Choose the agent’s OS user deliberately: its permissions determine which local files and services it can access. See on-premises data boundaries before connecting sensitive workloads.

1. Install and check OSA on the server

Use the current installer from the OSA repository:

curl -fsSL https://raw.githubusercontent.com/Miosa-osa/OSA/main/scripts/install.sh -o /tmp/osa-install.sh
sh /tmp/osa-install.sh
osa version

If osa is not found, open a new shell and run osa version again. Follow any platform-specific instructions printed by the installer. For a pinned release, use the version-selection instructions in the OSA installation guide.

2. Register the host and save its key

Open OpenComputers in MIOSA, choose Connect a computer, and register the server in the intended organization. Give it a recognizable name, such as lab-server, and select Linux. Save the returned host ID and one-time host 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.

On the server, configure the host connection:

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; enable enables host mode. Neither command proves that a live connection has started.

3. Start the host connection

Start the headless OSA process in the server 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 and confirm a fresh heartbeat and the capability needed for command execution. If it does not connect, follow Host stays offline.

4. Complete a command on the selected host

In a separate trusted terminal, set your platform API key and the returned host ID:

export MIOSA_API_KEY="<your-platform-api-key>"
export HOST_ID="<your-host-id>"

curl --fail-with-body -sS "https://api.miosa.ai/api/v1/opencomputers/hosts/$HOST_ID" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

The response contains a host object. Confirm its ID, name, heartbeat, and capabilities correspond to this server. Then run a read-only command:

curl --fail-with-body -sS 
  -X POST "https://api.miosa.ai/api/v1/opencomputers/hosts/$HOST_ID/exec" 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"cmd":"hostname","stream":false,"timeout_ms":10000}'

Expected result, with your own job ID and hostname:

{
  "job_id": "<job-id>",
  "exit_code": 0,
  "stdout": "lab-server\n",
  "stderr": ""
}

Compare stdout with hostname run directly on the server. For long-running commands, use the streaming exec contract instead of this short collected-output check.

5. Run the agent as a Linux service

After the command passes, stop the foreground osa serve process before starting a second instance. The following systemd unit runs under the same user and home directory that hold the configured identity. Run these commands as that user, not from a root login shell. If this unit already exists, inspect it before replacing it; preserve any site-specific service restrictions or configuration.

OSA_HOST_BIN="$(command -v osa)"
OSA_HOST_USER="$(id -un)"

sudo tee /etc/systemd/system/osa-opencomputers.service > /dev/null <<EOF_UNIT
[Unit]
Description=MIOSA OSA OpenComputers Host
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=${OSA_HOST_USER}
Environment=HOME=${HOME}
Environment=OSA_OPEN_COMPUTERS_ENABLED=true
ExecStart=${OSA_HOST_BIN} serve
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF_UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now osa-opencomputers.service
systemctl status osa-opencomputers.service --no-pager

Expect an active service, then verify a new heartbeat in MIOSA and repeat the hostname request. During a maintenance window, restart the service and repeat those checks:

sudo systemctl restart osa-opencomputers.service

An enabled service should start at boot, but verify that behavior after a scheduled reboot before relying on unattended work. Other service managers need their own startup configuration under the same agent user.

6. Disconnect or retire the server

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

sudo systemctl stop osa-opencomputers.service

It remains enabled for the next boot. For retirement, disable startup as well:

sudo systemctl disable --now osa-opencomputers.service
osa opencomputers logout

Revoke the host through MIOSA when it should no longer authenticate. Revocation and logout do not erase the server’s files or prove that every child process has stopped. Verify active work before removing access or retrying it elsewhere.