> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Start cloud task

> Start a remote coding task in Codex cloud.

`startCodexCloudTask` submits a coding task directly to a configured Codex cloud environment. Automate.ax dispatches the request; the Codex agent runs in OpenAI's cloud container.

```ts automations/start-codex-task.automation.ts theme={null}
import { automation, t } from "automate.ax"
import { startCodexCloudTask } from "automate.ax/codex"
import { onLinearIssueCreated } from "automate.ax/linear"

export default automation("Implement Linear issues", () => {
  const issue = onLinearIssueCreated()
  const task = startCodexCloudTask({
    branch: "main",
    environmentId: "env_abc123",
    mode: "code",
    prompt: t`Implement ${issue.identifier} and open a pull request.`,
  })

  task.id
  task.url
})
```

Connect a Codex access token from a ChatGPT Business or Enterprise workspace. Create the token in your workspace's access-token settings, and configure the target repository and setup scripts as a Codex cloud environment before running the action.

`environmentId` is the stable environment identifier returned by `listCodexCloudEnvironments`. `branch` is required so the headless dispatcher never guesses a ref from its own checkout. Set `attempts` from `1` to `4`; it defaults to `1`. `mode` defaults to `code`; use `ask` when you only want an answer and no repository changes. Optional second argument `{ account }` defaults to the project binding.

The result contains the new task ID and its ChatGPT URL. Submission is asynchronous. Use `runCodexCloudTask` when downstream work should wait for completion, `waitForCodexCloudTask` when you already have a task ID or signal, or `getCodexCloudTask` for one immediate status check.

<Warning>
  Codex Cloud does not currently provide an official public REST API. This
  action calls undocumented ChatGPT backend endpoints that may change without
  notice.
</Warning>