Skip to main content

Enterprise Connector

Audience: Developer

Context: Read this page when open-source usage needs to connect a runtime or workspace to an enterprise-managed environment.

What The Connector Is​

The enterprise connector is the public integration boundary between:

  • the open-source Caracal runtime and its public developer surfaces
  • the enterprise-managed environment that provides shared administration and connected operations

From a developer perspective, the connector exists so an otherwise open-source runtime can:

  • connect to an enterprise environment through approved public inputs
  • move between open-source-only and enterprise-connected operation
  • expose connection, sync, and status workflows through public commands
  • adjust certain runtime behaviors when enterprise-managed operation is active

System Boundary​

Treat the systems as having different responsibilities:

  • the open-source runtime owns local execution, enforcement, and the public CLI, TUI, and SDK integration points
  • Enterprise owns organization-level administration, shared operational workflows, and enterprise-managed connected behavior

The connector is the handshake layer between those responsibilities. It should be documented in terms of behavior, public configuration, and usage, not private implementation.

High-Level Data Flow​

At a high level, the connector flow looks like this:

  1. A developer or operator provides approved enterprise connection details.
  2. The runtime records the connection state for the selected workspace or environment.
  3. Enterprise-connected behavior becomes available through the public runtime surface.
  4. The runtime can report connection status, perform synchronization, or disconnect when requested.
  5. If the workspace is disconnected, it returns toward open-source-only behavior.

Public Configuration And Usage​

The connector is operated through public configuration and commands.

Public configuration inputs​

Depending on your workflow, the connector may use public environment or runtime settings such as:

  • CARACAL_ENTERPRISE_URL
  • CARACAL_GATEWAY_ENABLED

Use only organization-approved values for those inputs.

Public command path​

The standard public connector workflow is:

  • caracal enterprise login <url> <token>
  • caracal enterprise status
  • caracal enterprise sync
  • caracal enterprise disconnect

These commands are the supported developer and operator entry points for enterprise connectivity from the open-source side.

Developer Guidance​

  • Build against the connector as a boundary, not as a mirror of enterprise internals.
  • Assume Enterprise may evolve behind that public boundary without exposing its private implementation.
  • Treat enterprise-specific SDK surfaces as separate product surfaces from the core open-source runtime.
  • Keep documentation focused on what the runtime accepts, reports, and changes publicly.

Constraints​

  • Enterprise internals are not part of the connector surface.
  • Public connector behavior may affect runtime workflows such as sync status, connected mode, and certain managed-provider expectations.
AI tools
On this page