Xybrid

xybrid connect

Connect a project to a claimable Xybrid workspace without signing in

xybrid connect gives a project a Xybrid key without an account. It is built for coding agents: no browser and no sign-up. It creates (or reuses) a provisional workspace with a restricted, client-scoped key, saves the key privately, and keeps a private link that a person uses to claim the workspace with GitHub.

It never prints the key and never turns on trace export. It needs CLI 0.18.0 or newer.

Usage

xybrid connect --write-env .env
xybrid connect --write-env local.properties
xybrid connect --agent claude-code --write-env .env --json

Run it from the project's repository. Credentials are kept per repository and platform host.

Options

OptionDescription
--write-env <PATH>Write the key to this untracked project file and gitignore it
--env-name <VAR>Variable to set in --write-env. Default XYBRID_API_KEY, or xybrid.apiKey in a .properties file. For Expo, pass EXPO_PUBLIC_XYBRID_API_KEY
--agent <NAME>Self-reported agent name, for example claude-code. Detected from CLAUDECODE=1 when possible
--project-name <NAME>Name for a new workspace or project. Default: the repository's directory name
--newCreate a new workspace even if this project has saved credentials. Never replaces a key already in the project file
--allow-ciConnect even when a CI environment is detected. Privacy opt-outs still apply
--allow-custom-hostAllow a --platform-url other than the Xybrid production or staging API. HTTPS is required unless the host is localhost
--jsonPrint one JSON object instead of text

Project files

--write-env accepts three kinds of file. Any other file name is refused.

FormatFile namesDefault variable
dotenv.env, .env.* (such as .env.local), *.envXYBRID_API_KEY
Java propertieslocal.properties, *.propertiesxybrid.apiKey
xcconfig*.xcconfigXYBRID_API_KEY

Other lines in the file are kept as they are, and a value that is already set is never replaced. Above the key, connect writes a comment with the claim command and the workspace's dates. The comment never holds the claim link.

What it does

  1. Checks first, before anything is created. connect stops in CI unless you pass --allow-ci. It stops when a privacy opt-out is set (XYBRID_TELEMETRY_OPTOUT, DO_NOT_TRACK or OTEL_SDK_DISABLED=true). It stops when Git tracks the --write-env file. It also checks for a key the project already has and for a writable private credentials store.
  2. Reuses or creates. A project with a saved key reuses it. A second repository on the same machine becomes a new project in the same unclaimed workspace. Otherwise connect creates a new workspace, which takes a few seconds.
  3. Saves the key. The key and the claim token go to the private store, ~/.xybrid/credentials.json (XYBRID_CREDENTIALS_FILE moves it). With --write-env, the key also goes to the project file, and the file is added to .gitignore.

Later commands in the same repository use the saved key when neither --api-key nor XYBRID_API_KEY is set.

Exit codes

ExitStatusMeaning
0created, existingThe project has a key: a new one, or the one it already had
3signup_closedXybrid is not creating agent workspaces right now
4offlineXybrid could not be reached
5ci_skipped, opted_outA CI environment or a privacy opt-out was detected
6env_file_trackedGit tracks the project file. Choose an untracked file
7workspace_expiredThe saved workspace's key expired, but the workspace can still be claimed
1errorAnything else. error.code in the JSON says why

JSON output

--json prints one object. It never contains the key, only a preview such as sk_live_AbCd1234….

FieldContent
schema_version1
statusOne of the statuses above
tell_the_userA message for the person, including the claim link when there is one
keysource, preview and scope
env_filepath, variable, written, already_configured, gitignored, and suggestions when the file is tracked
credentialspath, saved, and recovery (whether xybrid auth claim can show the link again)
workspaceOrganization and project, key_expires_at, claim_expires_at, limits and the terms and privacy links
claim_urlThe private claim link
verificationWhether traces from this project have been stored
next_stepswire_init, verify and relay, each with a summary and sometimes a command

The claim link is private. Anyone who opens it and signs in can claim the workspace, so keep it out of commits, pull requests, issues and logs.

After connecting

  • Turn on trace export yourself. A key alone exports nothing. Configure the Xybrid observability preset in your app, or add --observability to a CLI command. See API keys.
  • Check that a trace arrived with xybrid auth status.
  • Claim the workspace. Unclaimed, the key stops after 7 days and the workspace is deleted after 14 days. You can claim until it is deleted, and claiming restores a stopped key. xybrid auth claim shows the link again.

Coding agents can follow the xybrid-connect skill, which also wires metadata-only export for each SDK. It lives in agents/skills/xybrid-connect.

On this page