Connect Your Agent

Connecting your agent to Clonit Cloud 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, and confirm everything works. (Registering the agent — Step 3 — is itself optional; it’s only for remote management.)

Note

Connecting to the cloud changes nothing about how your local snapshots, targets, and storage profiles work — cloud features layer on top.

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

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.

Tip

Prefer environment variables (handy in CI and containers)? Set the same values without touching the file:

export CLONIT_CLOUD_URL="https://cloud.clonit.ai"
export CLONIT_CLOUD_API_KEY="clt_your_api_key_here"   # CI/CD only

The prefix is CLONIT_ and nested keys are separated by _ (single underscore). See Configuration for the full precedence rules.

Step 2 — Authenticate

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

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

Note

Your session (access and refresh tokens) is stored in credentials.json in the Clonit config directory with 0600 permissions, separate from config.yaml. See the login command for all options.

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.

Least-privilege agents

By default an org API key has full org access — it can list every cloud target, retrieve any target’s connection config, and pull any snapshot. A CI/CD agent rarely needs all of that. Instead, mint it a target-scoped, pull-only key:

clonit cloud api-keys create --name ci-pull \
  --scope-target proddb --permissions pull

A key scoped with --scope-target is confined to a strict allowlist: target listing, config retrieve, and snapshot pulls only reach the targets in the scope — everything else in the org is invisible to that key. Snapshot push is allowed only when the key is unscoped or the target is in the scope; a key scoped only to SSO groups grants no push at all. --permissions pull additionally blocks uploads even for in-scope targets.

If a scoped key leaks, the blast radius is one pipeline’s targets — not the org. See clonit cloud api-keys for the full command reference.

Step 3 (optional) — Register for remote management

You can skip this step. Pushing, pulling, sharing, and every other day-to-day cloud operation work with just Steps 1–2. Registration exists for one thing: letting Clonit Cloud remotely manage this machine — it appears in the fleet list (Settings → Organization → Registered Agents in the web UI) and can receive cloud-relayed commands (the agent holds an outbound connection; the cloud pushes work down it). CI runners and one-off laptops generally don’t need it.

Register only if you want this machine remotely controllable:

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

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

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?

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 whoami             # confirm your identity
clonit cloud status       # confirm the agent is connected
clonit cloud register     # OPTIONAL (Step 3) — only for remote management

Two ways to connect, at a glance

• You, on your laptop: clonit login — one browser approval gives you both your identity and a least-privilege, user-scoped key. Nothing to copy.
• CI/CD (headless): set cloud.url + an org cloud.api_key. No login, no registration. See API Keys — note that org keys have full org access, so treat them as automation secrets.

Troubleshooting

Caution

cloud.url is required. If clonit login, clonit cloud register, or clonit cloud status complain that the cloud isn’t configured, re-check Step 1 — cloud.url must point at your deployment. Run clonit config show to see the resolved configuration and confirm the value took effect.

• 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

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

• Sign In & Login — how human sign-in works in depth
• Push & Pull via Cloud — move snapshots through the cloud’s managed storage
• Sharing Snapshots — share snapshots across your team
• Organizations & Teams — members, roles, and access
• API Keys — create and manage keys for automation

See also

• cloud command — full reference for clonit cloud subcommands
• login · whoami · logout
• Configuration — config file, environment variables, and precedence
• Clonit Cloud overview — what Clonit Cloud adds