Getting started
Connect to Cercloud
Source: Cercano/docs/enterprise-connection.md. The current native account-management pilot targets macOS. Source-build examples below are preserved deliberately; packaged-client live acceptance is not established by this guide.
Enterprise commands now control the running Cercano host. The host owns sign-in, Keychain credentials, policy refresh and model authorization. The command-line client does not hold a second copy of the connection or rotate its credentials.
This increment activates model restrictions and shared skills. Main and delegated agents discover assigned skills and read the pinned versions through a read-only tool. See shared skills. Applying administrator routing defaults and ordered fallbacks is also implemented; see the implementation status.
Start and connect the host
The V1 account-management pilot supports macOS. Your administrator provides a trusted HTTPS service origin and organization UUID. Accept the organization's invitation in the browser before connecting Cercano. The service needs Google OAuth, a signing key and a published policy.
Use a build with a numeric version accepted by the policy. For local development:
cd source/server
go build -ldflags '-X main.version=1.0.0' -o bin/cercano ./cmd/cercano
bin/cercano agent
In another terminal, using the same build:
bin/cercano enterprise login --server https://enterprise.example --organization YOUR_ORGANIZATION_UUID
bin/cercano enterprise status
Replace the example origin and organization UUID with the administrator's values.
For a non-default local host, append --address 127.0.0.1:PORT to each enterprise
command. Commands do not start or upgrade a host automatically. An older host
returns an update-required error instead of creating an unenforced connection.
The ordinary dev version does not satisfy a numeric minimum version.
Login opens the system browser from the host. Google sign-in returns a one-use
code to a temporary loopback listener. The host exchanges it using PKCE, enrolls
this device, saves credentials in the separate cercano-enterprise Keychain
service, and verifies the policy and skills. Provider API keys remain in their
existing store.
Understand status and synchronization
status prints the organization and team, applied policy revision, authorization
deadline, and synchronization state. It distinguishes an unassigned team from
missing membership details. During an outage or blocked connection, displayed
membership describes the last applied policy, not proof of current access.
Use cercano enterprise status --json for these machine-readable host fields:
managedmeans the host is using an enterprise profile.enforcement_activemeans the model-request gate is installed for that profile. It remains active when work is blocked.connectedmeans the host has saved connection credentials.usablemeans a verified policy is currently within its authorization lease.membership_known,organization_name,team_id, andteam_namedescribe the last applied policy response. An absent team with known membership means organization policy applies without additional team restrictions.revisionandvalid_untilidentify the accepted policy and its deadline.changingmeans a connection change, such as browser sign-in, is in progress.
When synchronization fails, the host sends a best-effort report containing only a fixed error code and client version. It never sends raw error text, local paths, prompts, source code, or provider credentials. Reporting has a two-second deadline and cannot change whether the cached policy is usable. Older servers may ignore it; offline and revoked clients may be unable to report. The administrator sees the last successful acknowledgement until a complete bundle is applied again.
The host checks about once a minute, with bounded backoff after failures. Unchanged responses reuse the verified bundle without extending its lease. When fewer than two minutes remain, the host requests a fresh signed policy. Sign-in, restart and recovery after a failed check also require a full response. To request synchronization immediately:
bin/cercano enterprise sync
For an account saved by the earlier connection preview, sync explicitly
activates that account in the running host. A synchronization error can leave the
host managed and blocked; use status to inspect it and retry when service or
Keychain access is restored.
A temporary outage retains an already verified bundle only until its original lease deadline. A denial or failed verification blocks work immediately. A restart always requires fresh online verification; the disk cache cannot grant permission to run work. A restriction published during a turn applies before the next physical model request, including a retry or fallback.
Inspect the settings you can use
bin/cercano enterprise policy
bin/cercano enterprise skills
bin/cercano enterprise skills --skill enterprise/ORGANIZATION_UUID/SKILL_SLUG
policy lists the allowed provider, endpoint, model and placement for each route,
then the task defaults, ordered fallbacks and whether each choice is locked.
skills lists enterprise assignments with their source, namespaced IDs and exact
versions. Pass one of those IDs with --skill to read its text. These commands
read the running host's verified bundle; they do not fetch credentials or start
model requests. The ordinary host skill catalog combines built-in tool skills,
built-in workflow protocols, and enterprise assignments from the managed settings
snapshot. It does not discover personal or repository skill directories.
Append --json to get structured output. Policy and assigned skill inspection
require a usable managed bundle. If access is blocked or expired, use status
and sync to diagnose and recover. An inspection is a snapshot, not permission
for future inference: each actual request still checks current authorization.
Sign out or return to personal settings
bin/cercano enterprise logout
Logout removes local credentials and attempts server revocation. It leaves the host in a managed, blocked state, including after restart. If remote revocation fails, the command reports that failure even when local removal succeeded. A locked Keychain must be unlocked before removal can complete.
To deliberately return to personal settings after logout:
bin/cercano enterprise standalone
This is a separate, explicit mode change. It is rejected while credentials remain connected or work is active. Login and logout also require active work to finish. Personal model settings are preserved. A new login after logout enrolls a new host record.
One connection owner
The host holds the enterprise connection lock for its lifetime. Another process cannot rotate the same refresh credential or clear its managed profile. A host that was already running standalone notices another host's activation and blocks its own model requests rather than silently bypassing that profile.
Use the normal host connection for managed MCP access. An independently embedded MCP host cannot become a second enterprise connection owner. Its model requests remain blocked while the main host owns the connection. Restart a secondary host or explicitly select standalone there after the owner has logged out and released the connection.
Verification and local state
The trusted service origin supplies Ed25519 verification keys. The host rejects redirects, bad signatures, unknown policy schemas, wrong organization/member/host scope, older revisions, expired policies and unsupported client versions. Every skill must match the signed ID, version, length and SHA-256 digest. The bundle is accepted only after all downloads and persistence succeed.
~/.cercano/enterprise/active-bundle.json stores policy and skill content with
owner-only permissions. It contains no credentials and is not trusted after a
restart. The managed marker in that directory preserves the mode even when
Keychain credentials disappear. Only an explicit standalone command clears it.
Tests use disposable TLS servers, real signatures, an in-memory credential store and local gRPC. They cover browser callback and PKCE exchange, policy enforcement, updates, logout, restart, credential loss, lock ownership and explicit standalone mode. They do not sign into a real Google organization or modify your Keychain. Live Google and Keychain acceptance testing remains outstanding.