Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Add eve start --no-schedules for self-hosted replicas (#5056)

prha743b4989a82e
diff --git a/.changeset/quiet-schedule-replicas.md b/.changeset/quiet-schedule-replicas.md
new file mode 100644
index 000000000..44342913f
--- /dev/null
+++ b/.changeset/quiet-schedule-replicas.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+`eve start --no-schedules` and `EVE_SCHEDULES_DISABLED=1` start a server that does not fire authored cron schedules, so only one process runs them when you scale out.
diff --git a/docs/guides/deployment/self-hosting.md b/docs/guides/deployment/self-hosting.md
index 8a9a91c88..dc727e026 100644
--- a/docs/guides/deployment/self-hosting.md
+++ b/docs/guides/deployment/self-hosting.md
@@ -105,6 +105,8 @@ You can instead use [`eve/next`](../frontend/nextjs#dev-vs-deploy-topology) if y
The standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.
+Each `eve start` process runs every authored schedule. When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).
+
## Verify the service
Check the health route after your proxy and authentication configuration are active:
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index bb71a0db3..c1ae041a0 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -241,15 +241,20 @@ Useful stable artifacts written by inspection and development flows under `.eve/
## `eve start`
```bash
-eve start [--host <host>] [--port <port>]
+eve start [--host <host>] [--port <port>] [--no-schedules]
```
-| Flag | Type | Default | Description |
-| --------------- | ------ | ------------------ | ---------------------- |
-| `--host <host>` | string | all interfaces | Host interface to bind |
-| `--port <port>` | number | `$PORT`, then 3000 | Port to listen on |
+| Flag | Type | Default | Description |
+| ---------------- | ------ | ------------------ | --------------------------------------------- |
+| `--host <host>` | string | all interfaces | Host interface to bind |
+| `--port <port>` | number | `$PORT`, then 3000 | Port to listen on |
+| `--no-schedules` | flag | schedules on | Start without running authored cron schedules |
-Serves the previously built output. Prints the listening URL.
+Serves the previously built output. Prints the listening URL, and a `schedules disabled` line when `--no-schedules` or `EVE_SCHEDULES_DISABLED` turns schedules off. HTTP requests and workflow jobs continue to run.
+
+Set `EVE_SCHEDULES_DISABLED=1` or `true` (case-insensitive) to disable authored cron schedules at runtime, including when you run `node .output/server/index.mjs` directly. Unset, empty, and other values leave schedules enabled. `--no-schedules` sets the variable to `1` only for the spawned server; omitting the flag preserves any value you already set. The same build can run with schedules enabled or disabled.
+
+Use this setting when [scaling self-hosted replicas](../guides/deployment/self-hosting#run-schedules). It also disables authored cron dispatch on Vercel if set there, but does not affect explicit schedule dispatch in `eve dev`.
For self-hosted deployments, copy the app source, `.output/`, and installed dependencies together. The deployment directory can differ from the build directory. Preserve the relative layout of any workspace packages used by the app; startup resolves sandbox prewarm modules from the deployed source.
diff --git a/packages/eve/src/cli/dev/command-options.ts b/packages/eve/src/cli/dev/command-options.ts
index 50430df05..060ae055d 100644
--- a/packages/eve/src/cli/dev/command-options.ts
+++ b/packages/eve/src/cli/dev/command-options.ts
@@ -30,4 +30,5 @@ export interface DevelopmentCliOptions {
export interface ProductionCliOptions {
host?: string;
port?: number;
+ schedules?: boolean;
}
diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.ts
index 63721e9ea..ce4a3bd26 100644
--- a/packages/eve/src/cli/run.test.ts
+++ b/packages/eve/src/cli/run.test.ts
@@ -1,6 +1,6 @@
import { resolve } from "node:path";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
import { createCliProgram, resolveDevUiMode, resolveTuiDisplayOptions, runCli } from "#cli/run.js";
import { cliTelemetryCommandPaths, internalCliCommandPaths } from "#cli/telemetry/index.js";
@@ -664,6 +664,41 @@ describe("eve dev --input", () => {
});
});
+describe("eve start schedules", () => {
+ afterEach(() => vi.unstubAllEnvs());
+
+ it.each([
+ { argv: ["start", "--no-schedules"], inherited: undefined, schedules: false, reported: true },
+ { argv: ["start"], inherited: "1", schedules: true, reported: true },
+ { argv: ["start"], inherited: undefined, schedules: true, reported: false },
+ ])(
+ "passes schedules=$schedules and reports disabled=$reported for $argv with $inherited",
+ async ({ argv, inherited, schedules, reported }) => {
+ vi.stubEnv("EVE_SCHEDULES_DISABLED", inherited);
+ const lines: string[] = [];
+ const startProductionHost = vi.fn(async () => ({
+ close: async () => {},
+ url: "http://127.0.0.1:4321/",
+ wait: async () => {},
+ }));
+
+ await runCli(
+ argv,
+ { error: () => {}, log: (line) => lines.push(line) },
+ {
+ startProductionHost,
+ },
+ );
+
+ expect(startProductionHost).toHaveBeenCalledWith(
+ expect.any(String),
+ expect.objectContaining({ schedules }),
+ );
+ expect(lines.some((line) => line.includes("schedules disabled"))).toBe(reported);
+ },
+ );
+});
+
describe("eve remote invoke", () => {
it("runs a fresh remote task without starting the TUI", async () => {
const runInvoke = vi.fn(async () => ({
diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.ts
index 852934a33..3b020c46e 100644
--- a/packages/eve/src/cli/run.ts
+++ b/packages/eve/src/cli/run.ts
@@ -1,6 +1,7 @@
import { Command, CommanderError } from "#compiled/commander/index.js";
import { registerBuildCommand, type BuildHost } from "#cli/commands/build.js";
import { resolveApplicationRoot } from "#internal/application/paths.js";
+import { areSchedulesDisabled } from "#internal/schedules/disabled.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
import { isCodingAgentLaunch } from "#cli/agent-detection.js";
import type { CliApplicationContext } from "#cli/application-command.js";
@@ -79,6 +80,7 @@ interface CliRuntimeDependencies {
options?: {
host?: string;
port?: number;
+ schedules?: boolean;
},
): Promise<ProductionServerHandle>;
}
@@ -253,6 +255,7 @@ export function createCliProgram(
agentCommand(program.command("start"), applicationContext)
.description("Start a built eve application.")
+ .option("--no-schedules", "Start without running authored cron schedules")
.option("--host <host>", "Host interface to bind")
.option("--port <port>", "Port to listen on (defaults to $PORT, then 3000)", parsePortOption)
.action(async (options: ProductionCliOptions) => {
@@ -264,6 +267,7 @@ export function createCliProgram(
const server = await startProductionHost(applicationContext.root, {
host: options.host,
port: options.port,
+ schedules: options.schedules,
});
logger.log(
@@ -274,6 +278,17 @@ export function createCliProgram(
}),
);
+ // The server inherits this process environment, including loaded env files.
+ if (options.schedules === false || areSchedulesDisabled()) {
+ logger.log(
+ renderCliTaggedLine(theme, {
+ message: "schedules disabled",
+ tag: "start",
+ tone: "info",
+ }),
+ );
+ }
+
await waitForShutdownSignal({ close: () => server.close(), wait: () => server.wait() });
});
diff --git a/packages/eve/src/internal/nitro/host/start-production-server.test.ts b/packages/eve/src/internal/nitro/host/start-production-server.test.ts
index 88acbf991..df13d8aad 100644
--- a/packages/eve/src/internal/nitro/host/start-production-server.test.ts
+++ b/packages/eve/src/internal/nitro/host/start-production-server.test.ts
@@ -68,6 +68,7 @@ describe("startProductionServer", () => {
afterEach(() => {
vi.restoreAllMocks();
+ vi.unstubAllEnvs();
globalThis.fetch = originalFetch;
if (originalPort === undefined) {
delete process.env.PORT;
@@ -120,6 +121,28 @@ describe("startProductionServer", () => {
expect(child.kill).toHaveBeenCalledWith("SIGTERM");
});
+ it.each([
+ { schedules: undefined, inherited: undefined, expected: undefined },
+ { schedules: false, inherited: undefined, expected: "1" },
+ { schedules: undefined, inherited: "true", expected: "true" },
+ { schedules: false, inherited: "false", expected: "1" },
+ ])(
+ "passes EVE_SCHEDULES_DISABLED=$expected for schedules=$schedules over $inherited",
+ async ({ schedules, inherited, expected }) => {
+ vi.stubEnv("EVE_SCHEDULES_DISABLED", inherited);
+ const { startProductionServer } = await import("./start-production-server.js");
+ const child = createChildProcess();
+ (child.stdout as PassThrough).write("Listening on http://127.0.0.1:4321/\n");
+ mocks.spawn.mockReturnValueOnce(child);
+
+ const server = await startProductionServer("/tmp/app", { schedules });
+ const spawnOptions = mocks.spawn.mock.calls[0]?.[2] as { env: NodeJS.ProcessEnv };
+ expect(spawnOptions.env.EVE_SCHEDULES_DISABLED).toBe(expected);
+ expect(process.env.EVE_SCHEDULES_DISABLED).toBe(inherited);
+ await server.close();
+ },
+ );
+
it("uses PORT when no explicit port is provided", async () => {
const { startProductionServer } = await import("./start-production-server.js");
const child = createChildProcess();
diff --git a/packages/eve/src/internal/nitro/host/start-production-server.ts b/packages/eve/src/internal/nitro/host/start-production-server.ts
index 7dd61736e..7fa30c289 100644
--- a/packages/eve/src/internal/nitro/host/start-production-server.ts
+++ b/packages/eve/src/internal/nitro/host/start-production-server.ts
@@ -6,6 +6,7 @@ import { setTimeout as sleep } from "node:timers/promises";
import { loadDevelopmentEnvironmentFiles } from "#cli/dev/environment.js";
import type { ProductionServerHandle } from "#internal/nitro/host/types.js";
+import { EVE_SCHEDULES_DISABLED_ENV } from "#internal/schedules/disabled.js";
const DEFAULT_PRODUCTION_SERVER_HOST = "0.0.0.0";
const DEFAULT_PRODUCTION_SERVER_PORT = 3000;
@@ -192,6 +193,7 @@ export async function startProductionServer(
options: {
host?: string;
port?: number;
+ schedules?: boolean;
} = {},
): Promise<ProductionServerHandle> {
const appRoot = resolve(rootDir);
@@ -221,15 +223,20 @@ export async function startProductionServer(
let closing = false;
let startError: unknown;
+ const env: NodeJS.ProcessEnv = {
+ ...process.env,
+ HOST: host,
+ NITRO_HOST: host,
+ NITRO_PORT: String(port),
+ PORT: String(port),
+ };
+ if (options.schedules === false) {
+ env[EVE_SCHEDULES_DISABLED_ENV] = "1";
+ }
+
const child = spawn(process.execPath, [serverEntry], {
cwd: appRoot,
- env: {
- ...process.env,
- HOST: host,
- NITRO_HOST: host,
- NITRO_PORT: String(port),
- PORT: String(port),
- },
+ env,
stdio: ["ignore", "pipe", "pipe"],
});
diff --git a/packages/eve/src/internal/nitro/routes/schedule-task.test.ts b/packages/eve/src/internal/nitro/routes/schedule-task.test.ts
new file mode 100644
index 000000000..dc72538fc
--- /dev/null
+++ b/packages/eve/src/internal/nitro/routes/schedule-task.test.ts
@@ -0,0 +1,43 @@
+import { afterEach, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ info: vi.fn(),
+ loadResolvedCompiledScheduleByTaskName: vi.fn(),
+ resolveNitroCompiledArtifactsSource: vi.fn(),
+}));
+
+vi.mock("#internal/logging.js", () => ({
+ createLogger: () => ({ info: mocks.info }),
+}));
+vi.mock("#runtime/schedules/resolve-schedule.js", () => ({
+ loadResolvedCompiledScheduleByTaskName: mocks.loadResolvedCompiledScheduleByTaskName,
+}));
+vi.mock("#internal/nitro/routes/runtime-artifacts.js", () => ({
+ resolveNitroCompiledArtifactsSource: mocks.resolveNitroCompiledArtifactsSource,
+}));
+
+import { dispatchScheduleTask } from "./schedule-task.js";
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+});
+
+it("skips disabled schedules before resolving artifacts and logs only the first skipped tick", async () => {
+ vi.stubEnv("EVE_SCHEDULES_DISABLED", "1");
+ const config = { kind: "production", sandboxScope: "test" } as const;
+
+ await expect(dispatchScheduleTask("heartbeat", config)).resolves.toEqual({
+ skipped: "schedules-disabled",
+ taskName: "heartbeat",
+ });
+ await expect(dispatchScheduleTask("digest", config)).resolves.toEqual({
+ skipped: "schedules-disabled",
+ taskName: "digest",
+ });
+
+ expect(mocks.resolveNitroCompiledArtifactsSource).not.toHaveBeenCalled();
+ expect(mocks.loadResolvedCompiledScheduleByTaskName).not.toHaveBeenCalled();
+ expect(mocks.info).toHaveBeenCalledExactlyOnceWith(
+ 'Schedules are disabled in this process (EVE_SCHEDULES_DISABLED); skipping "heartbeat"',
+ );
+});
diff --git a/packages/eve/src/internal/nitro/routes/schedule-task.ts b/packages/eve/src/internal/nitro/routes/schedule-task.ts
index 77bf5287c..c020d7b5e 100644
--- a/packages/eve/src/internal/nitro/routes/schedule-task.ts
+++ b/packages/eve/src/internal/nitro/routes/schedule-task.ts
@@ -6,6 +6,11 @@ import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-
import type { NitroArtifactsConfig } from "#internal/nitro/routes/runtime-artifacts.js";
import { resolveNitroCompiledArtifactsSource } from "#internal/nitro/routes/runtime-artifacts.js";
import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import { createLogger } from "#internal/logging.js";
+import { areSchedulesDisabled, EVE_SCHEDULES_DISABLED_ENV } from "#internal/schedules/disabled.js";
+
+const log = createLogger("schedule.dispatch");
+let loggedSchedulesDisabled = false;
/**
* Dispatches one eve authored schedule via the execution engine.
@@ -17,7 +22,20 @@ import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts
export async function dispatchScheduleTask(
taskName: string,
config: NitroArtifactsConfig,
-): Promise<{ scheduleId: string; sessionIds: readonly string[] }> {
+): Promise<
+ | { scheduleId: string; sessionIds: readonly string[] }
+ | { skipped: "schedules-disabled"; taskName: string }
+> {
+ if (areSchedulesDisabled()) {
+ if (!loggedSchedulesDisabled) {
+ loggedSchedulesDisabled = true;
+ log.info(
+ `Schedules are disabled in this process (${EVE_SCHEDULES_DISABLED_ENV}); skipping "${taskName}"`,
+ );
+ }
+ return { skipped: "schedules-disabled", taskName };
+ }
+
return await dispatchScheduleTaskFromArtifacts(
taskName,
resolveNitroCompiledArtifactsSource(config),
diff --git a/packages/eve/src/internal/schedules/disabled.test.ts b/packages/eve/src/internal/schedules/disabled.test.ts
new file mode 100644
index 000000000..36fb15f79
--- /dev/null
+++ b/packages/eve/src/internal/schedules/disabled.test.ts
@@ -0,0 +1,16 @@
+import { expect, it } from "vitest";
+
+import { areSchedulesDisabled } from "./disabled.js";
+
+it.each([
+ [undefined, false],
+ ["", false],
+ ["0", false],
+ ["false", false],
+ ["yes", false],
+ ["1", true],
+ ["true", true],
+ ["TrUe", true],
+] as const)("interprets EVE_SCHEDULES_DISABLED=%s as disabled=%s", (value, disabled) => {
+ expect(areSchedulesDisabled({ EVE_SCHEDULES_DISABLED: value })).toBe(disabled);
+});
diff --git a/packages/eve/src/internal/schedules/disabled.ts b/packages/eve/src/internal/schedules/disabled.ts
new file mode 100644
index 000000000..dc856d1f1
--- /dev/null
+++ b/packages/eve/src/internal/schedules/disabled.ts
@@ -0,0 +1,8 @@
+export const EVE_SCHEDULES_DISABLED_ENV = "EVE_SCHEDULES_DISABLED";
+
+export function areSchedulesDisabled(
+ env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+ const value = env[EVE_SCHEDULES_DISABLED_ENV]?.toLowerCase();
+ return value === "1" || value === "true";
+}
diff --git a/packages/eve/test/scenarios/cli.scenario.test.ts b/packages/eve/test/scenarios/cli.scenario.test.ts
index 6b56142e3..5a1fa53f2 100644
--- a/packages/eve/test/scenarios/cli.scenario.test.ts
+++ b/packages/eve/test/scenarios/cli.scenario.test.ts
@@ -325,6 +325,7 @@ describe("runCli", () => {
expect(startProductionHost).toHaveBeenCalledWith(resolvedWorkspaceRoot, {
host: "127.0.0.1",
port: 0,
+ schedules: true,
});
});