← Back to Hub Guide
User Guide · Closed Beta

Connect Your First Machine

Install Coral, approve a short code, then open your first agent.

A machine is the computer running Coral and your agents. Install Coral there first, connect it to Coral Hub, and then start an agent. Keep that computer running and online while you use the Hub.

Prerequisites

1. Install and open Coral on your computer

Use the official Coral release downloads. In the filenames below, replace <version> with the release version you download. Follow the official download verification instructions before opening the package. The macOS app is signed and notarized by Apple. If you use SHA256SUMS.txt, take it from the same release as your download; follow the official instructions for release-attestation checks.

./coral --cloud-url https://app.coralhub.dev

For a terminal installation with coral on your PATH, use coral --cloud-url https://app.coralhub.dev. Keep the process running. On the same computer, the default local dashboard is http://localhost:8420. Use the address printed by Coral if you configured a different port. A headless computer uses the same command; approve its code in a browser on another device.

2. Add your machine

  1. Sign in to Coral Hub with your beta account. Open Servers and find the Add a machine section.
  2. On the computer running Coral, open Settings and choose Connect to Coral Hub. Use https://app.coralhub.dev as the hub address. For the terminal command above, follow the short-code instructions it prints.
  3. Enter the short code in Add a machine and select Continue.
  4. Check the code and machine details on the approval page. Give the machine a name and select Approve this machine only if you initiated this connection. Machine-supplied details are not independently verified identity. Do not approve a code someone else sends you.
  5. When the page says Connected., choose Open Servers. Confirm that your machine is online. You choose the access when you connect a computer, and Coral Hub never gives more than the computer allows.

3. Start and open your first agent

  1. Check the Hub access column on the Servers tab (in your dashboard’s top navigation) before filling in the agent form. View lets you look; starting an agent remotely requires effective Launch access. Set the Hub mode and, on your own computer, Settings → Network and Hub (open the menu in the top bar and choose Settings; in older Coral versions the section is Settings → Coral Hub) as appropriate. The lower setting wins. See the access modes guide.
  2. After the machine is online and has the required access, open Agents, choose +New → AI Agent, select your connected machine and installed CLI, and choose a working folder on that machine.
  3. Review the CLI permissions, enter a simple first task and choose Launch. For a first check, try: “Say hello and wait for my next instruction. Do not change any files.”
  4. Open the agent and check for a response. If startup trust or hook review needs attention, use Open terminal and review the prompt yourself before continuing.
  5. Open the Needs-you inbox to find waiting agents across your own connected machines. Its Open agent action takes you back to the agent; the inbox itself is read-only, and offline machines or read limits can make it partial.

If you prefer to keep Hub access at View, start the agent in Coral on your own computer and watch it through the Hub. Responding remotely requires at least effective Interact access.

If your first agent appears stuck

In an early beta walkthrough, Chat displayed Connecting and marked messages Sent even though they were still in the terminal input. Do not keep sending duplicates. Open the terminal, inspect the pending text, and submit it only if it is the instruction you intend. Enlarge the browser window if the active terminal prompt is clipped. Check the terminal for startup prompts even when the inbox says nothing needs you.

These observations came from an early beta walkthrough, not a clean production install. Later Coral releases include startup-prompt and chat fixes; this walkthrough has not verified them end to end. The public installer and a new provider sign-in were not tested, and there is no verified setup-time claim.

Turning Coral Hub off on a computer

To stop a computer from ever connecting to Coral Hub, start Coral with the hub address switched off (or set CORAL_CLOUD_URL=off). Nothing is sent to a hub until you connect:

$ coral --cloud-url off

Note that --cloud-connect=off is different: it only stops Coral from offering to connect when it starts on a computer that is not connected yet. You can still connect from Settings, and a computer that is already connected stays connected. To disconnect one, use Disconnect in Settings → Network and Hub (in older Coral versions, Settings → Coral Hub), or Revoke on the Servers page.

Troubleshooting

Issue Resolution
Code expired Pairing codes expire if left unused. Generate a fresh code in Coral Settings or restart the headless process.
Machine shows stale The machine temporarily lost network connectivity. Coral automatically retries. Verify outbound internet access.
Corporate Proxy If your network requires a proxy, configure standard HTTPS_PROXY and NO_PROXY environment variables.

Privacy & Control

Your agents run on your machine. Coral Hub relays dashboard traffic between your browser and that machine over encrypted connections; see the privacy policy for data handling and retention. View mode is read-only. You stay in control: revoke access from Coral Hub at any time. See Coral Hub Privacy for details.

← Previous Topic
1. Getting Started & UI Tour
Current Page
2. Connect Your First Machine

See also: Signing in with Google, Coral docs: remote access, Coral docs: multi-server hub.