> ## 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. # Start live environment (external) > Start a standalone live environment for the agent. Returns the (proxied) CDP URL or Daytona connection details once the env is ready; optionally returns decrypted credentials when agentProfileId is supplied. The env is stamped with an `external` owner and reaped on its session TTL. ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /agents/{agentId}/environments 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: /agents/{agentId}/environments: post: tags: - Environments summary: Start live environment (external) description: >- Start a standalone live environment for the agent. Returns the (proxied) CDP URL or Daytona connection details once the env is ready; optionally returns decrypted credentials when agentProfileId is supplied. The env is stamped with an `external` owner and reaped on its session TTL. operationId: AgentEnvironmentsStart parameters: - description: The agent the environment belongs to. in: path name: agentId required: true schema: $ref: '#/components/schemas/Common.uuid' requestBody: content: application/json: schema: $ref: >- #/components/schemas/Agents.Environment.ExternalStartEnvironmentRequest required: true responses: '200': content: application/json: schema: $ref: >- #/components/schemas/Agents.Environment.StartEnvironmentResponse 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.ExternalStartEnvironmentRequest: description: >- Request to start a standalone live environment via the external (agents-API-key) API. Unlike the internal StartEnvironmentRequest there is no owner field — the env is stamped with an `external` owner for the path agent, and takes the agent's own organisation (not the caller's). Provisioning reads no workflow unless a workflow source is passed. properties: agentProfileId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- Optional agent profile to attach. When supplied, the profile's decrypted credentials are returned as the ##NAME## placeholder map and the profile id is stamped onto the env row for the session's lifetime. source: allOf: - $ref: '#/components/schemas/Agents.Environment.EnvironmentSource' description: >- Where the environment spec comes from. Omit for the server default (a browser env at the computer-use resolution). type: object Agents.Environment.StartEnvironmentResponse: description: >- Response from starting a live environment. Shape mirrors the legacy `POST /agents/{id}/workflows/{wid}/live-environment` response so callers can share rendering code; `environmentId` is the new wire handle astro stores for `stop` / `attach`. properties: cdpUrl: description: >- Chrome DevTools Protocol websocket URL. Present only for browser environments. type: string credentials: description: >- Decrypted credential placeholders for the attached agent profile, keyed by ##NAME## placeholder. Present only when agentProfileId was supplied and the profile has credentials. type: object unevaluatedProperties: type: string cua: allOf: - $ref: >- #/components/schemas/Agents.Workflow.LiveEnvironmentCuaConnection description: >- Provider-specific CUA connection details. Present for Anchor browsers and Daytona OS environments. environmentId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The newly-provisioned environment. environmentType: allOf: - $ref: '#/components/schemas/Agents.Workflow.EnvironmentType' description: The environment type the workflow is configured for. required: - environmentId - environmentType 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.EnvironmentSource: description: >- Where the environment spec comes from: copied from a workflow, or supplied inline. discriminator: mapping: spec: $ref: '#/components/schemas/Agents.Environment.ExplicitEnvironmentSource' workflow: $ref: '#/components/schemas/Agents.Environment.WorkflowEnvironmentSource' propertyName: kind oneOf: - $ref: '#/components/schemas/Agents.Environment.WorkflowEnvironmentSource' - $ref: '#/components/schemas/Agents.Environment.ExplicitEnvironmentSource' type: object 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.Workflow.EnvironmentType: description: Type of execution environment enum: - browser - os type: string Agents.Environment.ExplicitEnvironmentSource: description: >- Environment spec supplied inline — provisioning does not read any workflow. This is how a live env is started without touching (or even having) a workflow definition. properties: kind: enum: - spec type: string sessionTimeoutMins: description: >- Session lifetime in minutes before the reaper tears the env down. Clamped server-side to the astro session cap. Omit for the default. format: int32 type: integer template: allOf: - $ref: '#/components/schemas/Agents.Environment.SpecEnvironmentTemplate' description: >- Environment template. Omit entirely for the server default (browser). viewportHeight: description: >- Viewport height in pixels. Omit for the default (800, the computer-use resolution). Ignored for OS environments — they always run at the fixed computer-use resolution. format: int32 type: integer viewportWidth: description: >- Viewport width in pixels. Omit for the default (1280, the computer-use resolution). Ignored for OS environments — they always run at the fixed computer-use resolution. format: int32 type: integer required: - kind type: object Agents.Environment.WorkflowEnvironmentSource: description: >- Environment spec derived from a workflow. The workflow's environment_template + settings (viewport, timeout) drive provisioning. properties: kind: enum: - workflow type: string workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The workflow whose environment_template + settings drive provisioning. Omit to use the agent's editable head — the server resolves the head anyway, so passing an explicit id only matters for agents without one. required: - kind type: object Agents.Workflow.OsType: description: Operating system the environment sandbox runs enum: - linux - windows type: string Agents.Workflow.LiveEnvironmentCuaProvider: description: CUA provider identifier. enum: - anchor - daytona type: string Agents.Environment.SpecEnvironmentTemplate: description: >- Environment template for the explicit spec arm — a looser sibling of the workflow's own EnvironmentTemplate where every field has a server default, so callers can say as little as `{type: "os"}`. discriminator: mapping: browser: $ref: '#/components/schemas/Agents.Environment.SpecBrowserTemplate' os: $ref: '#/components/schemas/Agents.Environment.SpecOsTemplate' propertyName: type oneOf: - $ref: '#/components/schemas/Agents.Environment.SpecBrowserTemplate' - $ref: '#/components/schemas/Agents.Environment.SpecOsTemplate' type: object Agents.Environment.SpecBrowserTemplate: description: >- Browser template for the explicit spec arm. Every field is optional with a server default. properties: provider: allOf: - $ref: '#/components/schemas/Agents.Workflow.BrowserProvider' description: Browser provider. Omit for the server's configured default provider. type: enum: - browser type: string required: - type type: object Agents.Environment.SpecOsTemplate: description: >- OS template for the explicit spec arm. Every field is optional with a server default. properties: osType: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsType' description: Operating system the sandbox runs. Omit for linux. provider: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsProvider' description: OS provider. Omit for the default (daytona). public: description: Whether the sandbox is publicly reachable. Omit for false. type: boolean snapshotName: description: >- Snapshot to boot. Omit for the configured default snapshot for the chosen osType. type: string type: enum: - os type: string required: - type type: object Agents.Workflow.BrowserProvider: description: Browser provider type enum: - anchor - steel type: string Agents.Workflow.OsProvider: description: OS provider type enum: - daytona - local type: string securitySchemes: ApiKeyAuth: in: header name: X-Asteroid-Agents-Api-Key type: apiKey ````