> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a local agent

> Attach an operator-owned ACP process while Checkfu keeps durable Session truth.

A connected runtime lets you start an ACP-speaking process on a laptop,
workstation, or VM and attach it to Checkfu. Location is not a new Agent kind:
the Workspace still owns the Agent and Environment, and every turn still belongs
to a durable Session.

Connected runtimes are an alpha capability. Check
[capability status](/getting-started/status) before making the path part of a
customer journey.

<Warning>
  This flow runs from a Checkfu source checkout.
  Part of this flow is behind a rollout fence; a deployment that has not enabled it refuses the request rather than running it.
  Confirm [capability status](/getting-started/status) before making availability part of your application's contract.
</Warning>

## Prerequisites

Use the CLI from a source checkout or an explicitly authorized private-alpha
artifact; there is no self-service public installation channel. See
[CLI access](/getting-started/cli-access).

Configure the Workspace-bound `CHECKFU_API_KEY`, the optional
`CHECKFU_API_URL`, an existing Agent ID, an Environment ID, and the command that
starts your ACP process. The Agent and Environment identify the authority
admitted for the Session. The operator-owned process retains its own model
configuration; Checkfu makes no model-control or provider-usage claim for this
lane.

Before pairing, check the selected Agent's Harness on the console's Harnesses
page. Session creation still resolves that Harness against this deployment's
catalog or a qualified Workspace profile. Pairing does not make a Harness marked
`image_required` or `blocked` launchable; `session create` refuses that Agent
until its Harness is ready. An online connected runtime does not bypass this
admission gate.

## 1. Connect the process

Keep this command running in its own terminal:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu harness connect \
  --agent "$CHECKFU_AGENT_ID" \
  --environment "$CHECKFU_ENVIRONMENT_ID" \
  --name "laptop-agent" \
  -- /path/to/your-acp-agent
```

The CLI enrolls the exact Agent and Environment, prints the ConnectedRuntime ID,
and starts and supervises the ACP process over an outbound connection. No inbound
port, tunnel, or public URL is required.

Copy the printed ID into a second terminal:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
export CHECKFU_CONNECTED_RUNTIME_ID="<printed ConnectedRuntime ID>"
```

## 2. Create a normal Session

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
export CHECKFU_SESSION_ID="$(
  checkfu session create \
    --agent "$CHECKFU_AGENT_ID" \
    --environment "$CHECKFU_ENVIRONMENT_ID"
)"
```

Session admission resolves and freezes one exact AgentVersion and the selected
Environment authority. The ConnectedRuntime does not create a second Agent,
Session, or transcript.

## 3. Drive and stream the turn

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
checkfu session chat "Summarize my inbox." \
  --session "$CHECKFU_SESSION_ID" \
  --connected-runtime "$CHECKFU_CONNECTED_RUNTIME_ID"
```

The authenticated request supplies actor attribution. `session chat` stores the
user message, then follows the same durable Session log used by every execution
lane until the turn reaches a boundary.

Under standard retention, work can remain durably parked while the runtime is
offline and continue when it reconnects. Do not promise that behavior under
ZDR, where retaining execution content may be forbidden.

## Security boundary

A connected runtime is outside Checkfu's managed sandbox. Checkfu does not
claim managed isolation, model control, provider usage, billing, or sandbox
conformance for the operator-owned process. Runtime narration is not
platform-witnessed evidence, and credentials for the local process must never be
copied into Agent configuration or Session events.

Presence is disposable liveness only. An offline or revoked runtime does not
rewrite Session history. Revoke the ConnectedRuntime through the authenticated
ConnectedRuntime API when offboarding it, then verify the absence of later
presence or accepted work.

For Checkfu-managed or customer-operated Cloudflare, see
[Deployment](/concepts/deployment). Connecting this process does not change
who operates Checkfu or choose a different deployment model.

Continue with
[Sessions and Runs](/concepts/sessions-and-runs), and
[security](/concepts/security).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.