Docs › Agent
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.
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.
Setting a repository up
- Run AstraCode: Enable remote agents for this repository from the command palette. It writes
.github/workflows/astracode-agent.ymland shows it as a diff. Review it and commit it to the default branch yourself: AstraCode never commits or pushes it. - Create an API key with the Run agents scope on the API keys page, and add it to the repository as the Actions secret
ASTRACODE_TOKEN(Settings, Secrets and variables, Actions). AstraCode never sees the secret. - In the repository's Settings, Actions, General, allow GitHub Actions to create pull requests, so the run can open one.
Starting one
Ask for it ("do this in a remote agent"), or give an agent definition isolation: remote. The agent tool takes isolation: "remote" as well. 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 mode: 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, MCP servers 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 in autonomous mode. 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.
What it costs
Model use is billed to the ASTRACODE_TOKEN key like any other request. The Actions minutes are your repository's own. Progress events (step numbers, tool names, the report, the pull request link) are kept by the gateway for seven days and can be read only by you and the key that wrote them.
All documentation
Get started
Agent
- Agent overview
- Approvals and permissions
- Plan mode
- What the agent can do
- Running commands
- Browser tools
- Checkpoints and undo
- Infrastructure as code
- Running several agents at once
- Remote agents in GitHub Actions