Environments

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 defines the Agent’s behavior. The Session 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.

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 before making availability part of your application’s contract.

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

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"
  }'

const environment = await checkfu.environments.create({
  name: "report-work",
})

The TypeScript example uses the 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:

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

Deployment

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. BYOH selects a harness. BYOK selects model access. A supported ConnectedRuntime 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

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

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 and Permissions 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.

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:

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.

Get started

Agents

Sessions

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Environments

Choose capabilities

Create an Environment

Session admission

Keep a Computer between Sessions

Deployment

Networking

Credentials

Requirement resolution helper

Composing an attached Computer

​Choose capabilities

​Create an Environment

​Session admission

​Keep a Computer between Sessions

​Deployment

​Networking

​Credentials

​Requirement resolution helper

​Composing an attached Computer

Choose capabilities

Create an Environment

Session admission

Keep a Computer between Sessions

Deployment

Networking

Credentials

Requirement resolution helper

Composing an attached Computer