docs: add guide for running agents locally with released binaries#665
docs: add guide for running agents locally with released binaries#665waynesun09 wants to merge 2 commits into
Conversation
New user guide covering the full workflow without a Go toolchain: download CLI from GitHub Releases, configure env, run agents on macOS (Podman Desktop) and Linux (Podman). Signed-off-by: Wayne Sun <gsun@redhat.com>
Explain how to run agent inference without post-script side effects (PR comments, branch pushes). Notes that PUSH_TOKEN/REVIEW_TOKEN are not needed when using this flag. Signed-off-by: Wayne Sun <gsun@redhat.com>
Review: #665Head SHA: 6783f21 SummaryClean documentation-only PR adding a user guide for running fullsend agents locally with released binaries (no Go toolchain required). The new guide at FindingsMedium
FooterOutcome: approve |
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/u/271249281?s=60&v=4){kind=small}
ralphbean
left a comment
ralphbean
left a comment
There was a problem hiding this comment.
Thanks for writing this guide — local agent execution is a key gap and this addresses it well. Two items need changes before merging, plus a couple of notes for follow-up.
Also note: this PR should merge after #662 lands, since it documents behavior (cross-platform binary resolution, FULLSEND_SANDBOX_ARCH) that only exists on that branch. Consider linking issue #457 in the PR description — it directly describes this use case.
|
|
||
| ## Platform notes | ||
|
|
||
| ### macOS |
There was a problem hiding this comment.
[important] The prerequisites say Podman is required with OpenShell 0.0.37-dev+, but this section casually references Docker as if it works ("if using Docker instead of Podman..."). This sends mixed signals — a user with only Docker would think it's supported based on this note, but the prerequisites say otherwise.
Please either:
- Remove the Docker reference and state explicitly that Podman is the only supported runtime, or
- If Docker genuinely works, list it as an alternative in the prerequisites table.
Also, the guide never explains why OpenShell 0.0.37-dev+ is required (it's the version that adds Podman support). A sentence explaining this would help users understand whether they can use an older version with Docker.
|
|
||
| > For building fullsend from source or contributing to the CLI, see [Local development](../dev/local-dev.md). | ||
|
|
||
| ## Prerequisites |
There was a problem hiding this comment.
[moderate] OpenShell is listed as a prerequisite but the guide never explains what it is, where to get it, or how to install it. The troubleshooting section mentions openshell version but a new user encountering OpenShell for the first time would be stuck. Please add a brief install step or link to OpenShell's installation docs.
|
|
||
| ```bash | ||
| gh repo clone <org>/.fullsend /tmp/fullsend-dot | ||
| ``` |
There was a problem hiding this comment.
[moderate — deferred] Nit: /tmp/fullsend.env is world-readable on most systems, which means tokens and credential paths are accessible to any local user. Consider suggesting ~/.config/fullsend/env as the example path and adding a chmod 600 note. Not blocking, but worth addressing in a follow-up.
| @@ -0,0 +1,197 @@ | |||
| # Running agents locally | |||
There was a problem hiding this comment.
[minor — deferred] This guide documents FULLSEND_SANDBOX_ARCH and cross-platform binary resolution behavior that only exists in PR #662's branch. This creates a merge ordering dependency — please merge after #662 lands. Also consider linking issue #457 ("Support local execution of individual agents for pre-adoption evaluation") in the PR description since it directly describes this use case.
|
|
||
| ```bash | ||
| tar xzf fullsend_0.4.0_darwin_arm64.tar.gz | ||
| sudo mv fullsend_0.4.0_darwin_arm64/fullsend /usr/local/bin/ |
There was a problem hiding this comment.
Move it to $HOME/.local/bin instead.
| --no-post-script | ||
| ``` | ||
|
|
||
| The agent runs normally inside the sandbox, but the post-script is skipped. This means `PUSH_TOKEN` and `REVIEW_TOKEN` are not needed in your env file — only the core variables (`GH_TOKEN`, GCP credentials) are required. |
| ### Example: triage an issue | ||
|
|
||
| ```bash | ||
| fullsend run triage \ | ||
| --fullsend-dir /tmp/fullsend-dot \ | ||
| --target-repo /path/to/repo \ | ||
| --env-file /tmp/fullsend.env | ||
| ``` | ||
|
|
||
| ### Example: review a pull request | ||
|
|
||
| ```bash | ||
| fullsend run review \ | ||
| --fullsend-dir /tmp/fullsend-dot \ | ||
| --target-repo /path/to/repo \ | ||
| --env-file /tmp/fullsend.env | ||
| ``` | ||
|
|
||
| ### Example: implement an issue | ||
|
|
||
| ```bash | ||
| fullsend run code \ | ||
| --fullsend-dir /tmp/fullsend-dot \ | ||
| --target-repo /path/to/repo \ | ||
| --env-file /tmp/fullsend.env | ||
| ``` | ||
|
|
||
| ### Example: fix review feedback on a PR | ||
|
|
||
| ```bash | ||
| fullsend run fix \ | ||
| --fullsend-dir /tmp/fullsend-dot \ | ||
| --target-repo /path/to/repo \ | ||
| --env-file /tmp/fullsend.env | ||
| ``` |
There was a problem hiding this comment.
I feel these examples are not useful, the only thing that changes is the command. If we want to provide better examples I would provide them with the env variables, which is the tricky part.
|
Need details on
|
ralphbean
left a comment
ralphbean
left a comment
There was a problem hiding this comment.
Review Summary
This is a well-structured documentation PR that addresses issue #457. The guide is comprehensive and follows good documentation practices.
Strategic assessment: ✅ Good direction. The change fits the project scope and directly addresses a documented user need.
Existing discussion: The PR already has thorough review comments from @ralphbean and @rh-hemartin covering the most important issues:
- Docker/Podman support clarity (important)
- OpenShell installation instructions (moderate)
- Security concerns with
/tmp/paths (moderate, deferred) - Merge ordering dependency on #662 (minor, deferred)
- Install path preferences and example improvements
I'm adding two minor notes below for future consideration. Approving since the documentation is solid and the existing comments cover the substantive issues.
Dependencies: This PR documents features from #662, so it should merge after #662 lands (already noted by @ralphbean).
| | Linux (x86_64) | `fullsend_{version}_linux_amd64.tar.gz` | | ||
| | Linux (arm64) | `fullsend_{version}_linux_arm64.tar.gz` | | ||
|
|
||
| Extract and move to a directory in your PATH: |
There was a problem hiding this comment.
[moderate — deferred] Consider adding a step to verify the downloaded binary checksum or signature. This is a security best practice for software distribution. GoReleaser can generate checksums files automatically — if the release includes a checksums.txt, add a verification step:
# Verify the checksum (optional but recommended)
shasum -a 256 -c checksums.txt 2>&1 | grep fullsend_0.4.0_darwin_arm64.tar.gzNot blocking for this PR, but worth considering for a future update.
| - The default `:latest` tag is amd64-only. Add `FULLSEND_SANDBOX_IMAGE=ghcr.io/fullsend-ai/fullsend-sandbox:dev` to your env file | ||
|
|
||
| **`unable to replace "host-gateway"` on macOS** | ||
| - Set `host_containers_internal_ip = "192.168.127.254"` under `[containers]` in `~/.config/containers/containers.conf` and restart the Podman machine |
There was a problem hiding this comment.
[minor — deferred] Consider adding a "Cleanup" or "Maintenance" section covering:
- How to remove stopped sandbox containers (
podman ps -a,podman rm) - When/how to update the local
.fullsendconfig directory clone - How to clean up temporary artifacts
Users following this guide might accumulate containers or wonder about keeping their config up-to-date. Not urgent, but would round out the guide.
4 participants
Summary
docs/guides/user/running-agents-locally.md) covering the full workflow for running fullsend agents on macOS and Linux using released binaries — no Go toolchain or source checkout needed.fullsendconfig directory, creating env files with per-agent variables, running each agent type (triage, review, code, fix), cross-platform binary resolution, platform notes, and troubleshootingdocs/guides/README.mdunder User guidesSplit out from #662 to keep the feature PR focused on the code change.
Test plan
local-dev.md, GitHub Releases URL)docs/guides/README.mdentry renders correctly