> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get environment > Read an environment, including the provider state the live view renders from. Terminal environments are returned too, so the caller can play the recording. ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /environments/{environmentId} openapi: 3.1.0 info: title: Agent Service version: v1 servers: - description: V2 API url: https://odyssey.asteroid.ai/agents/v2 security: - ApiKeyAuth: [] tags: - name: Agents - name: Environments - name: Execution - name: Files - name: Agent Profiles - name: Agent Profile Pools - name: Workflows - name: Schema - name: Documentation - name: Context - name: Admin Customer Activity paths: /environments/{environmentId}: get: tags: - Environments summary: Get environment description: >- Read an environment, including the provider state the live view renders from. Terminal environments are returned too, so the caller can play the recording. operationId: EnvironmentByIdGet parameters: - description: The environment to read. in: path name: environmentId required: true schema: $ref: '#/components/schemas/Common.uuid' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Agents.Environment.Environment' description: The request has succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/Common.BadRequestErrorBody' description: The server could not understand the request due to invalid syntax. '401': content: application/json: schema: $ref: '#/components/schemas/Common.UnauthorizedErrorBody' description: Access is unauthorized. '403': content: application/json: schema: $ref: '#/components/schemas/Common.ForbiddenErrorBody' description: Access is forbidden. '404': content: application/json: schema: $ref: '#/components/schemas/Common.NotFoundErrorBody' description: The server cannot find the requested resource. '500': content: application/json: schema: $ref: '#/components/schemas/Common.InternalServerErrorBody' description: Server error components: schemas: Common.uuid: format: uuid type: string Agents.Environment.Environment: description: >- A single environment: what it is, its provider state, and how to drive it. `state` is the same shape the execution endpoint returns, so the LiveView/OsLiveView components render either without branching. properties: agentProfileId: allOf: - $ref: '#/components/schemas/Common.uuid' description: Profile snapshot the environment was booted against, if any. connection: allOf: - $ref: '#/components/schemas/Agents.Environment.EnvironmentConnection' description: How to connect to it. createdAt: description: When the environment row was created. format: date-time type: string environmentType: allOf: - $ref: '#/components/schemas/Agents.Workflow.EnvironmentType' description: Browser or OS. expiresAt: description: >- When the reaper will tear the environment down if no graceful Stop arrives first. format: date-time type: string hasRecording: description: >- Whether a playable recording has been persisted (GCS object or provider URL). The playable URL itself is minted on the by-id read. type: boolean id: allOf: - $ref: '#/components/schemas/Common.uuid' description: Environment identifier. organizationId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The organisation the environment belongs to. osType: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsType' description: >- Operating system for OS environments. Absent for browser environments; linux when an OS environment predates explicit osType storage. owner: allOf: - $ref: '#/components/schemas/Agents.Environment.EnvironmentOwner' description: Who the environment belongs to, and the identity that owner carries. readyAt: description: When the environment first became ready, if it reached that state. format: date-time type: string state: allOf: - $ref: '#/components/schemas/Agents.Execution.EnvironmentState' description: >- Environment state (browser or OS): live-view URL, viewport, provider config and a freshly-minted recording URL when one exists. status: allOf: - $ref: '#/components/schemas/Agents.Environment.EnvironmentStatus' description: >- Current status, terminal states included. Lists exclude terminal environments unless `includeTerminal` is set. stoppedAt: description: When the environment reached a terminal state. Set after Stop runs. format: date-time type: string required: - id - organizationId - owner - environmentType - status - hasRecording - createdAt - expiresAt - state - connection type: object Common.BadRequestErrorBody: properties: code: enum: - 400 type: number x-enum-varnames: - BadRequest message: type: string required: - code - message type: object Common.UnauthorizedErrorBody: properties: code: enum: - 401 type: number x-enum-varnames: - Unauthorized message: type: string required: - code - message type: object Common.ForbiddenErrorBody: properties: code: enum: - 403 type: number x-enum-varnames: - Forbidden message: type: string required: - code - message type: object Common.NotFoundErrorBody: properties: code: enum: - 404 type: number x-enum-varnames: - NotFound message: type: string required: - code - message type: object Common.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError message: type: string required: - code - message type: object Agents.Environment.EnvironmentConnection: description: >- How to drive a running environment. All fields are optional — an env that is still bootstrapping has no CDP URL yet, and a caller can proceed without browser tools. properties: cdpUrl: description: >- Chrome DevTools Protocol websocket URL. Present only for browser environments with a ready CDP endpoint. Proxied on the browser and API-key surfaces; the raw provider URL is only ever handed to service-to-service callers. type: string cua: allOf: - $ref: >- #/components/schemas/Agents.Workflow.LiveEnvironmentCuaConnection description: >- Provider-specific CUA connection details. Present for Anchor browsers and Daytona OS environments. Carries session handles, not credentials — the caller resolves provider API keys from its own config. type: object Agents.Workflow.EnvironmentType: description: Type of execution environment enum: - browser - os type: string Agents.Workflow.OsType: description: Operating system the environment sandbox runs enum: - linux - windows type: string Agents.Environment.EnvironmentOwner: description: >- Who the environment belongs to. Discriminated on `type`, mirroring the storage-side agent_environment.owner_type, so each owner kind carries exactly the identity it has — an execution id only exists for execution-owned envs, a chat id only for astro-owned ones. A future owner kind (warm pools, org sessions) joins as a member rather than as another optional column. discriminator: mapping: astro: $ref: '#/components/schemas/Agents.Environment.AstroEnvironmentOwner' execution: $ref: '#/components/schemas/Agents.Environment.ExecutionEnvironmentOwner' external: $ref: '#/components/schemas/Agents.Environment.ExternalEnvironmentOwner' propertyName: type oneOf: - $ref: '#/components/schemas/Agents.Environment.ExecutionEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.AstroEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.ExternalEnvironmentOwner' type: object Agents.Execution.EnvironmentState: anyOf: - $ref: '#/components/schemas/Agents.Execution.BrowserState' - $ref: '#/components/schemas/Agents.Execution.OsState' description: >- Discriminated union of environment states (discriminated by environmentType) Agents.Environment.EnvironmentStatus: description: Every state an environment can be in, terminal included. enum: - requested - provisioning - ready - stopping - stopped - failed - dead type: string Agents.Workflow.LiveEnvironmentCuaConnection: description: >- CUA provider connection metadata returned alongside a live environment. Credentials are NOT included — the caller resolves API keys from its own local config keyed by provider. properties: anchorBaseUrl: description: >- Base URL for the Anchor control plane. Optional; defaults to the Anchor SDK default. Set only when provider is anchor. type: string daytonaOsType: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsType' description: >- Operating system of the Daytona sandbox. Set only when provider is daytona. daytonaToolboxBaseUrl: description: >- Per-sandbox base URL for the Daytona toolbox HTTP API. Set only when provider is daytona. type: string provider: allOf: - $ref: '#/components/schemas/Agents.Workflow.LiveEnvironmentCuaProvider' description: The CUA provider backing this session. sessionId: description: >- Provider session ID. Anchor: browser session id. Daytona: sandbox id. type: string required: - provider - sessionId type: object Agents.Environment.AstroEnvironmentOwner: description: >- An astro build conversation owns the environment: it lives as long as the chat driving it. properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The agent the conversation is building. chatId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The astro chat that booted the environment. type: enum: - astro type: string required: - type - agentId - chatId type: object Agents.Environment.ExecutionEnvironmentOwner: description: >- An execution owns the environment: it was booted to run that execution and dies with it. properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The agent the execution runs on behalf of. executionId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The execution that booted the environment. type: enum: - execution type: string required: - type - agentId - executionId type: object Agents.Environment.ExternalEnvironmentOwner: description: >- A standalone environment: it belongs to the organisation rather than to a chat or an execution, and outlives both. Booted by an API key today; the agent binding arrives with the workflow it was started from. properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The agent the environment is bound to. createdByApiKeyId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The API key that booted it, when one did. Absent for environments booted by a signed-in user. type: enum: - external type: string required: - type - agentId type: object Agents.Execution.BrowserState: description: Browser environment state properties: browserIp: description: Browser's public IP address (detected at startup) type: string environmentType: description: Environment type discriminator enum: - browser type: string hasRecording: description: >- Whether a recording exists (provider URL or durable GCS object persisted). Use this to gate the player rather than recordingUrl, which is empty for GCS-only recordings. type: boolean height: description: Browser viewport height type: integer liveViewUrl: description: Live view/debugger URL type: string provider: allOf: - $ref: '#/components/schemas/Agents.Workflow.BrowserProvider' description: Browser provider name providerConfig: allOf: - $ref: '#/components/schemas/Agents.Execution.BrowserProviderConfig' description: Provider-specific configuration recordingStartedAt: description: When the environment recording started (video time-zero anchor) format: date-time type: string recordingUrl: description: Recording URL (available after execution completes) type: string width: description: Browser viewport width type: integer required: - environmentType - provider - width - height - hasRecording type: object Agents.Execution.OsState: description: OS environment state properties: egressIp: description: Environment's public egress IP address (detected at startup) type: string environmentType: description: Environment type discriminator enum: - os type: string hasRecording: description: >- Whether a recording exists (provider URL or durable GCS object persisted). Use this to gate the player rather than recordingUrl, which is empty for GCS-only recordings. type: boolean height: description: Screen height type: integer liveViewUrl: description: Live view URL type: string provider: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsProvider' description: OS provider name providerConfig: allOf: - $ref: '#/components/schemas/Agents.Execution.DaytonaProviderConfig' description: Provider-specific configuration recordingStartedAt: description: When the environment recording started (video time-zero anchor) format: date-time type: string recordingUrl: description: Recording URL type: string width: description: Screen width type: integer required: - environmentType - provider - width - height - hasRecording type: object Agents.Workflow.LiveEnvironmentCuaProvider: description: CUA provider identifier. enum: - anchor - daytona type: string Agents.Workflow.BrowserProvider: description: Browser provider type enum: - anchor - steel type: string Agents.Execution.BrowserProviderConfig: description: Browser provider configuration (discriminated by type) discriminator: mapping: anchor: $ref: '#/components/schemas/Agents.Execution.AnchorProviderConfig' steel: $ref: '#/components/schemas/Agents.Execution.SteelProviderConfig' propertyName: type oneOf: - $ref: '#/components/schemas/Agents.Execution.AnchorProviderConfig' - $ref: '#/components/schemas/Agents.Execution.SteelProviderConfig' type: object Agents.Workflow.OsProvider: description: OS provider type enum: - daytona - local type: string Agents.Execution.DaytonaProviderConfig: description: Daytona OS provider configuration properties: sandboxId: description: Daytona sandbox ID type: string sandboxUrl: description: Sandbox URL type: string type: object Agents.Execution.AnchorProviderConfig: description: Anchor browser provider configuration properties: sessionId: allOf: - $ref: '#/components/schemas/Common.uuid' description: Anchor session ID sessionUrl: description: Anchor session URL type: string type: description: Provider type discriminator enum: - anchor type: string required: - type type: object Agents.Execution.SteelProviderConfig: description: Steel browser provider configuration properties: sessionId: description: Steel session ID type: string type: description: Provider type discriminator enum: - steel type: string required: - type type: object securitySchemes: ApiKeyAuth: in: header name: X-Asteroid-Agents-Api-Key type: apiKey ````