> ## 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 environment > Start an environment. Blocks until it is ready (or the provider fails) and returns the environment together with its connection details, so a caller boots in one round trip. The agent in the body gates access and supplies the organisation. ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /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: /environments: post: tags: - Environments summary: Start environment description: >- Start an environment. Blocks until it is ready (or the provider fails) and returns the environment together with its connection details, so a caller boots in one round trip. The agent in the body gates access and supplies the organisation. operationId: EnvironmentsStart requestBody: content: application/json: schema: $ref: '#/components/schemas/Agents.Environment.StartEnvironmentRequest' required: true 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: Agents.Environment.StartEnvironmentRequest: description: >- Request to start an environment. The agent is a binding carried in the body, not a path segment — an environment belongs to an organisation, and the agent tells provisioning which workflow, profile and organisation to boot against. properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The agent to bind the environment to. Gates access, and supplies the organisation the environment is stamped with. agentProfileId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- Optional agent profile to attach. The profile id is stamped onto the env row for the session's lifetime, so later reads resolve against the stamped profile rather than the agent's current one. Its decrypted credentials come back on the response's `connection` only for service-to-service callers — they are never returned to an API key or a browser. 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). required: - agentId type: object 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 Common.uuid: format: uuid type: string 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.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.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 owner's ceiling: 60 minutes for an astro-owned env, which lives only as long as its build conversation, and 1440 for a standalone one, which is parked deliberately. Omit for the owner's default — 60 and 720 respectively. 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.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.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.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.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.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 ````