Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Per-instance isolation: names, networks, volumes, and host ports.
//!
//! The default instance is named `macro` and keeps the exact resource names
//! and host ports the repo uses today, so existing worktrees and muscle memory
//! are untouched. A named instance (`--instance agent-a`) derives a disjoint
//! set of project name, networks, volumes, and a deterministic high port window
//! so two stacks can run concurrently without clobbering each other.
use std::net::TcpListener;
use anyhow::{Context, Result, bail};
use strum::{EnumIter, IntoEnumIterator};
use super::repo_root;
/// The reserved default instance name. Maps to today's frozen `macro` Compose
/// project and the fixed base ports.
pub const DEFAULT_NAME: &str = "macro";
/// Start of the non-default port window. Keep the entire allocation below
/// Linux's default ephemeral range (32768-60999), otherwise an ordinary
/// outbound connection can intermittently occupy a Compose host port.
const WINDOW_START: u32 = 20_000;
const STRIDE: u32 = 100;
const BUCKETS: u32 = 120; // 20000..=31999
/// A validated instance name: lowercase ASCII alphanumerics, hyphen, and
/// underscore, starting alphanumeric, non-empty, <= 40 chars. The newtype
/// guarantees every constructed name is a legal Docker resource-name component.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct InstanceName(String);
impl InstanceName {
pub fn parse(raw: &str) -> Result<Self> {
ensure_valid(raw)?;
Ok(InstanceName(raw.to_string()))
}
pub fn as_str(&self) -> &str {
&self.0
}
}
fn ensure_valid(raw: &str) -> Result<()> {
if raw.is_empty() {
bail!("instance name must not be empty");
}
if raw.len() > 40 {
bail!("instance name '{raw}' is too long (max 40 chars)");
}
let ok = raw.bytes().enumerate().all(|(i, b)| match b {
b'a'..=b'z' | b'0'..=b'9' => true,
b'-' | b'_' => i != 0,
_ => false,
});
if !ok {
bail!(
"instance name '{raw}' must be lowercase [a-z0-9_-] and start with an alphanumeric \
(so it yields valid Docker network/volume names)"
);
}
Ok(())
}
/// Every host port the orchestrator allocates. The discriminant IS the port the
/// default `macro` instance binds (matching the values hardcoded in the compose
/// files today); a named instance binds `port_base + offset`, where `offset` is
/// the variant's position in declaration order. Adding a port is a single line:
/// `NewThing = 8099,`. Offsets stay below `STRIDE`, so named windows never
/// overlap.
#[derive(Clone, Copy, Debug, PartialEq, Eq, EnumIter)]
#[repr(u16)]
pub enum Port {
Postgres = 5432,
Redis = 6379,
RedisUi = 8001,
OpenSearch = 9200,
OpenSearchPa = 9600,
FusionAuth = 9011,
LocalStack = 4566,
MailpitSmtp = 1025,
MailpitUi = 8025,
Proxy = 8090,
Frontend = 3000,
Auth = 8080,
ConnGateway = 8082,
Contacts = 8083,
DocCognition = 8085,
DocStorage = 8086,
Email = 8087,
Notification = 8089,
SearchProcessing = 8092,
StaticFile = 8094,
Unfurl = 8095,
ImageProxy = 8097,
Kafka = 9092,
SdkWebhookSsh = 8788,
SdkWebhookHostReceiver = 8789,
// Appended (not slotted by number) so existing per-instance port offsets,
// which come from declaration order, stay stable.
/// Retired with agent_proxy_service; kept (in place, at the end) because
/// per-instance port offsets come from declaration order, and removing a
/// variant would shift every one declared after it.
AgentProxy = 8091,
/// Agent session control API.
AgentHarness = 8101,
/// The agent egress proxy, `agent_harness_service`'s second listener.
/// Published on every local instance - it is what the Cursor egress
/// tunnel points at, and Cursor's cloud is outside the compose network.
AgentHarnessEgress = 8102,
/// Scheduled actions API and dispatcher (default compose port 8099).
ScheduledAction = 8099,
/// Calendar service API (default compose port 8088). Appended at the end so
/// existing per-instance port offsets, which come from declaration order,
/// stay stable.
Calendar = 8088,
/// Live-preview control API. Appended after Calendar for the same reason.
PreviewControl = 8110,
/// Stock SSH reverse-tunnel listener.
PreviewSsh = 2222,
/// Local wildcard preview TLS listener.
PreviewHttps = 8443,
}
impl Port {
/// The port the default `macro` instance binds — the variant's discriminant.
pub const fn fixed(self) -> u16 {
self as u16
}
/// The per-port offset within a named instance's stride: the variant's
/// position in declaration order. Unique and `< STRIDE` by construction
/// (there are far fewer variants than the stride).
pub fn offset(self) -> u16 {
Port::iter()
.position(|p| p == self)
.expect("every Port is yielded by iter()") as u16
}
/// Every allocated port — used by doctor / collision probing / the env
/// summary.
pub fn all() -> impl Iterator<Item = Port> {
Port::iter()
}
}
/// A resolved instance: its identity plus the derived resource names and port
/// base. Construct with [`Instance::derive`].
#[derive(Clone, Debug)]
pub struct Instance {
name: InstanceName,
project_name: String,
port_base: u16,
}
impl Instance {
/// Derive the instance from the `--instance`/`--port-base` flags. `None`
/// (or `--instance macro`) is the default instance.
pub fn derive(instance: Option<&str>, port_base: Option<u16>) -> Result<Self> {
let name = match instance {
None | Some(DEFAULT_NAME) => InstanceName(DEFAULT_NAME.to_string()),
Some(n) => InstanceName::parse(n)?,
};
let project_name = if name.as_str() == DEFAULT_NAME {
DEFAULT_NAME.to_string()
} else {
format!("macro-{}", name.0)
};
let port_base = port_base.unwrap_or_else(|| derive_port_base(&name));
Ok(Instance {
name,
project_name,
port_base,
})
}
pub fn name(&self) -> &str {
self.name.as_str()
}
pub fn is_default(&self) -> bool {
self.name.as_str() == DEFAULT_NAME
}
/// The Compose project name (`-p` / `COMPOSE_PROJECT_NAME`).
pub fn project_name(&self) -> &str {
&self.project_name
}
#[allow(dead_code)] // used by tests and diagnostics
pub fn port_base(&self) -> u16 {
self.port_base
}
/// The host port this instance binds for `port`.
pub fn port(&self, port: Port) -> u16 {
if self.is_default() {
port.fixed()
} else {
self.port_base + port.offset()
}
}
/// External `databases` network name.
pub fn network_databases(&self) -> String {
self.suffixed_dash("databases")
}
/// External `auth` network name.
pub fn network_auth(&self) -> String {
self.suffixed_dash("auth")
}
pub fn volume_postgres(&self) -> String {
self.suffixed_underscore("macro_postgres_data")
}
pub fn volume_redis(&self) -> String {
self.suffixed_underscore("macro_redis_data")
}
pub fn volume_opensearch(&self) -> String {
self.suffixed_underscore("macro_opensearch_data")
}
pub fn volume_kafka(&self) -> String {
self.suffixed_underscore("macro_kafka_data")
}
pub fn volume_fusionauth_db(&self) -> String {
self.suffixed_underscore("fusionauth_db_data")
}
pub fn volume_fusionauth_config(&self) -> String {
self.suffixed_underscore("fusionauth_config")
}
/// Where generated artifacts (compose override, env file, kickstart,
/// Caddyfile, frontend env) live for this instance.
pub fn artifact_dir(&self) -> std::path::PathBuf {
repo_root()
.join("infra/local/generated")
.join(self.name.as_str())
}
fn suffixed_dash(&self, base: &str) -> String {
if self.is_default() {
base.to_string()
} else {
format!("{base}-{}", self.name.0)
}
}
fn suffixed_underscore(&self, base: &str) -> String {
if self.is_default() {
base.to_string()
} else {
format!("{base}_{}", self.name.0)
}
}
/// Probe every allocated host port with a TCP bind. Returns the host ports
/// that are already in use. Advisory-only; surfaced as a warning in doctor.
pub fn busy_ports(&self) -> Vec<u16> {
Port::all()
.filter_map(|p| {
let host_port = self.port(p);
match TcpListener::bind(("127.0.0.1", host_port)) {
Ok(_) => None,
Err(_) => Some(host_port),
}
})
.collect()
}
/// Create the instance's generated-artifact directory.
pub fn ensure_artifact_dir(&self) -> Result<std::path::PathBuf> {
let dir = self.artifact_dir();
std::fs::create_dir_all(&dir)
.with_context(|| format!("creating artifact dir {}", dir.display()))?;
Ok(dir)
}
}
/// Deterministically derive a port base from the instance name with FNV-1a.
/// FNV is stable across machines and Rust versions (unlike `DefaultHasher`),
/// so two developers running `--instance agent-a` get the same ports.
fn derive_port_base(name: &InstanceName) -> u16 {
(WINDOW_START + (fnv1a(name.as_str()) % BUCKETS) * STRIDE) as u16
}
fn fnv1a(s: &str) -> u32 {
let mut h: u32 = 0x811c_9dc5;
for b in s.bytes() {
h ^= b as u32;
h = h.wrapping_mul(0x0100_0193);
}
h
}
#[cfg(test)]
mod test;