Skip to content
Clonit

Connect Your Agent

Clonit runs fully standalone. Connecting your agent to Clonit Cloud is an optional step that unlocks team collaboration, cross-device access, and snapshot sharing. This page walks through the one-time setup: tell the agent where the cloud lives, authenticate, register the agent, and confirm everything works.

Before you start

Section titled “Before you start”

You need:

  • A Clonit Cloud URL for your deployment (for example https://cloud.clonit.ai, or your team’s self-hosted address).
  • A way to authenticate, either:
    • As a human: sign in through your browser with clonit login, or
    • For automation (CI/CD): a Clonit Cloud API key (cloud.api_key).

You do not need to create a separate password for Clonit. Identity is handled by an external sign-in service — Clonit never stores your password.

Step 1 — Set the cloud URL

Section titled “Step 1 — Set the cloud URL”

The agent only talks to the cloud when cloud.url is set. Open your config file in your editor:

clonit config edit

This opens config.yaml in $VISUAL, $EDITOR, or vi. Add (or fill in) the cloud section:

cloud:
  url: "https://cloud.clonit.ai"   # your Clonit Cloud deployment
  api_key: ""                      # leave empty if you'll sign in with `clonit login`
  agent_id: ""                     # set automatically after registration

Save and close the editor.

Step 2 — Authenticate

Section titled “Step 2 — Authenticate”

How you authenticate depends on whether a person or an automated job is running the agent.

Humans: clonit login

Section titled “Humans: clonit login”

Sign in interactively through your browser:

clonit login

Clonit runs an OAuth 2.0 Device Authorization Grant (RFC 8628): it prints a short code and a URL, opens your browser, and waits for you to approve the sign-in. Once approved, your session is saved locally and refreshed automatically. No API key or password is ever typed into the terminal.

Only cloud.url needs to be set — Clonit discovers the sign-in service from the cloud for you. Over SSH or in a headless shell, add --no-browser to print the verification URL instead of opening a browser:

clonit login --no-browser

Automation: an API key

Section titled “Automation: an API key”

CI/CD pipelines and other headless jobs should not use interactive login. Instead, give the agent a Clonit Cloud API key via cloud.api_key (set in the config file from Step 1, or through CLONIT_CLOUD__API_KEY). An organization admin issues these keys — see API Keys for how to create and manage them.

With an API key configured, the agent authenticates automatically on every cloud command — no clonit login step is required.

Step 3 — Register the agent

Section titled “Step 3 — Register the agent”

Registration introduces this machine to the cloud and assigns it a stable agent identity, so the cloud can attribute snapshots and activity to it.

clonit cloud register

By default the agent is named after your machine’s hostname. Give it a clearer name if you like — useful when several agents (laptops, CI runners) connect to the same organization:

clonit cloud register --name ci-runner-01

If the agent is already registered and you need to re-register it, pass --force:

clonit cloud register --force

Registration writes the assigned agent_id back into your config file automatically — you don’t need to set it by hand.

Flag Default Description
--name hostname Name to register this agent under
--force false Re-register even if already registered

Step 4 — Verify the connection

Section titled “Step 4 — Verify the connection”

Confirm two things: who you’re signed in as, and that the agent can reach the cloud.

Who am I signed in as?

Section titled “Who am I signed in as?”
clonit whoami

This shows the identity currently signed in to Clonit Cloud and validates your stored session, refreshing the access token if needed. It’s the companion to clonit login and clonit logout.

Is the agent connected?

Section titled “Is the agent connected?”
clonit cloud status

This reports the agent’s cloud connection status — the configured cloud URL, whether the agent is registered, and whether it can reach the cloud API.

A healthy setup looks like this end to end:

clonit config edit        # set cloud.url (Step 1)
clonit login              # sign in via your browser (Step 2)
clonit cloud register     # register this agent (Step 3)
clonit whoami             # confirm your identity
clonit cloud status       # confirm the agent is connected

Troubleshooting

Section titled “Troubleshooting”
  • whoami says you’re not signed in — run clonit login again. Interactive sessions expire and can be cleared with clonit logout.
  • CI job fails to authenticate — make sure cloud.api_key (or CLONIT_CLOUD__API_KEY) is set in that environment. Do not rely on an interactive clonit login session inside automation.
  • Registration says the agent already exists — that’s fine; the agent is already known to the cloud. Use clonit cloud register --force only if you intend to re-register it.

What’s next

Section titled “What’s next”

With the agent connected, you can use the rest of Clonit Cloud:

See also

Section titled “See also”