Docs › Agent › Remote agents in GitHub Actions

Remote agents in GitHub Actions

Run an agent in your repository's GitHub Actions instead of on your machine, and get its work back as a pull request.

On this page

An agent can run off your machine: in your repository's GitHub Actions, on a branch of its own, coming back as a pull request. Its card in the chat follows it step by step, as a local agent's does, and the agent that started it is told when it finishes, with the report and the link.

Set a repository up

  1. Run AstraCode: Enable remote agents for this repository from the command palette. It writes .github/workflows/astracode-agent.yml and shows it as a diff.
  2. Review it and commit it to the default branch yourself: AstraCode never commits or pushes it.
  3. In the repository's settings on GitHub, under Actions, General, allow GitHub Actions to create pull requests, so the run can open one.

No secret is needed. Each run signs in with the identity token GitHub gives the job (the workflow asks for id-token: write), and AstraCode accepts it only for a run you started for that repository, and only until the run ends. A repository that already has an ASTRACODE_TOKEN Actions secret (an API key with the Run agents scope) keeps using it.

Start one

Ask for it ("do this in a remote agent"), or give an agent definition isolation: remote. Before anything starts, a dialog shows the repository, the branch it starts from, the new branch astracode/<run id> and the prompt, every time and in every approval setting, because it starts a job on your repository. The first time, the editor asks you to sign in to GitHub with the repo and workflow scopes.

The agent starts from your current branch if GitHub has it, otherwise from the default branch, and the dialog says which. Commits you have not pushed and uncommitted changes are not sent. A definition's timeoutMinutes (1 to 360, default 60) stops a run that goes on too long. Custom agents are sent with their prompt, tools and model; hooks, connectors and memory belong to your machine and are not.

While it runs

The card shows its steps and the tool it used last, refreshed every ten seconds, and it is listed in the Tasks panel as rm1, rm2 and so on. Stop cancels the workflow run. When it ends, Open PR opens the pull request, Check out branch fetches its branch and switches to it, and View run opens the run on GitHub. The report is also in the run's job summary.

What it can do there

The workflow runs the AstraCode CLI at a pinned version with --permissions auto: it edits and runs commands, and is refused what the editor confirms even with Never ask. The checkout keeps no GitHub token, so the agent cannot push; the workflow's own last step commits its changes to astracode/<run id>, pushes that branch alone and opens the pull request (a draft when the agent did not finish). Third-party actions are pinned to commit SHAs, and every input is checked before anything runs.

Usage

The run uses the allowance of whoever started it, like their own runs in the editor; with an ASTRACODE_TOKEN secret, that key's. The Actions minutes are your repository's own. Progress events (step numbers, tool names, the report, the pull request link) are kept by AstraCode for seven days and can be read only by you and the key that wrote them. Plans are on the pricing page.

If something goes wrong

← Subagents and background tasks Infrastructure as code →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference