> ## 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.

# Environments

> Choose execution capabilities and understand what a Computer keeps between Sessions.

An **Environment** is reusable execution configuration: the packages, network
requirements, and capabilities a Session needs. A **Computer** is an
independently owned, persistent machine identity that can outlive a Session.
Neither is the running process itself.

For example, a reporting Agent might read CSV files, run an analysis, and save a
report. Its Environment describes the execution requirements. An attached
Computer can keep working files for a later Session. Keeping those files does
not promise that the analysis process will still be running.

The [AgentVersion](/concepts/agents) defines the Agent's behavior. The
[Session](/concepts/sessions-and-runs) records the work. The Environment supplies
execution configuration, and a physical allocation supplies compute when needed.
Reusing an Environment does not share Session history or grant access to another
Computer's files.

<Note>
  Plain HTTP against the Checkfu API needs no private package.
  The Checkfu CLI and TypeScript SDK are optional private-alpha artifacts; the HTTP requests work without them.
  The documented path is usable as written for an admitted Workspace.
  Confirm [capability status](/getting-started/status) before making availability part of your application's contract.
</Note>

## Choose capabilities

Start with what the Agent must do, then select a supported execution path.
A Computer may be headless; a browser or graphical desktop is an additional
capability.

| Capability | What to check |
| - | - |
| Files | Which working files the tools can read and write, and which changes are retained. |
| Code | The supported language and execution limits for analysis or transformations. |
| Terminal | The available shell commands, packages, network access, and cancellation behavior. |
| Browser | Supported browser observation and actions, with current authorization. |
| Desktop | A graphical screen and input control, including any supported human viewing or takeover. |

Where the harness runs and where its tools execute are separate choices.
A Worker-native harness can use a Linux tool backend without becoming a
container-hosted harness. Some harnesses need Linux to run themselves; others
can use qualified Worker tools for file, text, or JavaScript work. A Linux tool
backend is needed only when the workload requires its capabilities.

The selected path must support the required combination. A configuration field
or a running Computer does not establish that every tool is available. Check
[capability status](/getting-started/status) for the exact harness and execution
path.

## Create an Environment

Create a named definition, then reuse its `env_…` ID. This request stores
configuration; it does not allocate a machine or attach a Computer.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST https://api.checkfu.com/v1/environments \
    --header "Authorization: Bearer $CHECKFU_API_KEY" \
    --header "Checkfu-Version: 2026-08-31" \
    --header "Idempotency-Key: create-report-work-001" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "report-work"
    }'
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const environment = await checkfu.environments.create({
    name: "report-work",
  })
  ```
</CodeGroup>

The TypeScript example uses the [TypeScript SDK](/reference/typescript-sdk).
Review the returned configuration and the selected path's requirements before
running work. Cloud configuration can specify packages and networking; those
requirements still need a supported execution path and current permission.

An Environment belongs to its owning Workspace. Sharing configuration does not
transfer permission to update or delete it, or share Session data. Development,
staging, and production are separate Workspaces, not Environment values.

## Session admission

A direct Session create selects an AgentVersion and Environment explicitly:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const session = await checkfu.sessions.create({
  agent: { type: "agent", id: agent.id, version: agent.version },
  environment_id: environment.id,
})
```

The Agent needs permission to use the Environment. At admission, Checkfu
resolves the selected AgentVersion, Environment, resources, and Vault references
under current authority, then freezes the Session's Environment configuration.

The Environment remains reusable and publicly unversioned. Updating it affects
later admissions; it does not replace the packages, network policy, or placement
of active work. Current authorization and revocation checks still apply.

## Keep a Computer between Sessions

Attach a Computer when work needs a persistent machine identity. The Workspace
owns the Computer independently of any Session. A Session borrows it; ending the Session
detaches that use and does not grant permission to destroy the Computer.

Creating a Computer stores the resource without starting a machine. Starting,
stopping, sleeping, archiving, and destroying it are separate operations.
Keeping its identity does not keep compute or processes alive. See
[Computers](/concepts/computer-and-screens) for creation, attachment, and lifecycle
APIs.

For the reporting Agent, a later Session may need the saved CSV files and report
without needing the old analysis process. Choose persistence and recovery for
each kind of state:

| State | What persistence establishes |
| - | - |
| Session history | Retained inputs, events, and outcomes can be read under the applicable retention policy. |
| Saved files | Captured files can be restored through a supported path to the expected state. |
| Native continuation | The selected harness can continue from its exact retained native state, where supported. |
| Live process | Process or memory continuity needs its own qualified capability; saved files and native continuation do not establish it. |

Required retained state must restore exactly or the operation must visibly
refuse. Missing, stale, or incompatible state cannot silently become a fresh
machine, empty workspace, or different recovery grade. Retention and erasure
can make state unavailable; a readable Session log does not recreate it.

Viewing and control also require separate capabilities and current authority.
A Checkfu-governed view-only connection cannot send input. Where takeover is
qualified, the server enforces the current controller and revokes the previous
controller's Checkfu-governed access. An agent with direct access to the same
desktop needs a separately enforced isolation or pause boundary; UI takeover
alone does not establish exclusive physical control.

Loading a viewer page does not restore revoked control, and closing it
does not cancel a Run or destroy the Computer. See
[desktop control](/concepts/computer-and-screens#watch-or-take-over-the-desktop).

## Deployment

<span id="self-hosted-environments" />

Choose Checkfu-managed or customer-operated Cloudflare. That choice determines
who operates the installation; it does not choose a harness, grant execution
capabilities, or guarantee recovery. See [Deployment](/concepts/deployment).

[BYOH](/guides/bring-a-custom-harness) selects a harness. BYOK selects model
access. A supported [ConnectedRuntime](/guides/connect-a-local-agent) attaches
an operator-owned process under its own contract. These are separate choices.
An Environment declaration alone does not install or qualify any of them.

## Networking

<span id="limited-networking-and-mcp-servers" />

A `limited` networking configuration accepts `allowed_hosts`,
`allow_package_managers`, and `allow_mcp_servers`:

* `allowed_hosts` names the hosts execution may reach directly.
* `allow_package_managers` adds the public package registries.
* `allow_mcp_servers` adds no direct network hosts. Supported MCP tools go
  through the Agent Gateway under current tool and Connection authority.

A configuration whose only network allowance is `allow_mcp_servers: true` still
requires no direct sandbox network access. Storing that requirement does not
prove enforcement or make an MCP tool available. The selected execution path
must enforce its advertised network boundary; authorized gateway calls are a
separate path.

## Credentials

<span id="environment-connections-and-credentials" />

An Environment can allow network paths, but it does not own external-account
secrets. A Vault owns Checkfu-custodied Credentials. A Connection is the
nonsecret governed link to an external account or provider capability.

Connected actions require current permission, policy, and approval where
applicable. Checkfu checks the Connection and revocation state before trusted
provider I/O. Checkfu-custodied credentials attach at that boundary and stay
outside Agent configuration, model context, Session events, working files, and
untrusted execution. Separately qualified harness-owned authentication has its
own custody limits; it does not grant Checkfu permissions.

See [Connections](/concepts/connections) and
[Permissions](/concepts/tenancy-and-governance) for the resource and authorization
contracts.

## Requirement resolution helper

The work-environment resolver is a read-only planning helper. It evaluates
execution requirements without creating an Environment, admitting a Session,
reserving usage, or authorizing allocation.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const resolution = await checkfu.workEnvironments.resolve({
  input_type: "preset",
  preset: "sandbox_ephemeral",
})

console.log(resolution.resolved_kind) // "session_sandbox"
```

### Composing an attached Computer

A composition input evaluates execution and Computer requirements together.
Affinity specifies whether they must share an execution environment or may be
separate. For example:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const composition = await checkfu.workEnvironments.resolve({
  input_type: "composition",
  execution: { input_type: "preset", preset: "sandbox_ephemeral" },
  computer: {
    requirements: { input_type: "preset", preset: "desktop_isolated" },
    affinity: { type: "remote_permitted" },
  },
  remote: { spend_authorized: true, data_egress_authorized: true },
})

console.log(composition.composition.disposition)
```

When affinity is omitted, the resolver normally requires a shared execution
environment. Computer requirements restricted to `connected` placement, such as
the `connected_computer` recipe, instead normalize to `remote_permitted`.
The resolver cannot replace a required shared environment with a detached
Computer, or replace an explicitly selected Computer with a fresh allocation.
A detached placement without the required spend and data-egress authorization
is refused. These planning inputs do not themselves grant that authority.

A successful resolution explains an intended placement. Session admission and
execution still check current authorization, usage, retention, locality, and
capability support. The resolver never provisions the proposed resources.


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