---
name: archal-session
description: Create and control Archal environment sessions. Use when listing or describing environments, creating an isolated session, waiting for readiness, reading provider connection details, renewing, resetting, or destroying a session.
---

# Control an environment session

Create the smallest session that proves the user's integration.

## Before creation

1. Inspect the repository for provider SDKs, base URLs, and test entry points.
2. List and describe candidate environments instead of guessing availability or capability.
3. Let the human choose when multiple environments fit. An empty prior onboarding choice is valid.
4. Choose an explicit sample or validated custom state when the test needs a known baseline.
5. Use an idempotency key for every create request.

## Lifecycle

1. Create the session with only the required environments.
2. Wait until the control plane reports `ready`; cold starts can take about a minute.
3. Use each returned provider base URL and its session-scoped provider credential. Never give the agent under test the Archal control-plane key.
4. Confirm one provider-shaped read before handing the session to a harness.
5. Renew only while useful work is active.
6. Reset to the declared baseline between cases when isolation is required.
7. Destroy the session as soon as work ends, including error and interrupt paths.
8. Wait for teardown acceptance or confirmed destruction according to the caller's cleanup requirement.

Run `archal environment --help` or the installed CLI's `archal session --help` before choosing exact flags.

## Report

Return the session ID, environment IDs, readiness, expiry, connection variable names, sample or state hashes, and cleanup state. Redact every credential.
