Tasks

A task is one request to a cloud agent and its result. You describe the work, Railway runs it on an agent, and you read the outcome when it finishes. You don't connect to the agent or keep a session open.

Use tasks to hand off work from a script, an editor, or another system: fix a failing test and open a pull request, investigate an error, or summarize what changed in an environment.

How tasks work

Railway tracks each task from dispatch to result, so a task survives a closed terminal or a dropped connection.

1. You dispatch a task with a prompt and a target environment.
2. Railway creates a cloud agent, or wakes the one you named, and sends it the prompt.
3. The agent works in the background. You can come back for the result, follow progress live, or receive webhooks.
4. The task ends with a result, a failure, or a cancellation.

A task has one of these statuses:

A finished task keeps its result, so you can read it after the agent sleeps or is deleted.

Where a task runs

Every task runs on a cloud agent in the environment you choose. What you pass decides which one.

A fresh session has no memory of earlier tasks on the same agent. To continue earlier work, reply to its task or reuse its conversation key.

A conversation key is a name you choose, such as linear:ENG-123. The first task with a key starts an agent. Later tasks with the same key continue it, each waiting for the one before to finish.

Billing

Starting a new cloud agent creates a virtual machine. The machine is billed while it's active and sleeps after five minutes idle. The model usage of a task is billed as Railway Agent usage.

Because a new agent costs money, the CLI and the MCP server tell you before a task starts one. See the notice behavior for railway ca task and railway agent.

Run a task from the CLI

railway ca task dispatches tasks and reads their results. run hands the task to Railway and returns the task ID. The task runs in the background.

railway ca task run "Fix the failing test in api/ and open a pull request" \
  --repo acme/api

Pick up the result when you're ready:

railway ca task status <task-id>

To follow a task live, add --watch. Use it on run to follow the task you're dispatching, or on status to follow one that is already running.

railway ca task run "Summarize yesterday's errors" --watch
railway ca task status <task-id> --watch

While watching, the CLI prints each tool the agent uses, then the result. A watch ends when the task completes, fails, is cancelled, or stops to ask for an answer.

Press Ctrl-C to stop watching. The task keeps running, and the CLI prints the command to return to it. See Watch a task for the details.

Continue the same work with a follow-up:

railway ca task run "Add a changelog entry for that fix" --reply-to <task-id>

See the railway ca task reference for every command and flag.

Ask questions with the Railway Agent

railway agent is a conversational front end to tasks. Each message is a task, and every thread in an environment shares one cloud agent named railway-agent.

railway agent -p "why is my backend service failing to deploy?"

Run a task from an AI assistant

The Railway MCP server exposes tasks as tools, so an assistant in your editor can hand work to a cloud agent.

Answer the agent

An agent can stop to ask a question or request an approval. The task moves to AWAITING_INPUT until you answer.

Questions are off unless you turn them on. Pass --interactive to railway ca task run, or set interactive: true in the API, to let the agent ask. With interactive: false, the agent decides on its own or gives up with a reason.

A task running in the background stays in AWAITING_INPUT until you come back to it. railway ca task status prints what the agent asked, and a watch ends at that point.

To answer a question, send your answer to the same agent and session. Railway delivers it as the answer instead of starting a new turn.

railway ca task run "Use the staging database" --reply-to <task-id>

To answer an approval, use respond:

railway ca task respond <task-id> allow

Use the API

The public API exposes every task operation, so your own services can dispatch tasks and act on their results. Dispatch a task with cloudAgentTaskDispatch:

mutation {
  cloudAgentTaskDispatch(
    input: {
      projectId: "<project-id>"
      environmentId: "<environment-id>"
      prompt: "Fix the failing test in api/ and open a pull request"
      source: { repo: "acme/api" }
    }
  ) {
    taskId
    cloudAgentId
    sessionId
    status
  }
}

The dispatch returns at once. Read the result with cloudAgentTask, or have Railway call a webhook when the task changes state.

Run cloud agent tasks with the Public API covers each operation with examples, including how to choose the model, pass context and images, get structured output, and receive webhooks.

Limits

Railway applies these limits per user.

A task that starts a new agent also counts against your workspace's cloud agent creation limit.

You can only list, read, answer, and cancel your own tasks, and a task can only run on a cloud agent you own.