Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

Fix macrod releases and add Hermes setup guide (#5881)

Wolf Mermelstein040fdb5eb21c
diff --git a/.github/actions/setup-nix-dev-shell/action.yml b/.github/actions/setup-nix-dev-shell/action.yml
index 2fc8f19ef8..5bbd3ed4f5 100644
--- a/.github/actions/setup-nix-dev-shell/action.yml
+++ b/.github/actions/setup-nix-dev-shell/action.yml
@@ -1,15 +1,29 @@
name: Setup Nix dev shell
-description: Enter the repository Nix dev shell without configuring a cache provider.
+description: Enter a repository Nix dev shell without configuring a cache provider.
+
+inputs:
+ shell:
+ description: Flake `devShells` attribute to enter (e.g. `default`, `agent-daemon`).
+ required: false
+ default: default
runs:
using: composite
steps:
- name: Enter Nix dev shell
shell: bash
+ env:
+ DEV_SHELL: ${{ inputs.shell }}
run: |
set -euo pipefail
+ case "$DEV_SHELL" in
+ ''|*[!A-Za-z0-9_-]*)
+ echo "invalid devShell attribute: ${DEV_SHELL@Q}" >&2
+ exit 1
+ ;;
+ esac
dev_env="$RUNNER_TEMP/nix-dev-env"
- nix print-dev-env --accept-flake-config > "$dev_env"
+ nix print-dev-env --accept-flake-config ".#$DEV_SHELL" > "$dev_env"
echo "BASH_ENV=$dev_env" >> "$GITHUB_ENV"
source "$dev_env"
printf '%s\n' "$PATH" | tr ':' '\n' >> "$GITHUB_PATH"
diff --git a/.github/workflows/build_agent_daemon_on_tag.yml b/.github/workflows/build_agent_daemon_on_tag.yml
index 44cd6b73dd..86bfb3a578 100644
--- a/.github/workflows/build_agent_daemon_on_tag.yml
+++ b/.github/workflows/build_agent_daemon_on_tag.yml
@@ -88,8 +88,15 @@ jobs:
continue-on-error: true
- name: Setup Nix
uses: './.github/actions/setup-nix'
+ with:
+ nix-cache-url: ${{ vars.NIX_CACHE_URL }}
+ nix-cache-public-key: ${{ vars.NIX_CACHE_PUBLIC_KEY }}
+ aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY }}
+ aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
- name: Setup Nix dev shell
uses: './.github/actions/setup-nix-dev-shell'
+ with:
+ shell: agent-daemon
- name: Configure Namespace remote sccache
if: (github.event_name != 'pull_request' && github.event_name != 'pull_request_target') || github.event.pull_request.head.repo.full_name == github.repository
run: |-
@@ -265,8 +272,15 @@ jobs:
continue-on-error: true
- name: Setup Nix
uses: './.github/actions/setup-nix'
+ with:
+ nix-cache-url: ${{ vars.NIX_CACHE_URL }}
+ nix-cache-public-key: ${{ vars.NIX_CACHE_PUBLIC_KEY }}
+ aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY }}
+ aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
- name: Setup Nix dev shell
uses: './.github/actions/setup-nix-dev-shell'
+ with:
+ shell: agent-daemon
- name: Configure Namespace remote sccache
if: (github.event_name != 'pull_request' && github.event_name != 'pull_request_target') || github.event.pull_request.head.repo.full_name == github.repository
run: |-
@@ -712,6 +726,7 @@ jobs:
- build-daemon-linux-aarch64
- build-daemon-macos-aarch64
- build-daemon-macos-x86-64
+ if: '!cancelled() && needs.resolve-ref.result == ''success'' && (needs.build-daemon-linux-x86-64.result == ''success'' || needs.build-daemon-linux-aarch64.result == ''success'' || needs.build-daemon-macos-aarch64.result == ''success'' || needs.build-daemon-macos-x86-64.result == ''success'')'
name: Upload Release Artifacts
runs-on: ubuntu-latest
permissions:
diff --git a/apps/docs/AI/bring-your-own.mdx b/apps/docs/AI/bring-your-own.mdx
new file mode 100644
index 0000000000..0f3eb4e4ee
--- /dev/null
+++ b/apps/docs/AI/bring-your-own.mdx
@@ -0,0 +1,116 @@
+---
+title: "Bring your own agent"
+sidebarTitle: "Bring Your Own"
+icon: "terminal"
+tag: "Coming soon"
+description: "Connect a self-hosted ACP agent harness to Macro with macrod."
+---
+
+<Info>
+ Bring Your Own Agent will be available soon.
+</Info>
+
+You can run any [Agent Client Protocol (ACP)](https://zed.dev/acp)-compatible agent harness directly in Macro.
+
+Macro provides `macrod`, a small daemon that runs on your computer and waits for agent sessions. When you start a session or @mention your custom agent, `macrod` launches your configured harness, sends it the prompt, and bridges its ACP connection to Macro.
+
+<Warning>
+ Self-hosted agents can run real commands on your computer. Anyone who can prompt the agent may be able to affect its configured workspace. Use a dedicated workspace and grant channel access carefully.
+</Warning>
+
+## Before you start
+
+You need:
+
+- A machine that can keep an agent harness and `macrod` running
+- An ACP-compatible harness installed and configured on that machine
+- A public HTTPS endpoint that forwards webhooks (in this demo, to port `8790`)
+
+<Tip>
+ [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) can provide the HTTPS endpoint needed to receive webhooks without opening a router port. To use it, [install `cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) and run `cloudflared tunnel --url http://localhost:8790`. Then copy the temporary `https://....trycloudflare.com` URL and append `/macro-events` for the `public_url` below.
+</Tip>
+
+<Steps>
+ <Step title="Create a Macro agent">
+ Open **Settings → Bots → Create bot**. Enable **Make this bot a coding agent**, choose the channels it can join, and create it.
+
+ Copy the agent token when it appears. Macro shows it only once, but you can create a new one later if you lose it.
+ </Step>
+
+ <Step title="Prepare an agent harness">
+ Install your preferred ACP-compatible agent and identify the command that starts its ACP server. Verify that command before configuring `macrod`.
+
+ These harnesses provide ACP entrypoints:
+
+ - **Claude Code:** `npx -y @agentclientprotocol/claude-agent-acp`
+ - **Codex:** `npx -y @agentclientprotocol/codex-acp`
+ - **Hermes:** `hermes-acp` (run `hermes-acp --check` first)
+ - **OpenCode:** `opencode acp`
+ - **OpenClaw:** `openclaw acp`
+
+ Claude Code and Codex require their linked adapter packages because the base `claude` and `codex` commands do not expose ACP servers directly.
+ </Step>
+
+ <Step title="Download macrod">
+ Open the [latest Macro release](https://github.com/macro-inc/macro/releases/latest) and download the `macrod` archive for your OS and architecture. Currently, we officially support macOS and Linux.
+ </Step>
+
+ <Step title="Start the HTTPS tunnel">
+ `macrod` listens on port `8790` and receives requests at `POST /macro-events`. Macro must be able to reach that endpoint over public HTTPS.
+
+ For the Cloudflare quick tunnel described above, run:
+
+ ```bash
+ cloudflared tunnel --url http://localhost:8790
+ ```
+
+ Keep this process running and copy the URL it prints.
+
+ <Note>
+ A quick-tunnel URL changes whenever `cloudflared` restarts. Create a [named Cloudflare tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/) for a stable endpoint.
+ </Note>
+
+ Alternatively, you can port-forward or deploy your harness to a cloud server.
+ </Step>
+
+ <Step title="Configure macrod">
+ Create `macro.toml` beside the `macrod` binary:
+
+ ```toml
+ [macro]
+ api_url = "https://agent-harness.macro.com"
+ storage_url = "https://cloud-storage.macro.com"
+ owner_user_id = "macro|[email protected]"
+ bot_token = "mbot_..."
+ bot_scope = "user"
+
+ [server]
+ port = 8790
+ public_url = "https://example.trycloudflare.com/macro-events"
+
+ [harness]
+ command = "your-acp-agent"
+ args = []
+
+ [workspace]
+ path = "/absolute/path/to/your/repository"
+ repo_url = "https://github.com/you/your-repository"
+ ```
+
+ Change `[email protected]` in `owner_user_id` to the email address you use to sign in to Macro. Replace `mbot_...` with the token from the first step. Set `command` and `args` to the ACP launch command from the second step.
+ </Step>
+
+ <Step title="Start the agent">
+ Keep the HTTPS tunnel running, then start `macrod` from a shell where your harness command is available:
+
+ ```bash
+ ./macrod --config ./macro.toml
+ ```
+
+ When `macrod` reports that it is listening for agent triggers, @mention the agent in one of its Macro channels.
+ </Step>
+</Steps>
+
+## Keep it connected
+
+Both `macrod` and your HTTPS tunnel must stay running for you to start self-hosted agent sessions from Macro.
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index f5946fee3c..971f24359d 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -63,6 +63,7 @@
"group": "Agents",
"pages": [
"AI/recipes",
+ "AI/bring-your-own",
"AI/mcp/overview",
{
"group": "Tool Reference",
diff --git a/apps/web/src/features/channel/Bots/BotAgentSection.tsx b/apps/web/src/features/channel/Bots/BotAgentSection.tsx
index 121677dc0f..4502c888d0 100644
--- a/apps/web/src/features/channel/Bots/BotAgentSection.tsx
+++ b/apps/web/src/features/channel/Bots/BotAgentSection.tsx
@@ -36,6 +36,19 @@ export function BotAgentSection(props: {
labelClass="sr-only"
/>
</div>
+
+ <Show when={props.checked}>
+ <div class="mt-4 border-t border-edge-muted pt-3">
+ <a
+ class="inline-flex h-7 items-center rounded-md border border-edge-muted px-2 text-xs font-medium text-ink-muted hover:bg-hover hover:text-ink"
+ href="https://docs.macro.com/AI/bring-your-own"
+ target="_blank"
+ rel="noopener noreferrer"
+ >
+ Connecting an agent? View setup guide
+ </a>
+ </div>
+ </Show>
</BotFormSection>
</Show>
);
diff --git a/nix/cloud-storage.nix b/nix/cloud-storage.nix
index d1c5bbb1ec..01689953dc 100644
--- a/nix/cloud-storage.nix
+++ b/nix/cloud-storage.nix
@@ -1073,6 +1073,25 @@
BINDGEN_EXTRA_CLANG_ARGS = "-I${pkgs.glibc.dev}/include -I${pkgs.gcc.cc}/lib/gcc/${pkgs.stdenv.hostPlatform.config}/${pkgs.gcc.version}/include";
}
);
+
+ # Keep release builds independent of optional developer tools in the
+ # default shell. In particular, adding Hermes there must not make
+ # macrod releases fetch or realize Hermes and its Python/npm closure.
+ agent-daemon = pkgs.mkShell {
+ packages = [
+ rustToolchain
+ pkgs.cargo-zigbuild
+ pkgs.zig
+ pkgs.cmake
+ pkgs.perl
+ pkgs.pkg-config
+ pkgs.sccache
+ nsc
+ ];
+ RUSTC_WRAPPER = "${pkgs.sccache}/bin/sccache";
+ CARGO_INCREMENTAL = "0";
+ AWS_LC_SYS_CMAKE_BUILDER = "1";
+ };
};
};
}
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/build_agent_daemon_on_tag.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/build_agent_daemon_on_tag.rs
index 75fb306eb8..8dbaa5ea38 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/build_agent_daemon_on_tag.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/build_agent_daemon_on_tag.rs
@@ -22,6 +22,9 @@ use crate::workflows::{build_appimage_on_tag, runners, steps, vars};
use std::collections::HashMap;
+#[cfg(test)]
+mod test;
+
const RESOLVED_REF: &str = "${{ needs.resolve-ref.outputs.ref }}";
/// One published binary.
@@ -93,10 +96,23 @@ pub fn build_agent_daemon_on_tag() -> Workflow {
for target in LINUX_TARGETS.iter().chain(MACOS_TARGETS) {
publish = publish.add_needs(job_id(target));
}
+ // A failed platform must not prevent successful platform artifacts from
+ // reaching the release.
+ publish = publish.cond(Expression::new(publish_when_any_build_succeeded()));
workflow.add_job("publish-daemon", publish)
}
+fn publish_when_any_build_succeeded() -> String {
+ let any_build = LINUX_TARGETS
+ .iter()
+ .chain(MACOS_TARGETS)
+ .map(|target| format!("needs.{}.result == 'success'", job_id(target)))
+ .collect::<Vec<_>>()
+ .join(" || ");
+ format!("!cancelled() && needs.resolve-ref.result == 'success' && ({any_build})")
+}
+
fn job_id(target: &DaemonTarget) -> String {
format!("build-daemon-{}", target.slug.replace('_', "-"))
}
@@ -144,16 +160,16 @@ fn resolve_ref_step() -> Step<Run> {
.add_env(("SELECTED_REF", "${{ github.ref }}"))
}
-/// The Nix dev shell is what carries cargo-zigbuild, zig, and cmake, so the
-/// musl builds go through it rather than a bare rustup toolchain.
+/// The minimal agent-daemon Nix shell carries cargo-zigbuild, zig, and cmake
+/// without realizing unrelated developer tools from the default shell.
fn linux_job(target: &DaemonTarget) -> Job {
Job::default()
.name(format!("Build daemon ({})", target.slug))
.runs_on(runners::Runner::RustCi.to_string())
.add_step(steps::checkout_ref(RESOLVED_REF))
.add_step(steps::mount_cache_volume())
- .add_step(steps::setup_nix())
- .add_step(steps::setup_dev_shell())
+ .add_step(steps::setup_nix_with_cache())
+ .add_step(steps::setup_dev_shell_named("agent-daemon"))
// The dev shell points RUSTC_WRAPPER at sccache regardless; this aims
// it at the shared remote cache so a release build is not a cold
// compile of the whole dependency graph. It degrades to the local
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/build_agent_daemon_on_tag/test.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/build_agent_daemon_on_tag/test.rs
new file mode 100644
index 0000000000..88c7a19311
--- /dev/null
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/build_agent_daemon_on_tag/test.rs
@@ -0,0 +1,47 @@
+use super::*;
+
+fn rendered_yaml() -> String {
+ build_agent_daemon_on_tag()
+ .to_string()
+ .expect("daemon workflow should serialize")
+}
+
+#[test]
+fn linux_jobs_enter_the_agent_daemon_shell() {
+ let yaml = rendered_yaml();
+ assert_eq!(
+ yaml.matches("shell: agent-daemon").count(),
+ LINUX_TARGETS.len(),
+ "every Linux target should request the agent-daemon shell"
+ );
+}
+
+#[test]
+fn linux_jobs_wire_the_s3_nix_cache() {
+ let yaml = rendered_yaml();
+ assert_eq!(
+ yaml.matches("nix-cache-url: ${{ vars.NIX_CACHE_URL }}")
+ .count(),
+ LINUX_TARGETS.len()
+ );
+}
+
+#[test]
+fn publish_runs_when_any_platform_succeeds() {
+ let yaml = rendered_yaml();
+ let publish = yaml
+ .split("\n publish-daemon:\n")
+ .nth(1)
+ .expect("publish-daemon job");
+ let if_line = publish
+ .lines()
+ .find(|line| line.trim_start().starts_with("if:"))
+ .expect("publish-daemon should tolerate individual platform failures");
+ assert!(if_line.contains("!cancelled()"));
+ assert!(if_line.contains("needs.resolve-ref.result"));
+ assert!(if_line.contains(" || "));
+ assert!(!if_line.contains(" && needs.build-daemon"));
+ for target in LINUX_TARGETS.iter().chain(MACOS_TARGETS) {
+ assert!(if_line.contains(&format!("needs.{}.result == ''success''", job_id(target))));
+ }
+}
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/steps.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/steps.rs
index c3ddd0d0d1..49b750c42c 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/steps.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/steps.rs
@@ -118,8 +118,8 @@ pub fn setup_nix() -> Step<Use> {
/// [`setup_nix`] with the private S3 binary cache configured as a substituter,
/// so a /nix cache-volume miss degrades to a download instead of a rebuild.
-/// Only for jobs with access to the AWS secrets (deploy pipeline — never
-/// PR-triggered jobs). No-ops back to plain [`setup_nix`] behavior while the
+/// Only for trusted jobs with access to the AWS secrets (never PR-triggered
+/// jobs). No-ops back to plain [`setup_nix`] behavior while the
/// `NIX_CACHE_*` repo variables are unset.
pub fn setup_nix_with_cache() -> Step<Use> {
setup_nix()
@@ -169,7 +169,8 @@ pub fn push_nix_cache(targets: &str) -> Step<Run> {
/// and `RUSTC_WRAPPER=sccache`) without selecting an sccache provider or
/// configuring an external Nix binary cache. Jobs that compile Rust can follow
/// this with [`configure_namespace_sccache`] to use Namespace's official remote
-/// cache. Requires [`setup_nix`] first.
+/// cache. Requires [`setup_nix`] first. The composite action defaults to the
+/// `default` flake shell when no `shell` input is passed.
pub fn setup_dev_shell() -> Step<Use> {
uses_local(
"Setup Nix dev shell",
@@ -177,6 +178,11 @@ pub fn setup_dev_shell() -> Step<Use> {
)
}
+/// [`setup_dev_shell`] for a named `devShells.<name>` flake output.
+pub fn setup_dev_shell_named(name: &str) -> Step<Use> {
+ setup_dev_shell().add_with(("shell", name))
+}
+
/// Mount the Namespace profile's persisted cache volume: `cache: rust` persists
/// the cargo registry/git, and `path:` persists the Nix store. Compiled objects
/// deliberately use Namespace's official remote sccache instead of this volume.
diff --git a/tooling/xtask/crates/xtask_workflows/src/workflows/steps/test.rs b/tooling/xtask/crates/xtask_workflows/src/workflows/steps/test.rs
index a78552abfe..3633d96a72 100644
--- a/tooling/xtask/crates/xtask_workflows/src/workflows/steps/test.rs
+++ b/tooling/xtask/crates/xtask_workflows/src/workflows/steps/test.rs
@@ -48,3 +48,22 @@ fn namespace_sccache_combines_job_specific_and_trust_conditions() {
);
assert!(condition.0.contains("steps.filter.outputs.hit == 'true'"));
}
+
+#[test]
+fn named_dev_shell_passes_the_flake_attribute() {
+ let step = setup_dev_shell_named("agent-daemon");
+ let with = step.value.with.expect("named shell should set with.shell");
+ assert_eq!(
+ with.0.get("shell").and_then(|value| value.as_str()),
+ Some("agent-daemon")
+ );
+}
+
+#[test]
+fn default_dev_shell_does_not_pass_a_shell_input() {
+ let step = setup_dev_shell();
+ assert!(
+ step.value.with.is_none(),
+ "unspecified shell must keep the action default so other workflows stay unchanged"
+ );
+}