Installations and placement

Three resources describe where an Agent is placed and which governance applies there. A2A endpoints, ConnectedRuntime enrollment, Memory, budgets, policies, and resource subscriptions all refer to them.

ExternalInstallation

One paired, Workspace-owned record of an external system tenant. exti_…

CollaborationSpace

One governed scope inside that installation. cspace_…

AgentPlacement

One Agent placed across selected CollaborationSpaces with a declared identity posture. aplace_…

You do not need any of them to start a Session. A Session created with POST /v1/sessions has no installation, space, or placement. Create these resources when you need an A2A endpoint, a scoped policy or budget, scoped Memory, or a governed resource subscription. Checkfu does not operate messaging adapters. To connect a messaging app, see Connect your own messaging app. These resources place work and scope governance. They do not own Agent execution, a transcript, or an approval ledger.

What uses them

Consumer	How it uses the resources
A2A	Each active AgentPlacement and CollaborationSpace pair has an Agent Card URL and a JSON-RPC URL
ConnectedRuntime	Enrollment creates or recovers an ExternalInstallation, a private root CollaborationSpace, and an AgentPlacement, and stores both IDs on the runtime
Memory	A CollaborationSpace is a scope that Memory is shared in or kept out of
Budgets and policies	A CollaborationSpace can be matched by a budget or an ActionPolicy
Resource subscriptions	A watched-resource subscription names the space, installation, and Connection it belongs to

ExternalInstallation

An ExternalInstallation links one external system tenant to a Checkfu Workspace. You identify it with provider and external_tenant_id, and you can add a display_name. Creating or reactivating it requires a short-lived signed pairing proof bound to the exact Workspace, tenant, operation, and installation identity. Issue the proof with POST /v1/external-installations/pairing-proofs, then pass it as pairing_proof to POST /v1/external-installations. Checkfu validates and consumes the proof once. The pairing proof establishes the installation. It does not authenticate later requests from the external system. Anything you build on an installation authenticates its own callers. Credentials for the external system stay with you. They do not appear on the ExternalInstallation, in Session events, in a Harness, or in a Computer. The lifecycle is active, disabled, disconnected, or uninstalled. Checkfu treats the live installation as authority. Holding a token for the external system does not make a disabled installation active.

CollaborationSpace

A CollaborationSpace is the governed scope used by policy and admission. Create one with POST /v1/collaboration-spaces.

Field	Meaning
`external_installation_id`	The installation the space belongs to
`external_id`	Your opaque identifier for the space, 1 to 512 characters
`kind`	`root`, `team`, `channel`, or `personal`. These are scope levels, not a messaging feature
`parent_id`	The parent space. `null` for `root`, required for the other kinds
`visibility`, `membership`, `inheritance`	How the space is seen, how members are decided, and what it inherits

root
├── team
│   ├── channel
│   └── personal
├── channel
└── personal

Permissions, policies, Memory, budgets, audit, and retention refer to the CollaborationSpace. Private and personal spaces fail closed unless the required membership evidence is positively verified. Display names, email addresses, and unsigned fields are not membership authority. A collaboration_space_id you put on a request does not grant access, join Memory, pick a budget, or place a transcript. Checkfu trusts a space only when it comes from an admitted placement.

AgentPlacement

An AgentPlacement places one mutable Agent on one or more CollaborationSpaces. Create one with POST /v1/agent-placements.

Field	Authority
`agent`	The mutable Agent. Session admission selects its immutable AgentVersion
`environment_id`	The Environment admitted for Sessions launched through the placement
`external_installation_id`	The installation the placement belongs to
`collaboration_space_ids`	One to 1000 spaces in that installation
`identity_posture`	`autonomous` or `delegated`
`acted_as`	The Principal whose permissions apply
`harness`	The Harness the placement uses

The placement coordinates these authorities. It does not copy the Agent or create another ACL.

Identity posture

autonomous means the placement acts as its own service Principal. Its Connections and PermissionAssignments belong to that service identity. delegated means the placement acts as a person Principal. The acting identity must satisfy the current admission rules. The placement itself grants nothing. The ExternalInstallation is context, not a Principal and not an author.

Session admission freezes execution truth

When a Session is admitted through an active placement, Checkfu derives admission from the ExternalInstallation, CollaborationSpace, AgentPlacement, and acting Principal. The Session freezes the selected immutable AgentVersion and the Environment admission snapshot. Later edits to the mutable Agent, Environment, or placement do not rewrite that Session.

mutable Agent + active placement + admitted requester
                    ↓ admission
        Session freezes AgentVersion + Environment snapshot
                    ↓
       Session owns Turn, Run, and event truth

Get started

Agents

Sessions

Environments

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Installations and placement

ExternalInstallation

CollaborationSpace

AgentPlacement

What uses them

ExternalInstallation

CollaborationSpace

AgentPlacement

Identity posture

Session admission freezes execution truth

Next steps

A2A edge

Tenancy and governance

ExternalInstallation

CollaborationSpace

AgentPlacement

​What uses them

​ExternalInstallation

​CollaborationSpace

​AgentPlacement

​Identity posture

​Session admission freezes execution truth

​Next steps

A2A edge

Tenancy and governance

What uses them

ExternalInstallation

CollaborationSpace

AgentPlacement

Identity posture

Session admission freezes execution truth

Next steps