> ## 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 organisation in the body is the scope; the agent, when given, is a binding the server verifies belongs to it. ## 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: Schedules - name: Execution - name: Files - name: Profiles - name: Profile Groups - name: Agent Profiles - name: Agent Profile Pools - name: Workflows - name: Execution Batches - name: Scheduled Executions - name: Schema - name: Documentation - name: Context - name: Admin Customer Activity - name: Reference - name: Workflow Tags - name: Secrets - name: Vault - name: Insights - name: Workflow Versions 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 organisation in the body is the scope; the agent, when given, is a binding the server verifies belongs to it. 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. '429': content: application/json: schema: $ref: '#/components/schemas/Common.TooManyRequestsErrorBody' description: Client error '500': content: application/json: schema: $ref: '#/components/schemas/Common.InternalServerErrorBody' description: Server error components: schemas: Agents.Environment.StartEnvironmentRequest: description: >- Request to start an environment. An environment belongs to an organisation; the agent is an optional binding carried in the body, not a path segment. With an agent, the environment is stamped external-owned and the agent's workflow/profile drive provisioning; without one, it is organization-owned and provisions from the explicit spec alone. properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: 'Deprecated: use workflowId. The agent to bind the environment to.' x-hidden: true agentProfileId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: 'Deprecated: use profileId. Optional agent profile to attach.' x-hidden: true organizationId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The organisation the environment belongs to. With an agent, the server verifies the agent belongs to it, so a mismatched binding fails instead of stamping the wrong organisation. Defaults to the one organization the caller acts in, such as an API key's. Required when the caller belongs to several. profileId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- Optional login 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 workflow'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. Do not set together with agentProfileId. 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). The workflow arm needs a workflow to resolve against, so it requires `workflowId`. workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The workflow to bind the environment to. Gates access to that workflow. Omit for an organization-owned environment with no workflow binding. Do not set together with 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' deprecated: true description: >- Deprecated: use profileId. Profile snapshot the environment was booted against, if any. x-hidden: true 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. profileId: allOf: - $ref: '#/components/schemas/Common.uuid' description: Profile snapshot the environment was booted against, if any. 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 detail: description: Explanation of this occurrence. Same text as message type: string errors: description: The parameters that failed validation, when known items: $ref: '#/components/schemas/Common.FieldError' type: array instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.UnauthorizedErrorBody: properties: code: enum: - 401 type: number x-enum-varnames: - Unauthorized detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.ForbiddenErrorBody: properties: code: enum: - 403 type: number x-enum-varnames: - Forbidden detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.NotFoundErrorBody: properties: code: enum: - 404 type: number x-enum-varnames: - NotFound detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.TooManyRequestsErrorBody: properties: code: enum: - 429 type: number x-enum-varnames: - TooManyRequests detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all 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: '#/components/schemas/Agents.Environment.ExplicitEnvironmentSource' workflow: '#/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 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 joins as a member rather than as another optional column. discriminator: mapping: astro: '#/components/schemas/Agents.Environment.AstroEnvironmentOwner' execution: '#/components/schemas/Agents.Environment.ExecutionEnvironmentOwner' external: '#/components/schemas/Agents.Environment.ExternalEnvironmentOwner' organization: '#/components/schemas/Agents.Environment.OrganizationEnvironmentOwner' warm_pool: '#/components/schemas/Agents.Environment.WarmPoolEnvironmentOwner' propertyName: type oneOf: - $ref: '#/components/schemas/Agents.Environment.ExecutionEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.AstroEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.ExternalEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.OrganizationEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.WarmPoolEnvironmentOwner' 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 Common.FieldError: description: A problem with one request parameter properties: detail: description: What is wrong with it type: string parameter: description: The query or path parameter name type: string required: - parameter - detail type: object 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.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' deprecated: true description: 'Deprecated: use workflowId. The agent the conversation is building.' x-hidden: true chatId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The astro chat that booted the environment. type: enum: - astro type: string workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The workflow the conversation is building. required: - type - agentId - workflowId - 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' deprecated: true description: >- Deprecated: use workflowId. The agent the execution runs on behalf of. x-hidden: true executionId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The execution that booted the environment. type: enum: - execution type: string workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The workflow the execution runs. required: - type - agentId - workflowId - 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' deprecated: true description: 'Deprecated: use workflowId. The agent the environment is bound to.' x-hidden: true 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 workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The workflow the environment is bound to. required: - type - agentId - workflowId type: object Agents.Environment.OrganizationEnvironmentOwner: description: >- An environment owned by the organisation itself: it has no agent binding at all — the organisation on the environment is its whole identity. properties: type: enum: - organization type: string required: - type type: object Agents.Environment.WarmPoolEnvironmentOwner: description: >- A warm pool owns the environment for its whole life; executions borrow it without ever taking ownership. properties: type: enum: - warm_pool type: string warmPoolId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The warm pool the environment belongs to. required: - type - warmPoolId 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: description: >- Browser provider name as stored on the environment. `anchor` for every environment this build can boot; an environment created by a provider that has since been removed reports that provider's name. type: string 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: '#/components/schemas/Agents.Environment.SpecBrowserTemplate' os: '#/components/schemas/Agents.Environment.SpecOsTemplate' propertyName: type oneOf: - $ref: '#/components/schemas/Agents.Environment.SpecBrowserTemplate' - $ref: '#/components/schemas/Agents.Environment.SpecOsTemplate' type: object Agents.Execution.BrowserProviderConfig: description: Browser provider configuration (discriminated by type) discriminator: mapping: anchor: '#/components/schemas/Agents.Execution.AnchorProviderConfig' propertyName: type oneOf: - $ref: '#/components/schemas/Agents.Execution.AnchorProviderConfig' 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). region: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsRegion' description: >- Daytona region for an unregistered snapshot. Omit for us, or us-west-4 on windows. A registered snapshot boots in its own region and ignores this. snapshotName: description: >- Snapshot from the registry: a bare `name` follows its newest version, `name:version` pins one. Omit or empty for the configured default for the selected osType. An unregistered name boots as the Daytona snapshot of that name. A name registered to another organisation is refused. 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.Workflow.BrowserProvider: description: Browser provider type enum: - anchor type: string Agents.Workflow.OsRegion: description: Daytona region the sandbox boots in. Omit for us. enum: - us - us-west-4 type: string securitySchemes: ApiKeyAuth: in: header name: X-Api-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.