Multiplayer agent harness for work.
import { codexAuthFileForEnv, loadCodexAuthFile } from "./model/chatgpt-auth-file.ts";
import {
deploymentBrokerCredentialsFromEnv,
type DeploymentBrokerCredential,
} from "./credentials/deployment-credentials.ts";
import { errMessage } from "./util/errors.ts";
import type { ExternalSlackPolicies } from "./resolution/external-slack.ts";
import { isBearerSecret, isStrongSigningSecret } from "./auth/source-auth.ts";
import { parseSandboxCapabilityTtlMs } from "./auth/capability-token.ts";
import { parseScopeId } from "./types.ts";
import type { LegacySandboxScopeDefaults } from "./sandbox/sandbox-resource-upgrade.ts";
import type { SandboxBackendName } from "./sandbox/sandbox-routing.ts";
import { existsSync, readdirSync } from "node:fs";
import {
parseProviderBaseUrl,
providerBaseUrlsFromEnv,
type ModelGatewayTransportConfig,
type ProviderBaseUrls,
} from "./model/provider-endpoints.ts";
import { join, resolve } from "node:path";
import {
parseMemoryCaptureMode,
parseMemoryRecallMode,
type MemoryCaptureMode,
type MemoryRecallMode,
} from "./memory/policy.ts";
import { parseMemoryStrategyKind, type MemoryStrategyKind } from "./memory/strategy.ts";
import { parseMemoryProviderConfig, type MemoryProviderConfig } from "./memory/provider-config.ts";
import { sanitizeBranding } from "./resolution/branding.ts";
import type { OrgBranding } from "./resolution/config-store.ts";
import { CORE_SECRET_SPECS, validateCoreSecretEnv } from "./deployment/secret-schema.ts";
import { DEFAULT_CAPTURE_QUIET_MS } from "./memory/strategies/per-turn.ts";
import {
parseSecurityPosture,
SECURITY_SCREEN_MODES,
type SecurityPosture,
type SecurityScreenMode,
} from "./security/security-posture.ts";
import { parseSharingPosture, type SharingPosture } from "./resolution/sharing-posture.ts";
import {
parseSlackContextSource,
type SlackContextSource,
slackPluginConfigFromEnv,
slackAccountConfigsFromEnv,
type SlackPluginConfig,
} from "./slack/config.ts";
import {
DEFAULT_CODEX_MODEL_ID,
MODEL_PROVIDERS,
defaultModelForProvider,
isModelProvider,
onlyProvider,
type ModelProvider,
type ModelProviderAvailability,
} from "./model/pi-models.ts";
import { resolveSwarmSettings, type SwarmSettings } from "./swarms/swarm-settings.ts";
export interface Config {
productAnalytics?: { apiKey: string; host?: string };
slackContextSource?: SlackContextSource;
suggestedActivitiesEnabled?: boolean;
suggestedActivitiesContext?: string;
swarmsEnabled?: boolean;
swarmDefaults?: SwarmSettings;
production: boolean;
allowUnauthenticatedCore: boolean;
port: number;
dataDir: string;
orgId: string;
sessionStore: "memory" | "postgres";
databaseUrl?: string;
databaseCaCert?: string;
databaseCaCertFile?: string;
databasePoolUrl?: string;
databasePoolCaCert?: string;
databasePoolMax?: number;
databaseDirectPoolMax?: number;
harness: "pi" | "claude";
securityPosture: SecurityPosture;
sharingPosture: SharingPosture;
legacySandboxScopeDefaults?: LegacySandboxScopeDefaults;
sandboxBackend: SandboxBackendName;
sandboxSecondaryBackend?: SandboxBackendName;
deployProvider: "docker" | "aws" | "fly" | "porter" | "e2b";
egressServiceHosts?: string[];
brandingDefault?: OrgBranding;
modelId?: string;
codexAuthFile?: string;
/** Keychain credential id holding the Codex ChatGPT OAuth auth.json (production path). */
codexAuthCredential?: string;
/** Keychain credential id holding a Claude Code subscription token (production path). */
claudeAuthCredential?: string;
claudeModel?: string;
claudeBinPath?: string;
claudeProcessEnv: NodeJS.ProcessEnv;
detectModelId?: string;
titleModelId?: string;
judgeModelId?: string;
anthropicApiKey?: string;
openaiApiKey?: string;
openrouterApiKey?: string;
modelProvider?: ModelProvider;
providerBaseUrls: ProviderBaseUrls;
modelGateway?: ModelGatewayTransportConfig;
brokerCredentials?: DeploymentBrokerCredential[];
piCaptureRequests: boolean;
piSystemCacheSplit: boolean;
adminGrants?: string;
trustedOidcAdminIssuer?: string;
emailAuthPrincipals?: string[];
emailAuthDomain?: string;
resendApiKey?: string;
emailFrom?: string;
rateLimitPerWindow: number;
rateLimitWindowMs: number;
budgetUsdPerWindow?: number;
orgBudgetUsdPerWindow?: number;
budgetWindowMs: number;
maxContextTokens?: number;
execTimeoutDefaultMs: number;
execTimeoutMaxMs: number;
turnWallClockMs: number;
runMaxAgeMs: number;
runWaitMs: number;
backgroundJobTtlMs: number;
sandboxCapabilityTtlMs: number;
backgroundJobTtlMaxMs: number;
backgroundWorkEnabled: boolean;
backgroundDeploymentId?: string;
deploymentControlSecret?: string;
spendExportToken?: string;
buildSha?: string;
monitorPollMs: number;
skillSyncPollMs: number;
monitorHeartbeatMs: number;
signingSecret?: string;
capabilitySecret?: string;
capabilityTokenCompression?: boolean;
portalIdentitySecret?: string;
requireSignedPortalIdentity?: boolean;
connectorSecretKey?: string;
slackEventsPort?: number;
secretsBackend: "env" | "aws";
secretsPrefix: string;
apiBaseUrl?: string;
publicUrl?: string;
gmailPubSub?: { topic: string; audience: string; serviceAccount: string };
publicWebUrl?: string;
flyAppName?: string;
slack?: SlackPluginConfig;
externalSlackPolicies?: ExternalSlackPolicies;
runStore: "memory" | "postgres";
skillSigningSecret?: string;
seedSkills: boolean;
skillsSeedDir: string;
pluginSkillDirs: string[];
deploymentLayerDir?: string;
layerEnv?: Readonly<Record<string, string | undefined>>;
filesDirectUploadsEnabled: boolean;
snapshotStore: "local" | "s3";
transferStore: "local" | "s3";
s3Bucket?: string;
s3Region?: string;
s3Prefix?: string;
deployIdleTtlMs?: number;
deployGitDir: string;
deployDialTimeoutMs: number;
deployAppsSessionSecret?: string;
deployAppsLoginUrl?: string;
deployAppsLoginPath?: "/auth/login" | "/auth/trusted/login";
deepIdleMachineMs: number;
devIdleMachineMs: number;
cronFireConcurrency: number;
memoryRecall: MemoryRecallMode;
memoryCapture: MemoryCaptureMode;
memoryStrategy: MemoryStrategyKind;
memoryProviderConfig?: MemoryProviderConfig;
memoryCaptureQuietMs: number;
memoryCaptureMaxTurns?: number;
workers: number;
leaseTtlMs: number;
heartbeatIntervalMs: number;
reaperIntervalMs: number;
shutdownDrainMs: number;
maxAttempts: number;
maxClaims: number;
processReaperIntervalMs: number;
approvalSummaryTimeoutMs: number;
turnLeaseWaitMs: number;
securityScreenTimeoutMs: number;
securityScreen: SecurityScreenMode;
securityScreenClassifier: "model" | "proxy";
securityScreenProxy?: {
provider: string;
endpoint: string;
token: string;
};
scratchExecEnabled: boolean;
reachExecEnabled: boolean;
surfaceDebugFooter: boolean;
eagerProvisionEnabled: boolean;
awsSandbox: AwsSandboxEnv;
localSandbox: LocalSandboxEnv;
spritesSandbox: SpritesSandboxEnv;
smolmachinesSandbox: SmolmachinesSandboxEnv;
agent37Sandbox: Agent37SandboxEnv;
superserveSandbox: SuperserveSandboxEnv;
e2bSandbox: E2bSandboxEnv;
managedAgentsSandbox: ManagedAgentsSandboxEnv;
modalSandbox: ModalSandboxEnv;
porterSandbox: PorterSandboxEnv;
porterDeploy: PorterDeployEnv;
awsDeploy: AwsDeployEnv;
deployAppsDomain?: string;
flyDeploy: FlyDeployEnv;
}
export function configuredModelForHarness(config: Config, harness: string): string | undefined {
if (harness === "claude") return config.claudeModel;
if (
harness === "pi" &&
!config.modelId &&
!config.anthropicApiKey &&
!config.modelProvider &&
harnessCarriedModelAuth(config) === "openai"
)
return DEFAULT_CODEX_MODEL_ID;
return config.modelId;
}
export function providerKeysPresent(config: Config): ModelProviderAvailability {
return {
anthropic: Boolean(config.anthropicApiKey),
openai: Boolean(config.openaiApiKey),
openrouter: Boolean(config.openrouterApiKey),
...(config.codexAuthCredential || config.codexAuthFile ? { codexOAuth: true } : {}),
};
}
export function baseModelProviders(config: Config): ModelProviderAvailability | undefined {
return config.modelProvider ? onlyProvider(config.modelProvider) : undefined;
}
export function harnessCarriedModelAuth(config: Config): ModelProvider | undefined {
if (
config.harness === "claude" &&
(config.claudeAuthCredential ||
config.claudeProcessEnv.CLAUDE_CODE_OAUTH_TOKEN ||
config.claudeProcessEnv.ANTHROPIC_AUTH_TOKEN)
)
return "anthropic";
if (config.codexAuthCredential || config.codexAuthFile) return "openai";
return undefined;
}
interface AwsSandboxEnv {
region: string;
profile?: string;
imageIdentifier: string;
imageVersion?: string;
executionRoleArn?: string;
ingressConnectorArns?: string[];
egressConnectorArns?: string[];
s3Bucket?: string;
s3Prefix?: string;
agentPort?: number;
maxIdleDurationSeconds?: number;
suspendedDurationSeconds?: number;
maximumDurationInSeconds?: number;
rotateAfterSeconds?: number;
snapshotIntervalMs?: number;
defaultTimeoutSec?: number;
cpus?: number;
memoryMb?: number;
diskGb?: number;
}
function awsSandboxEnv(env: NodeJS.ProcessEnv): AwsSandboxEnv {
const csv = (s: string | undefined): string[] | undefined =>
s
? s
.split(",")
.map((x) => x.trim())
.filter(Boolean)
: undefined;
const ingress = csv(env.AWS_SANDBOX_INGRESS_CONNECTORS);
const egress = csv(env.AWS_SANDBOX_EGRESS_CONNECTORS);
return {
region: env.AWS_SANDBOX_REGION ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION ?? "us-west-2",
...(env.AWS_SANDBOX_PROFILE ? { profile: env.AWS_SANDBOX_PROFILE } : {}),
imageIdentifier: env.AWS_SANDBOX_IMAGE ?? "qm-microvm-sandbox",
...(env.AWS_SANDBOX_IMAGE_VERSION ? { imageVersion: env.AWS_SANDBOX_IMAGE_VERSION } : {}),
...(env.AWS_SANDBOX_EXEC_ROLE_ARN ? { executionRoleArn: env.AWS_SANDBOX_EXEC_ROLE_ARN } : {}),
...(ingress ? { ingressConnectorArns: ingress } : {}),
...(egress ? { egressConnectorArns: egress } : {}),
...(env.AWS_SANDBOX_S3_BUCKET ? { s3Bucket: env.AWS_SANDBOX_S3_BUCKET } : {}),
...(env.AWS_SANDBOX_S3_PREFIX ? { s3Prefix: env.AWS_SANDBOX_S3_PREFIX } : {}),
...(numEnvStrict("AWS_SANDBOX_AGENT_PORT", env.AWS_SANDBOX_AGENT_PORT) !== undefined
? { agentPort: numEnvStrict("AWS_SANDBOX_AGENT_PORT", env.AWS_SANDBOX_AGENT_PORT) }
: {}),
...(numEnvStrict("AWS_SANDBOX_MAX_IDLE_SEC", env.AWS_SANDBOX_MAX_IDLE_SEC) !== undefined
? { maxIdleDurationSeconds: numEnvStrict("AWS_SANDBOX_MAX_IDLE_SEC", env.AWS_SANDBOX_MAX_IDLE_SEC) }
: {}),
...(numEnvStrict("AWS_SANDBOX_SUSPENDED_SEC", env.AWS_SANDBOX_SUSPENDED_SEC) !== undefined
? { suspendedDurationSeconds: numEnvStrict("AWS_SANDBOX_SUSPENDED_SEC", env.AWS_SANDBOX_SUSPENDED_SEC) }
: {}),
...(numEnvStrict("AWS_SANDBOX_MAX_DURATION_SEC", env.AWS_SANDBOX_MAX_DURATION_SEC) !== undefined
? { maximumDurationInSeconds: numEnvStrict("AWS_SANDBOX_MAX_DURATION_SEC", env.AWS_SANDBOX_MAX_DURATION_SEC) }
: {}),
...(numEnvStrict("AWS_SANDBOX_ROTATE_AFTER_SEC", env.AWS_SANDBOX_ROTATE_AFTER_SEC) !== undefined
? { rotateAfterSeconds: numEnvStrict("AWS_SANDBOX_ROTATE_AFTER_SEC", env.AWS_SANDBOX_ROTATE_AFTER_SEC) }
: {}),
...(numEnvStrict("AWS_SANDBOX_SNAPSHOT_INTERVAL_MS", env.AWS_SANDBOX_SNAPSHOT_INTERVAL_MS) !== undefined
? { snapshotIntervalMs: numEnvStrict("AWS_SANDBOX_SNAPSHOT_INTERVAL_MS", env.AWS_SANDBOX_SNAPSHOT_INTERVAL_MS) }
: {}),
...(env.QM_CORE_CONTAINER ? { coreContainer: env.QM_CORE_CONTAINER } : {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
...(numEnvStrict("AWS_SANDBOX_CPUS", env.AWS_SANDBOX_CPUS) !== undefined
? { cpus: numEnvStrict("AWS_SANDBOX_CPUS", env.AWS_SANDBOX_CPUS) }
: {}),
...(numEnvStrict("AWS_SANDBOX_MEMORY_MB", env.AWS_SANDBOX_MEMORY_MB) !== undefined
? { memoryMb: numEnvStrict("AWS_SANDBOX_MEMORY_MB", env.AWS_SANDBOX_MEMORY_MB) }
: {}),
...(numEnvStrict("AWS_SANDBOX_DISK_GB", env.AWS_SANDBOX_DISK_GB) !== undefined
? { diskGb: numEnvStrict("AWS_SANDBOX_DISK_GB", env.AWS_SANDBOX_DISK_GB) }
: {}),
};
}
interface LocalSandboxEnv {
image?: string;
dockerBin?: string;
cpus?: number;
memoryMb?: number;
coreContainer?: string;
defaultTimeoutSec?: number;
}
function localSandboxEnv(env: NodeJS.ProcessEnv): LocalSandboxEnv {
return {
...(env.LOCAL_SANDBOX_IMAGE ? { image: env.LOCAL_SANDBOX_IMAGE } : {}),
...(env.LOCAL_SANDBOX_DOCKER_BIN ? { dockerBin: env.LOCAL_SANDBOX_DOCKER_BIN } : {}),
...(numEnvStrict("LOCAL_SANDBOX_CPUS", env.LOCAL_SANDBOX_CPUS) !== undefined
? { cpus: numEnvStrict("LOCAL_SANDBOX_CPUS", env.LOCAL_SANDBOX_CPUS) }
: {}),
...(numEnvStrict("LOCAL_SANDBOX_MEMORY_MB", env.LOCAL_SANDBOX_MEMORY_MB) !== undefined
? { memoryMb: numEnvStrict("LOCAL_SANDBOX_MEMORY_MB", env.LOCAL_SANDBOX_MEMORY_MB) }
: {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
};
}
interface SpritesSandboxEnv {
token?: string;
baseUrl?: string;
namePrefix?: string;
egressProxyUrl?: string;
egressProxyAdditionalUrls?: string[];
snapshotS3Bucket?: string;
memoryMb?: number;
defaultTimeoutSec?: number;
}
function spritesSandboxEnv(env: NodeJS.ProcessEnv): SpritesSandboxEnv {
return {
...(env.SPRITES_TOKEN ? { token: env.SPRITES_TOKEN } : {}),
...(env.SPRITES_BASE_URL ? { baseUrl: env.SPRITES_BASE_URL } : {}),
...(env.SPRITES_NAME_PREFIX ? { namePrefix: env.SPRITES_NAME_PREFIX } : {}),
...(env.SPRITES_EGRESS_PROXY_URL ? { egressProxyUrl: env.SPRITES_EGRESS_PROXY_URL } : {}),
...(env.SPRITES_EGRESS_PROXY_ADDITIONAL_URLS?.trim()
? {
egressProxyAdditionalUrls: env.SPRITES_EGRESS_PROXY_ADDITIONAL_URLS.split(",")
.map((url) => url.trim())
.filter(Boolean),
}
: {}),
...(env.SPRITES_SNAPSHOT_S3_BUCKET ? { snapshotS3Bucket: env.SPRITES_SNAPSHOT_S3_BUCKET } : {}),
...(numEnvStrict("SPRITES_MEMORY_MB", env.SPRITES_MEMORY_MB) !== undefined
? { memoryMb: numEnvStrict("SPRITES_MEMORY_MB", env.SPRITES_MEMORY_MB) }
: {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
};
}
interface E2bSandboxEnv {
apiKey?: string;
templateId?: string;
namePrefix?: string;
sandboxTtlSec?: number;
proxy?: string;
egressProxyUrl?: string;
snapshotS3Bucket?: string;
snapshotIntervalSec?: number;
nativeSnapshotIntervalSec?: number;
maxLifetimeSec?: number;
defaultTimeoutSec?: number;
}
function e2bSandboxEnv(env: NodeJS.ProcessEnv): E2bSandboxEnv {
return {
...(env.E2B_API_KEY ? { apiKey: env.E2B_API_KEY } : {}),
...(env.E2B_TEMPLATE_ID ? { templateId: env.E2B_TEMPLATE_ID } : {}),
...(env.E2B_NAME_PREFIX ? { namePrefix: env.E2B_NAME_PREFIX } : {}),
...(numEnvStrict("E2B_SANDBOX_TTL_SEC", env.E2B_SANDBOX_TTL_SEC) !== undefined
? { sandboxTtlSec: numEnvStrict("E2B_SANDBOX_TTL_SEC", env.E2B_SANDBOX_TTL_SEC) }
: {}),
...(numEnvStrict("E2B_MAX_LIFETIME_SEC", env.E2B_MAX_LIFETIME_SEC) !== undefined
? { maxLifetimeSec: numEnvStrict("E2B_MAX_LIFETIME_SEC", env.E2B_MAX_LIFETIME_SEC) }
: {}),
...(env.E2B_PROXY ? { proxy: env.E2B_PROXY } : {}),
...(env.E2B_EGRESS_PROXY_URL ? { egressProxyUrl: env.E2B_EGRESS_PROXY_URL } : {}),
...(env.E2B_SNAPSHOT_S3_BUCKET ? { snapshotS3Bucket: env.E2B_SNAPSHOT_S3_BUCKET } : {}),
...(numEnvStrict("E2B_SNAPSHOT_INTERVAL_SEC", env.E2B_SNAPSHOT_INTERVAL_SEC) !== undefined
? { snapshotIntervalSec: numEnvStrict("E2B_SNAPSHOT_INTERVAL_SEC", env.E2B_SNAPSHOT_INTERVAL_SEC) }
: {}),
...(numEnvStrict("E2B_NATIVE_SNAPSHOT_INTERVAL_SEC", env.E2B_NATIVE_SNAPSHOT_INTERVAL_SEC) !== undefined
? {
nativeSnapshotIntervalSec: numEnvStrict(
"E2B_NATIVE_SNAPSHOT_INTERVAL_SEC",
env.E2B_NATIVE_SNAPSHOT_INTERVAL_SEC,
),
}
: {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
};
}
interface ManagedAgentsSandboxEnv {
apiToken?: string;
apiBaseUrl?: string;
template?: string;
namePrefix?: string;
sizeSlug?: string;
idleTimeoutSec?: number;
egressProxyUrl?: string;
snapshotS3Bucket?: string;
snapshotIntervalSec?: number;
defaultTimeoutSec?: number;
}
function managedAgentsSandboxEnv(env: NodeJS.ProcessEnv): ManagedAgentsSandboxEnv {
return {
...(env.DO_AGENTS_API_TOKEN ? { apiToken: env.DO_AGENTS_API_TOKEN } : {}),
...(env.DO_AGENTS_API_BASE_URL ? { apiBaseUrl: env.DO_AGENTS_API_BASE_URL } : {}),
...(env.DO_AGENTS_TEMPLATE ? { template: env.DO_AGENTS_TEMPLATE } : {}),
...(env.DO_AGENTS_NAME_PREFIX ? { namePrefix: env.DO_AGENTS_NAME_PREFIX } : {}),
...(env.DO_AGENTS_SIZE_SLUG ? { sizeSlug: env.DO_AGENTS_SIZE_SLUG } : {}),
...(numEnvStrict("DO_AGENTS_IDLE_TIMEOUT_SEC", env.DO_AGENTS_IDLE_TIMEOUT_SEC) !== undefined
? { idleTimeoutSec: numEnvStrict("DO_AGENTS_IDLE_TIMEOUT_SEC", env.DO_AGENTS_IDLE_TIMEOUT_SEC) }
: {}),
...(env.DO_AGENTS_EGRESS_PROXY_URL ? { egressProxyUrl: env.DO_AGENTS_EGRESS_PROXY_URL } : {}),
...(env.DO_AGENTS_SNAPSHOT_S3_BUCKET ? { snapshotS3Bucket: env.DO_AGENTS_SNAPSHOT_S3_BUCKET } : {}),
...(numEnvStrict("DO_AGENTS_SNAPSHOT_INTERVAL_SEC", env.DO_AGENTS_SNAPSHOT_INTERVAL_SEC) !== undefined
? { snapshotIntervalSec: numEnvStrict("DO_AGENTS_SNAPSHOT_INTERVAL_SEC", env.DO_AGENTS_SNAPSHOT_INTERVAL_SEC) }
: {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
};
}
interface ModalSandboxEnv {
nativeSnapshotsEnabled?: boolean;
nativeSnapshotIntervalSec?: number;
snapshotRetentionSec?: number;
tokenId?: string;
tokenSecret?: string;
appName?: string;
environment?: string;
image?: string;
namePrefix?: string;
cpus?: number;
memoryMb?: number;
regions?: string[];
sandboxTimeoutSec?: number;
rotateAfterSec?: number;
reapIdleSec?: number;
egressProxyUrl?: string;
snapshotS3Bucket?: string;
snapshotIntervalSec?: number;
defaultTimeoutSec?: number;
}
function modalSandboxEnv(env: NodeJS.ProcessEnv): ModalSandboxEnv {
const num = (name: string): number | undefined => numEnvStrict(name, env[name]);
return {
nativeSnapshotsEnabled:
boolEnvStrict("MODAL_NATIVE_SNAPSHOTS_ENABLED", env.MODAL_NATIVE_SNAPSHOTS_ENABLED) ?? false,
...(num("MODAL_NATIVE_SNAPSHOT_INTERVAL_SEC") !== undefined
? { nativeSnapshotIntervalSec: num("MODAL_NATIVE_SNAPSHOT_INTERVAL_SEC") }
: {}),
...(num("MODAL_SNAPSHOT_RETENTION_SEC") !== undefined
? { snapshotRetentionSec: num("MODAL_SNAPSHOT_RETENTION_SEC") }
: {}),
...(env.MODAL_TOKEN_ID ? { tokenId: env.MODAL_TOKEN_ID } : {}),
...(env.MODAL_TOKEN_SECRET ? { tokenSecret: env.MODAL_TOKEN_SECRET } : {}),
...(env.MODAL_APP_NAME ? { appName: env.MODAL_APP_NAME } : {}),
...(env.MODAL_ENVIRONMENT ? { environment: env.MODAL_ENVIRONMENT } : {}),
...(env.MODAL_IMAGE ? { image: env.MODAL_IMAGE } : {}),
...(env.MODAL_NAME_PREFIX ? { namePrefix: env.MODAL_NAME_PREFIX } : {}),
...(num("MODAL_CPUS") !== undefined ? { cpus: num("MODAL_CPUS") } : {}),
...(num("MODAL_MEMORY_MB") !== undefined ? { memoryMb: num("MODAL_MEMORY_MB") } : {}),
...(env.MODAL_REGIONS?.trim()
? {
regions: env.MODAL_REGIONS.split(",")
.map((r) => r.trim())
.filter(Boolean),
}
: {}),
...(num("MODAL_SANDBOX_TIMEOUT_SEC") !== undefined ? { sandboxTimeoutSec: num("MODAL_SANDBOX_TIMEOUT_SEC") } : {}),
...(num("MODAL_ROTATE_AFTER_SEC") !== undefined ? { rotateAfterSec: num("MODAL_ROTATE_AFTER_SEC") } : {}),
...(num("MODAL_REAP_IDLE_SEC") !== undefined ? { reapIdleSec: num("MODAL_REAP_IDLE_SEC") } : {}),
...(env.MODAL_EGRESS_PROXY_URL ? { egressProxyUrl: env.MODAL_EGRESS_PROXY_URL } : {}),
...(env.MODAL_SNAPSHOT_S3_BUCKET ? { snapshotS3Bucket: env.MODAL_SNAPSHOT_S3_BUCKET } : {}),
...(num("MODAL_SNAPSHOT_INTERVAL_SEC") !== undefined
? { snapshotIntervalSec: num("MODAL_SNAPSHOT_INTERVAL_SEC") }
: {}),
...(num("SANDBOX_TIMEOUT_SEC") !== undefined ? { defaultTimeoutSec: num("SANDBOX_TIMEOUT_SEC") } : {}),
};
}
interface SmolmachinesSandboxEnv {
token?: string;
baseUrl?: string;
namePrefix?: string;
image?: string;
cpus?: number;
memoryMb?: number;
diskGb?: number;
autoStopSec?: number;
egressProxyUrl?: string;
snapshotS3Bucket?: string;
snapshotIntervalSec?: number;
defaultTimeoutSec?: number;
}
function smolmachinesSandboxEnv(env: NodeJS.ProcessEnv): SmolmachinesSandboxEnv {
return {
...(env.SMOLMACHINES_TOKEN ? { token: env.SMOLMACHINES_TOKEN } : {}),
...(env.SMOLMACHINES_BASE_URL ? { baseUrl: env.SMOLMACHINES_BASE_URL } : {}),
...(env.SMOLMACHINES_NAME_PREFIX ? { namePrefix: env.SMOLMACHINES_NAME_PREFIX } : {}),
...(env.SMOLMACHINES_IMAGE ? { image: env.SMOLMACHINES_IMAGE } : {}),
...(numEnvStrict("SMOLMACHINES_CPUS", env.SMOLMACHINES_CPUS) !== undefined
? { cpus: numEnvStrict("SMOLMACHINES_CPUS", env.SMOLMACHINES_CPUS) }
: {}),
...(numEnvStrict("SMOLMACHINES_MEMORY_MB", env.SMOLMACHINES_MEMORY_MB) !== undefined
? { memoryMb: numEnvStrict("SMOLMACHINES_MEMORY_MB", env.SMOLMACHINES_MEMORY_MB) }
: {}),
...(numEnvStrict("SMOLMACHINES_DISK_GB", env.SMOLMACHINES_DISK_GB) !== undefined
? { diskGb: numEnvStrict("SMOLMACHINES_DISK_GB", env.SMOLMACHINES_DISK_GB) }
: {}),
...(numEnvStrict("SMOLMACHINES_AUTOSTOP_SEC", env.SMOLMACHINES_AUTOSTOP_SEC) !== undefined
? { autoStopSec: numEnvStrict("SMOLMACHINES_AUTOSTOP_SEC", env.SMOLMACHINES_AUTOSTOP_SEC) }
: {}),
...(env.SMOLMACHINES_EGRESS_PROXY_URL ? { egressProxyUrl: env.SMOLMACHINES_EGRESS_PROXY_URL } : {}),
...(env.SMOLMACHINES_SNAPSHOT_S3_BUCKET ? { snapshotS3Bucket: env.SMOLMACHINES_SNAPSHOT_S3_BUCKET } : {}),
...(numEnvStrict("SMOLMACHINES_SNAPSHOT_INTERVAL_SEC", env.SMOLMACHINES_SNAPSHOT_INTERVAL_SEC) !== undefined
? {
snapshotIntervalSec: numEnvStrict(
"SMOLMACHINES_SNAPSHOT_INTERVAL_SEC",
env.SMOLMACHINES_SNAPSHOT_INTERVAL_SEC,
),
}
: {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
};
}
interface PorterSandboxEnv {
image?: string;
token?: string;
baseUrl?: string;
namePrefix?: string;
homeDir?: string;
ttlSec?: number;
egressProxyUrl?: string;
defaultTimeoutSec?: number;
}
interface PorterDeployEnv {
token?: string;
baseUrl?: string;
runnerImage?: string;
appsDomain?: string;
visibility?: "public" | "private" | "internal";
namePrefix?: string;
ttlSec?: number;
}
function porterApiBaseUrl(env: NodeJS.ProcessEnv): string | undefined {
const deployProjectId = numEnvStrict("PORTER_DEPLOY_PROJECT_ID", env.PORTER_DEPLOY_PROJECT_ID);
const deployClusterId = numEnvStrict("PORTER_DEPLOY_CLUSTER_ID", env.PORTER_DEPLOY_CLUSTER_ID);
const derived =
deployProjectId !== undefined && deployClusterId !== undefined
? `${(env.PORTER_DEPLOY_URL ?? "https://dashboard.porter.run").replace(/\/+$/, "")}/api/v2/alpha/projects/${deployProjectId}/clusters/${deployClusterId}`
: undefined;
return env.PORTER_SANDBOX_BASE_URL ?? derived;
}
const porterLocatorPresent = (env: NodeJS.ProcessEnv): boolean =>
Boolean(porterApiBaseUrl(env) || env.PORTER_CLUSTER_ID || env.KUBERNETES_SERVICE_HOST);
function porterDeployVisibilityStrict(value: string | undefined): PorterDeployEnv["visibility"] {
if (value === undefined || value.trim() === "") return undefined;
const visibility = value.trim();
if (visibility === "public" || visibility === "private" || visibility === "internal") return visibility;
throw new Error(
`PORTER_DEPLOY_VISIBILITY=${JSON.stringify(value)} is not recognized — use public, private, or internal, or unset it.`,
);
}
function porterDeployEnv(env: NodeJS.ProcessEnv): PorterDeployEnv {
const token = env.PORTER_DEPLOY_API_TOKEN;
const baseUrl = porterApiBaseUrl(env);
const visibility = porterDeployVisibilityStrict(env.PORTER_DEPLOY_VISIBILITY);
if (visibility === "internal" && env.PORTER_DEPLOY_APPS_DOMAIN) {
throw new Error(
"PORTER_DEPLOY_VISIBILITY=internal serves apps inside the cluster only, so it takes no PORTER_DEPLOY_APPS_DOMAIN — unset one of them.",
);
}
const ttlSec = numEnvStrict("PORTER_DEPLOY_TTL_SEC", env.PORTER_DEPLOY_TTL_SEC);
const runnerImage = env.PORTER_DEPLOY_RUNNER_IMAGE ?? env.PORTER_SANDBOX_IMAGE;
return {
...(token ? { token } : {}),
...(baseUrl ? { baseUrl } : {}),
...(runnerImage ? { runnerImage } : {}),
...(env.PORTER_DEPLOY_APPS_DOMAIN ? { appsDomain: env.PORTER_DEPLOY_APPS_DOMAIN } : {}),
...(visibility ? { visibility } : {}),
...(env.PORTER_SANDBOX_NAME_PREFIX ? { namePrefix: env.PORTER_SANDBOX_NAME_PREFIX } : {}),
...(ttlSec !== undefined ? { ttlSec } : {}),
};
}
function porterSandboxEnv(env: NodeJS.ProcessEnv): PorterSandboxEnv {
const token = env.PORTER_DEPLOY_API_TOKEN;
const baseUrl = porterApiBaseUrl(env);
const ttlSec = numEnvStrict("PORTER_SANDBOX_TTL_SEC", env.PORTER_SANDBOX_TTL_SEC);
return {
...(env.PORTER_SANDBOX_IMAGE ? { image: env.PORTER_SANDBOX_IMAGE } : {}),
...(token ? { token } : {}),
...(baseUrl ? { baseUrl } : {}),
...(env.PORTER_SANDBOX_NAME_PREFIX ? { namePrefix: env.PORTER_SANDBOX_NAME_PREFIX } : {}),
...(env.PORTER_SANDBOX_HOME ? { homeDir: env.PORTER_SANDBOX_HOME } : {}),
...(ttlSec !== undefined ? { ttlSec } : {}),
...(env.PORTER_SANDBOX_EGRESS_PROXY_URL ? { egressProxyUrl: env.PORTER_SANDBOX_EGRESS_PROXY_URL } : {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
};
}
interface Agent37SandboxEnv {
apiKey?: string;
baseUrl?: string;
namePrefix?: string;
template?: string;
cpus?: number;
memoryGb?: number;
diskGb?: number;
egressProxyUrl?: string;
defaultTimeoutSec?: number;
}
function agent37SandboxEnv(env: NodeJS.ProcessEnv): Agent37SandboxEnv {
return {
...(env.AGENT37_API_KEY ? { apiKey: env.AGENT37_API_KEY } : {}),
...(env.AGENT37_API_BASE_URL ? { baseUrl: env.AGENT37_API_BASE_URL } : {}),
...(env.AGENT37_NAME_PREFIX ? { namePrefix: env.AGENT37_NAME_PREFIX } : {}),
...(env.AGENT37_TEMPLATE ? { template: env.AGENT37_TEMPLATE } : {}),
...(numEnvStrict("AGENT37_CPUS", env.AGENT37_CPUS) !== undefined
? { cpus: numEnvStrict("AGENT37_CPUS", env.AGENT37_CPUS) }
: {}),
...(numEnvStrict("AGENT37_MEMORY_GB", env.AGENT37_MEMORY_GB) !== undefined
? { memoryGb: numEnvStrict("AGENT37_MEMORY_GB", env.AGENT37_MEMORY_GB) }
: {}),
...(numEnvStrict("AGENT37_DISK_GB", env.AGENT37_DISK_GB) !== undefined
? { diskGb: numEnvStrict("AGENT37_DISK_GB", env.AGENT37_DISK_GB) }
: {}),
...(env.AGENT37_EGRESS_PROXY_URL ? { egressProxyUrl: env.AGENT37_EGRESS_PROXY_URL } : {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
};
}
interface SuperserveSandboxEnv {
apiKey?: string;
baseUrl?: string;
namePrefix?: string;
template?: string;
homeDir?: string;
idlePauseSec?: number;
retentionSec?: number;
egressAllow?: string[];
egressDeny?: string[];
defaultTimeoutSec?: number;
configGeneration?: number;
}
const csvList = (value: string | undefined): string[] | undefined => {
const items = (value ?? "")
.split(",")
.map((s) => s.trim())
.filter(Boolean);
return items.length ? items : undefined;
};
function superserveSandboxEnv(env: NodeJS.ProcessEnv): SuperserveSandboxEnv {
const egressAllow = csvList(env.SUPERSERVE_EGRESS_ALLOW);
const egressDeny = csvList(env.SUPERSERVE_EGRESS_DENY);
const configGeneration = numEnvStrict("SUPERSERVE_CONFIG_GENERATION", env.SUPERSERVE_CONFIG_GENERATION);
if (configGeneration !== undefined && (!Number.isSafeInteger(configGeneration) || configGeneration < 0)) {
throw new Error(
`SUPERSERVE_CONFIG_GENERATION=${JSON.stringify(env.SUPERSERVE_CONFIG_GENERATION)} must be a nonnegative safe integer, or unset it.`,
);
}
return {
...(env.SUPERSERVE_API_KEY ? { apiKey: env.SUPERSERVE_API_KEY } : {}),
...(env.SUPERSERVE_BASE_URL?.trim() ? { baseUrl: env.SUPERSERVE_BASE_URL.trim() } : {}),
...(env.SUPERSERVE_NAME_PREFIX ? { namePrefix: env.SUPERSERVE_NAME_PREFIX } : {}),
...(env.SUPERSERVE_TEMPLATE?.trim() ? { template: env.SUPERSERVE_TEMPLATE.trim() } : {}),
...(env.SUPERSERVE_HOME_DIR ? { homeDir: env.SUPERSERVE_HOME_DIR } : {}),
...(numEnvStrict("SUPERSERVE_IDLE_PAUSE_SEC", env.SUPERSERVE_IDLE_PAUSE_SEC) !== undefined
? { idlePauseSec: numEnvStrict("SUPERSERVE_IDLE_PAUSE_SEC", env.SUPERSERVE_IDLE_PAUSE_SEC) }
: {}),
...(numEnvStrict("SUPERSERVE_RETENTION_SEC", env.SUPERSERVE_RETENTION_SEC) !== undefined
? { retentionSec: numEnvStrict("SUPERSERVE_RETENTION_SEC", env.SUPERSERVE_RETENTION_SEC) }
: {}),
...(egressAllow ? { egressAllow } : {}),
...(egressDeny ? { egressDeny } : {}),
...(numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) !== undefined
? { defaultTimeoutSec: numEnvStrict("SANDBOX_TIMEOUT_SEC", env.SANDBOX_TIMEOUT_SEC) }
: {}),
...(configGeneration !== undefined ? { configGeneration } : {}),
};
}
interface AwsDeployEnv {
region: string;
profile?: string;
imageIdentifier: string;
imageVersion?: string;
executionRoleArn?: string;
ingressConnectorArns?: string[];
egressConnectorArns?: string[];
agentPort?: number;
appPort?: number;
maximumDurationInSeconds?: number;
rotateAfterSeconds?: number;
maxIdleDurationSeconds?: number;
suspendedDurationSeconds?: number;
appsDomain?: string;
gateSecret?: string;
tokenTtlMinutes?: number;
dataBucket?: string;
dataPrefix?: string;
snapshotIntervalMs?: number;
dataRoleArn?: string;
}
function deployAppsEnv(
env: NodeJS.ProcessEnv,
defaultLoginUrl: string | undefined,
): {
deployAppsSessionSecret?: string;
deployAppsLoginUrl?: string;
deployAppsLoginPath?: "/auth/login" | "/auth/trusted/login";
} {
const explicit = env.DEPLOY_APPS_SESSION_SECRET;
const shared = env.PORTAL_SESSION_SECRET;
const loginUrl = env.DEPLOY_APPS_LOGIN_URL ?? (explicit || shared ? defaultLoginUrl : undefined);
if (loginUrl && !explicit && !shared) {
throw new Error("DEPLOY_APPS_LOGIN_URL requires DEPLOY_APPS_SESSION_SECRET");
}
if (explicit && !loginUrl) {
throw new Error("DEPLOY_APPS_SESSION_SECRET needs a sign-in address — set DEPLOY_APPS_LOGIN_URL or PUBLIC_WEB_URL");
}
const secret = explicit ?? (loginUrl ? shared : undefined);
const loginPath = env.DEPLOY_APPS_LOGIN_PATH ?? "/auth/login";
if (loginPath !== "/auth/login" && loginPath !== "/auth/trusted/login") {
throw new Error("DEPLOY_APPS_LOGIN_PATH must be /auth/login or /auth/trusted/login");
}
if (!secret || !loginUrl) return {};
return {
deployAppsSessionSecret: secret,
deployAppsLoginUrl: loginUrl.replace(/\/$/, ""),
deployAppsLoginPath: loginPath,
};
}
const SHARED_PLATFORM_SUFFIXES = [
"onporter.run",
"withporter.run",
"porter.run",
"fly.dev",
"herokuapp.com",
"onrender.com",
"railway.app",
"vercel.app",
"netlify.app",
"ondigitalocean.app",
"azurewebsites.net",
"elasticbeanstalk.com",
"amazonaws.com",
"cloudfront.net",
"github.io",
"pages.dev",
"workers.dev",
"e2b.app",
];
function sharedPlatformSuffixOf(domain: string): string | undefined {
const host = domain.toLowerCase();
return SHARED_PLATFORM_SUFFIXES.find((suffix) => host === suffix || host.endsWith(`.${suffix}`));
}
const HOSTNAME_LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
const HOSTNAME_RE = new RegExp(`^${HOSTNAME_LABEL}(?:\\.${HOSTNAME_LABEL})+$`);
function deployAppsDomainEnv(env: NodeJS.ProcessEnv, deployProvider: string): string | undefined {
const raw = env.DEPLOY_APPS_DOMAIN?.trim();
if (raw) {
const canonical = raw.toLowerCase().replace(/\.$/, "");
if (!HOSTNAME_RE.test(canonical)) {
throw new Error(
`DEPLOY_APPS_DOMAIN (${raw}) is not a plain DNS name — set it to a bare domain like apps.example.com (no scheme, port, path, or wildcard prefix).`,
);
}
const suffix = sharedPlatformSuffixOf(canonical);
if (suffix) {
throw new Error(
`DEPLOY_APPS_DOMAIN (${canonical}) is under ${suffix}, a shared platform domain that cannot carry per-app subdomains — attach a custom domain you control (set DEPLOY_APPS_DOMAIN=apps.<your-domain> with a wildcard DNS record pointing at this instance), or unset it to keep serving apps signed-in at /d/<app>/.`,
);
}
return canonical;
}
if (deployProvider === "porter" && env.PORTER_DEPLOY_APPS_DOMAIN) return env.PORTER_DEPLOY_APPS_DOMAIN;
return env.AWS_DEPLOY_APPS_DOMAIN;
}
function awsDeployEnv(env: NodeJS.ProcessEnv): AwsDeployEnv {
const csv = (s: string | undefined): string[] | undefined =>
s
? s
.split(",")
.map((x) => x.trim())
.filter(Boolean)
: undefined;
const ingress = csv(env.AWS_DEPLOY_INGRESS_CONNECTORS);
const egress = csv(env.AWS_DEPLOY_EGRESS_CONNECTORS);
return {
region: env.AWS_DEPLOY_REGION ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION ?? "us-west-2",
...(env.AWS_DEPLOY_PROFILE ? { profile: env.AWS_DEPLOY_PROFILE } : {}),
imageIdentifier: env.AWS_DEPLOY_IMAGE ?? "qm-microvm-sandbox",
...(env.AWS_DEPLOY_IMAGE_VERSION ? { imageVersion: env.AWS_DEPLOY_IMAGE_VERSION } : {}),
...(env.AWS_DEPLOY_EXEC_ROLE_ARN ? { executionRoleArn: env.AWS_DEPLOY_EXEC_ROLE_ARN } : {}),
...(ingress ? { ingressConnectorArns: ingress } : {}),
...(egress ? { egressConnectorArns: egress } : {}),
...(numEnvStrict("AWS_DEPLOY_AGENT_PORT", env.AWS_DEPLOY_AGENT_PORT) !== undefined
? { agentPort: numEnvStrict("AWS_DEPLOY_AGENT_PORT", env.AWS_DEPLOY_AGENT_PORT) }
: {}),
...(numEnvStrict("AWS_DEPLOY_APP_PORT", env.AWS_DEPLOY_APP_PORT) !== undefined
? { appPort: numEnvStrict("AWS_DEPLOY_APP_PORT", env.AWS_DEPLOY_APP_PORT) }
: {}),
...(numEnvStrict("AWS_DEPLOY_MAX_DURATION_SEC", env.AWS_DEPLOY_MAX_DURATION_SEC) !== undefined
? { maximumDurationInSeconds: numEnvStrict("AWS_DEPLOY_MAX_DURATION_SEC", env.AWS_DEPLOY_MAX_DURATION_SEC) }
: {}),
...(numEnvStrict("AWS_DEPLOY_ROTATE_AFTER_SEC", env.AWS_DEPLOY_ROTATE_AFTER_SEC) !== undefined
? { rotateAfterSeconds: numEnvStrict("AWS_DEPLOY_ROTATE_AFTER_SEC", env.AWS_DEPLOY_ROTATE_AFTER_SEC) }
: {}),
...(numEnvStrict("AWS_DEPLOY_MAX_IDLE_SEC", env.AWS_DEPLOY_MAX_IDLE_SEC) !== undefined
? { maxIdleDurationSeconds: numEnvStrict("AWS_DEPLOY_MAX_IDLE_SEC", env.AWS_DEPLOY_MAX_IDLE_SEC) }
: {}),
...(numEnvStrict("AWS_DEPLOY_SUSPENDED_SEC", env.AWS_DEPLOY_SUSPENDED_SEC) !== undefined
? { suspendedDurationSeconds: numEnvStrict("AWS_DEPLOY_SUSPENDED_SEC", env.AWS_DEPLOY_SUSPENDED_SEC) }
: {}),
...(env.AWS_DEPLOY_APPS_DOMAIN ? { appsDomain: env.AWS_DEPLOY_APPS_DOMAIN } : {}),
...(env.AWS_DEPLOY_GATE_SECRET ? { gateSecret: env.AWS_DEPLOY_GATE_SECRET } : {}),
...(numEnvStrict("AWS_DEPLOY_TOKEN_TTL_MIN", env.AWS_DEPLOY_TOKEN_TTL_MIN) !== undefined
? { tokenTtlMinutes: numEnvStrict("AWS_DEPLOY_TOKEN_TTL_MIN", env.AWS_DEPLOY_TOKEN_TTL_MIN) }
: {}),
...(env.AWS_DEPLOY_DATA_BUCKET ? { dataBucket: env.AWS_DEPLOY_DATA_BUCKET } : {}),
...(env.AWS_DEPLOY_DATA_PREFIX ? { dataPrefix: env.AWS_DEPLOY_DATA_PREFIX } : {}),
...(env.AWS_DEPLOY_DATA_ROLE_ARN ? { dataRoleArn: env.AWS_DEPLOY_DATA_ROLE_ARN } : {}),
...(numEnvStrict("AWS_DEPLOY_SNAPSHOT_INTERVAL_MS", env.AWS_DEPLOY_SNAPSHOT_INTERVAL_MS) !== undefined
? {
snapshotIntervalMs: Math.max(
60_000,
numEnvStrict("AWS_DEPLOY_SNAPSHOT_INTERVAL_MS", env.AWS_DEPLOY_SNAPSHOT_INTERVAL_MS)!,
),
}
: {}),
};
}
interface FlyDeployEnv {
token: string;
appPrefix: string;
sharedAppName?: string;
wireguardPeers?: string;
metadataUri?: string;
baseImage: string;
org: string;
region?: string;
dataVolumeSizeGb?: number;
}
function flyDeployEnv(env: NodeJS.ProcessEnv): FlyDeployEnv {
return {
token: env.FLY_DEPLOY_API_TOKEN ?? "",
appPrefix: env.FLY_DEPLOY_APP_PREFIX ?? "",
...(env.FLY_DEPLOY_SHARED_APP_NAME ? { sharedAppName: env.FLY_DEPLOY_SHARED_APP_NAME } : {}),
...(env.FLY_DEPLOY_WIREGUARD_PEERS ? { wireguardPeers: env.FLY_DEPLOY_WIREGUARD_PEERS } : {}),
...(env.ECS_CONTAINER_METADATA_URI_V4 ? { metadataUri: env.ECS_CONTAINER_METADATA_URI_V4 } : {}),
baseImage: env.FLY_DEPLOY_BASE_IMAGE ?? "",
org: env.FLY_ORG ?? "",
...(env.FLY_REGION ? { region: env.FLY_REGION } : {}),
...(env.FLY_DEPLOY_DATA_VOLUME_SIZE_GB !== undefined
? { dataVolumeSizeGb: Number(env.FLY_DEPLOY_DATA_VOLUME_SIZE_GB) }
: {}),
};
}
const DEFAULT_ORG_ID = "default-org";
export function orgId(): string {
return process.env.ORG_ID ?? DEFAULT_ORG_ID;
}
export function orgScope(): string {
return `org:${orgId()}`;
}
export const CONFIG_DEFAULTS = {
port: 8080,
rateLimitPerWindow: 60,
rateLimitWindowMs: 60_000,
budgetWindowMs: 86_400_000,
execTimeoutDefaultSec: 120,
execTimeoutMaxSec: 300,
turnWallClockSec: 0,
runMaxAgeMs: 24 * 60 * 60_000,
backgroundJobTtlSec: 1800,
backgroundJobTtlMaxSec: 3600,
backgroundWorkEnabled: true,
monitorPollMs: 10_000,
skillSyncPollMs: 0,
deployDialTimeoutMs: 20_000,
deepIdleMachineMs: 3 * 24 * 60 * 60_000,
devIdleMachineMs: 2 * 60 * 60_000,
cronFireConcurrency: 4,
monitorHeartbeatSec: 180,
approvalSummaryTimeoutMs: 6_000,
turnLeaseWaitMs: 5_000,
securityScreenTimeoutMs: 15_000,
workers: 16,
leaseTtlMs: 120_000,
heartbeatIntervalMs: 10_000,
reaperIntervalMs: 15_000,
shutdownDrainMs: 30_000,
maxAttempts: 3,
maxClaims: 8,
processReaperIntervalMs: 30_000,
} as const;
export function boolEnv(value: string | undefined): boolean | undefined {
if (value === undefined) return undefined;
const v = value.trim().toLowerCase();
if (["1", "true", "yes", "on"].includes(v)) return true;
if (["0", "false", "no", "off", "none"].includes(v)) return false;
return undefined;
}
export function numEnv(value: string | undefined): number | undefined {
if (value === undefined || value.trim() === "") return undefined;
const n = Number(value);
return Number.isFinite(n) ? n : undefined;
}
function boolEnvStrict(name: string, value: string | undefined): boolean | undefined {
if (value === undefined || value.trim() === "") return undefined;
const parsed = boolEnv(value);
if (parsed === undefined) {
throw new Error(
`${name}=${JSON.stringify(value)} is not a recognized boolean — use 1/true/yes/on or 0/false/no/off/none (case-insensitive), or unset it.`,
);
}
return parsed;
}
function numEnvStrict(name: string, value: string | undefined): number | undefined {
if (value === undefined || value.trim() === "") return undefined;
const parsed = numEnv(value);
if (parsed === undefined) {
throw new Error(`${name}=${JSON.stringify(value)} is not a number — set a finite numeric value, or unset it.`);
}
return parsed;
}
function orgBrandingFromEnv(env: NodeJS.ProcessEnv): Config["brandingDefault"] {
return sanitizeBranding({
accent: env.ORG_BRAND_ACCENT,
mark: env.ORG_BRAND_MARK,
selfLabel: env.ORG_BRAND_SELF_LABEL,
orgName: env.ORG_BRAND_ORG_NAME,
});
}
function harnessEnvStrict(value: string | undefined): Config["harness"] {
if (value === undefined || value.trim() === "") return "pi";
const harness = value.trim();
if (harness === "pi" || harness === "claude") return harness;
throw new Error(`HARNESS=${JSON.stringify(value)} is not recognized — use pi or claude, or unset it.`);
}
export function enabledSandboxBackends(config: Config): Array<Config["sandboxBackend"]> {
const credentialed: Record<Config["sandboxBackend"], boolean> = {
local: Boolean(config.localSandbox?.image),
sprites: Boolean(config.spritesSandbox?.token),
smolmachines: Boolean(config.smolmachinesSandbox?.token),
agent37: Boolean(config.agent37Sandbox?.apiKey),
superserve: Boolean(config.superserveSandbox?.apiKey && config.superserveSandbox?.template),
e2b: Boolean(config.e2bSandbox?.apiKey),
"do-managed-agents": Boolean(config.managedAgentsSandbox?.apiToken),
modal: Boolean(config.modalSandbox?.tokenId && config.modalSandbox?.tokenSecret),
aws: Boolean(config.awsSandbox?.s3Bucket),
porter: Boolean(config.porterSandbox?.token),
};
const enabled = new Set<Config["sandboxBackend"]>([config.sandboxBackend]);
for (const [name, on] of Object.entries(credentialed)) {
if (on) enabled.add(name as Config["sandboxBackend"]);
}
return [...enabled];
}
function sandboxBackendEnvStrict(value: string | undefined, name = "SANDBOX_BACKEND"): Config["sandboxBackend"] {
if (value === undefined || value.trim() === "") return "local";
const backend = value.trim();
if (
backend === "aws" ||
backend === "local" ||
backend === "sprites" ||
backend === "smolmachines" ||
backend === "e2b" ||
backend === "modal" ||
backend === "agent37" ||
backend === "superserve" ||
backend === "do-managed-agents" ||
backend === "porter"
)
return backend;
throw new Error(
`${name}=${JSON.stringify(value)} is not recognized — use aws, local, sprites, smolmachines, e2b, modal, porter, agent37, superserve, or do-managed-agents, or unset it.`,
);
}
function secretsBackendEnvStrict(value: string | undefined, prefix: string): Config["secretsBackend"] {
if (value === undefined || value.trim() === "") return "env";
const backend = value.trim();
if (backend === "env") return backend;
if (backend === "aws") {
if (!prefix)
throw new Error(
"SECRETS_BACKEND=aws requires a non-empty SECRETS_PREFIX (e.g. qm-prod-) so lookups can't collide across stacks sharing an account.",
);
return backend;
}
throw new Error(`SECRETS_BACKEND=${JSON.stringify(value)} is not recognized — use env or aws, or unset it.`);
}
function securityPostureEnvStrict(value: string | undefined): SecurityPosture {
if (value === undefined || value.trim() === "") return "auto";
const posture = parseSecurityPosture(value);
if (posture) return posture;
throw new Error(
`HARNESS_SECURITY_POSTURE=${JSON.stringify(value)} is not recognized — use dangerous, auto, or strict, or unset it.`,
);
}
function sharingPostureEnvStrict(value: string | undefined): SharingPosture {
if (value === undefined || value.trim() === "") return "isolated";
const posture = parseSharingPosture(value);
if (posture) return posture;
throw new Error(
`HARNESS_SHARING_POSTURE=${JSON.stringify(value)} is not recognized — use isolated or open, or unset it.`,
);
}
function choiceEnvStrict<T extends string>(name: string, value: string | undefined, choices: readonly T[]): T {
if (value === undefined || value.trim() === "") return choices[0]!;
const choice = value.trim().toLowerCase();
if ((choices as readonly string[]).includes(choice)) return choice as T;
throw new Error(`${name}=${JSON.stringify(value)} is not recognized — use ${choices.join(", ")}, or unset it.`);
}
const RETIRED_SECURITY_SCREEN_ENV = [
"SECURITY_SCREEN_BACKEND",
"SECURITY_SCREEN_ALL_POSTURES",
"SECURITY_SCREEN_PROXY_ROLLOUT",
] as const;
function csvPaths(value: string | undefined): string[] | undefined {
if (value === undefined) return undefined;
if (boolEnv(value) === false) return [];
return value
.split(",")
.map((s) => s.trim())
.filter(Boolean)
.map((p) => resolve(p));
}
function modelGatewayFromEnv(env: NodeJS.ProcessEnv): ModelGatewayTransportConfig | undefined {
const names = ["MODEL_GATEWAY_URL", "MODEL_GATEWAY_API_KEY", "MODEL_GATEWAY_API_KEY_HEADER", "MODEL_GATEWAY_MODELS"];
if (!names.some((name) => env[name]?.trim())) return undefined;
for (const name of names.filter((name) => name !== "MODEL_GATEWAY_MODELS")) {
if (!env[name]?.trim()) throw new Error(`${name} is required when model gateway routing is configured`);
}
const apiKeyHeader = env.MODEL_GATEWAY_API_KEY_HEADER!.trim();
if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(apiKeyHeader)) {
throw new Error("MODEL_GATEWAY_API_KEY_HEADER must be a valid HTTP header name");
}
const models: Record<string, string> = {};
for (const mapping of env.MODEL_GATEWAY_MODELS?.trim() ? env.MODEL_GATEWAY_MODELS.split(",") : []) {
const separator = mapping.indexOf("=");
const source = mapping.slice(0, separator).trim();
const target = mapping.slice(separator + 1).trim();
if (separator < 1 || !source || !target) throw new Error(`invalid MODEL_GATEWAY_MODELS mapping: ${mapping}`);
if (models[source]) throw new Error(`duplicate MODEL_GATEWAY_MODELS source: ${source}`);
models[source] = target;
}
return {
url: parseProviderBaseUrl("MODEL_GATEWAY_URL", env.MODEL_GATEWAY_URL!),
apiKey: env.MODEL_GATEWAY_API_KEY!,
apiKeyHeader,
models,
};
}
function defaultPluginSkillDirs(): string[] {
const root = resolve("./plugins");
try {
return readdirSync(root, { withFileTypes: true })
.filter((entry) => entry.isDirectory())
.map((entry) => join(root, entry.name, "skills"))
.filter((dir) => existsSync(dir));
} catch {
return [];
}
}
function modelProviderEnvStrict(env: NodeJS.ProcessEnv): ModelProvider | undefined {
const declared = env.MODEL_PROVIDER?.trim();
if (!declared) return undefined;
if (!isModelProvider(declared)) {
throw new Error(
`MODEL_PROVIDER=${JSON.stringify(declared)} is not recognized — use ${MODEL_PROVIDERS.join(", ")}.`,
);
}
const harness = harnessEnvStrict(env.HARNESS);
const base = defaultModelForProvider(harness, declared);
if (!base) {
throw new Error(
`MODEL_PROVIDER=${declared} cannot serve a base model on HARNESS=${harness} — that harness runs no ${declared} model, so every turn would be refused.`,
);
}
return declared;
}
function resolveStoreKinds(env: NodeJS.ProcessEnv): Pick<Config, "sessionStore" | "runStore"> {
for (const key of ["SESSION_STORE", "RUN_STORE", "ARTIFACT_STORE"] as const) {
if (env[key] === "sqlite") {
throw new Error(
`${key}=sqlite is no longer supported — SQLite was removed. ` +
`Set ${key === "ARTIFACT_STORE" ? "DATABASE_URL (Postgres)" : `${key}=postgres (with DATABASE_URL)`}.`,
);
}
}
const sessionStore = env.SESSION_STORE === "postgres" ? "postgres" : "memory";
const runStore = env.RUN_STORE === "memory" || env.RUN_STORE === "postgres" ? env.RUN_STORE : sessionStore;
if (env.NODE_ENV === "production" && (sessionStore === "memory" || runStore === "memory")) {
throw new Error(
`production requires SESSION_STORE=postgres and a Postgres run store (got SESSION_STORE=${env.SESSION_STORE ?? "unset"}, RUN_STORE=${env.RUN_STORE ?? "unset"}): in-memory sessions and runs are lost on restart and invisible to other instances.`,
);
}
return { sessionStore, runStore };
}
export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
const token = env.SPEND_EXPORT_TOKEN;
if (token) {
const reused = Object.entries(env).some(([name, value]) => name !== "SPEND_EXPORT_TOKEN" && value === token);
if (!isStrongSigningSecret(token) || !isBearerSecret(token) || reused)
throw new Error(
"SPEND_EXPORT_TOKEN must be at least 32 characters, have no surrounding whitespace and differ from every other environment value",
);
}
if (env.BACKGROUND_DEPLOYMENT_ID !== undefined) {
if (!env.BACKGROUND_DEPLOYMENT_ID.trim() || env.BACKGROUND_DEPLOYMENT_ID.length > 256)
throw new Error("BACKGROUND_DEPLOYMENT_ID must be nonempty and at most 256 characters");
if (!env.DATABASE_URL) throw new Error("Background ownership requires DATABASE_URL");
if (
!isStrongSigningSecret(env.CORE_SIGNING_SECRET) ||
!isStrongSigningSecret(env.DEPLOYMENT_CONTROL_SECRET) ||
env.DEPLOYMENT_CONTROL_SECRET === env.CORE_SIGNING_SECRET
)
throw new Error(
"Background ownership requires a distinct DEPLOYMENT_CONTROL_SECRET of at least 32 characters and CORE_SIGNING_SECRET",
);
}
const swarmDefaults = resolveSwarmSettings(
env.SWARM_DEFAULTS === undefined ? undefined : JSON.parse(env.SWARM_DEFAULTS),
);
const harness = harnessEnvStrict(env.HARNESS);
const codexAuthCredential = env.CODEX_AUTH_CREDENTIAL?.trim() || undefined;
const claudeAuthCredential = env.CLAUDE_AUTH_CREDENTIAL?.trim() || undefined;
const codexAuthFile = codexAuthCredential ? undefined : codexAuthFileForEnv(env);
if (env.NODE_ENV === "production" && codexAuthFile) {
throw new Error(
"CODEX_AUTH_FILE is supported for local development only; production must use CODEX_AUTH_CREDENTIAL (keychain custody)",
);
}
if (codexAuthFile) {
try {
loadCodexAuthFile(codexAuthFile);
} catch (error) {
throw new Error(`CODEX_AUTH_FILE is unusable: ${errMessage(error)}`, { cause: error });
}
}
const deployAppsDomain = deployAppsDomainEnv(env, env.DEPLOY_PROVIDER ?? "docker");
const missingSecrets = validateCoreSecretEnv(env);
if (missingSecrets.length) {
const described = missingSecrets.map((name) => {
const reason = CORE_SECRET_SPECS.find((spec) => spec.name === name)?.reason;
return reason ? `${name} (${reason})` : name;
});
throw new Error(`missing or insecure required core secrets: ${described.join(", ")}`);
}
const modelProvider = modelProviderEnvStrict(env);
const { sessionStore, runStore } = resolveStoreKinds(env);
if (env.E2B_API_KEY && !env.E2B_SNAPSHOT_S3_BUCKET) {
console.warn(
"[config] e2b sandbox backend enabled without E2B_SNAPSHOT_S3_BUCKET — provider pause preserves the machine, but there are no home snapshots, so a sandbox the provider loses comes back with an empty home; set E2B_SNAPSHOT_S3_BUCKET for durable portable recovery.",
);
}
if (env.MODAL_TOKEN_ID && env.MODAL_TOKEN_SECRET && !env.MODAL_SNAPSHOT_S3_BUCKET) {
console.warn(
"[config] modal sandbox backend enabled without MODAL_SNAPSHOT_S3_BUCKET — there are no home snapshots, so unless native home checkpoints are enabled (limited retention) the home is lost at Modal's 24h sandbox lifetime. Set MODAL_SNAPSHOT_S3_BUCKET for durable portable recovery and configure DATABASE_URL for durable checkpoint references.",
);
}
if (env.SMOLMACHINES_TOKEN && !env.SMOLMACHINES_SNAPSHOT_S3_BUCKET) {
console.warn(
"[config] smolmachines sandbox backend enabled without SMOLMACHINES_SNAPSHOT_S3_BUCKET — stopping a machine is not a backup; set SMOLMACHINES_SNAPSHOT_S3_BUCKET for durable home recovery snapshots.",
);
}
if (env.SANDBOX_BACKEND === "sprites" && !env.SPRITES_EGRESS_PROXY_URL) {
console.warn(
"[config] SANDBOX_BACKEND=sprites without SPRITES_EGRESS_PROXY_URL — sandboxes run with NO egress enforcement (fail-open); set SPRITES_EGRESS_PROXY_URL to the public egress proxy to force sandbox traffic through it.",
);
}
if (env.SANDBOX_BACKEND === "e2b" && !env.E2B_EGRESS_PROXY_URL) {
console.warn(
"[config] SANDBOX_BACKEND=e2b without E2B_EGRESS_PROXY_URL — sandboxes run with NO egress enforcement (fail-open); set E2B_EGRESS_PROXY_URL to the public egress proxy so E2B's network rules admit only that host.",
);
}
if (env.SANDBOX_BACKEND === "do-managed-agents" && !env.DO_AGENTS_EGRESS_PROXY_URL) {
console.warn(
"[config] SANDBOX_BACKEND=do-managed-agents without DO_AGENTS_EGRESS_PROXY_URL — sandboxes run with NO egress enforcement (fail-open); set DO_AGENTS_EGRESS_PROXY_URL to the public egress proxy so the session's egress allowlist admits only that host.",
);
}
if (env.DO_AGENTS_API_TOKEN && !env.DO_AGENTS_SNAPSHOT_S3_BUCKET) {
console.warn(
"[config] do-managed-agents sandbox backend enabled without DO_AGENTS_SNAPSHOT_S3_BUCKET — pause preserves the microVM, but a destroyed session takes the home with it; set DO_AGENTS_SNAPSHOT_S3_BUCKET so a replacement session can hydrate from a portable snapshot.",
);
}
if (env.MODAL_TOKEN_ID && env.MODAL_TOKEN_SECRET && !env.MODAL_EGRESS_PROXY_URL) {
console.warn(
"[config] modal sandbox backend enabled without MODAL_EGRESS_PROXY_URL — sandboxes run with NO egress enforcement (fail-open); set MODAL_EGRESS_PROXY_URL to the public https egress proxy so Modal's outbound allowlist admits only that host.",
);
}
if (env.SANDBOX_BACKEND === "sprites" && !env.SPRITES_SNAPSHOT_S3_BUCKET) {
console.warn(
"[config] SANDBOX_BACKEND=sprites without SPRITES_SNAPSHOT_S3_BUCKET — retiring a computer deletes its sprite and every checkpoint irreversibly with no exported home; set SPRITES_SNAPSHOT_S3_BUCKET to export the home to S3 before a sprite is destroyed and to rehydrate a replacement.",
);
}
if (env.SANDBOX_BACKEND === "smolmachines" && !env.SMOLMACHINES_EGRESS_PROXY_URL) {
console.warn(
"[config] SANDBOX_BACKEND=smolmachines without SMOLMACHINES_EGRESS_PROXY_URL — machines are created with open outbound networking and NO egress enforcement (fail-open); set SMOLMACHINES_EGRESS_PROXY_URL to allow-list only the egress proxy.",
);
}
const dataDir = resolve(env.DATA_DIR ?? "./data");
const porterSandboxSelected = env.SANDBOX_BACKEND === "porter";
if (porterSandboxSelected && !env.PORTER_SANDBOX_EGRESS_PROXY_URL) {
console.warn(
"[config] SANDBOX_BACKEND=porter without PORTER_SANDBOX_EGRESS_PROXY_URL — sandboxes run with NO egress enforcement (fail-open); set PORTER_SANDBOX_EGRESS_PROXY_URL to the egress proxy to force sandbox traffic through it.",
);
}
if (env.DEPLOY_PROVIDER === "porter" && !env.PORTER_DEPLOY_APPS_DOMAIN && !env.DEPLOY_APPS_DOMAIN) {
console.warn(
"[config] DEPLOY_PROVIDER=porter without an apps domain — published apps are reachable signed-in at /d/<app>/ only; set DEPLOY_APPS_DOMAIN to a domain you control to serve each app on its own subdomain.",
);
}
for (const [selected, label] of [
[porterSandboxSelected, "SANDBOX_BACKEND=porter"],
[env.DEPLOY_PROVIDER === "porter", "DEPLOY_PROVIDER=porter"],
] as const) {
if (selected && !porterLocatorPresent(env)) {
throw new Error(
`${label} requires PORTER_DEPLOY_PROJECT_ID and PORTER_DEPLOY_CLUSTER_ID (or PORTER_SANDBOX_BASE_URL, or PORTER_CLUSTER_ID) to locate the Porter sandbox API.`,
);
}
}
if (env.NODE_ENV === "production" && !env.SANDBOX_BACKEND?.trim()) {
throw new Error(
"SANDBOX_BACKEND must be set explicitly in production — use sprites, smolmachines, e2b, modal, porter, agent37, superserve, do-managed-agents, aws, or local.",
);
}
const sandboxBackend = sandboxBackendEnvStrict(env.SANDBOX_BACKEND);
const legacySandboxScopeDefaults: LegacySandboxScopeDefaults = {};
if (env.SANDBOX_SCOPE_BACKENDS) {
const values: unknown = JSON.parse(env.SANDBOX_SCOPE_BACKENDS);
if (!values || typeof values !== "object" || Array.isArray(values))
throw new Error("SANDBOX_SCOPE_BACKENDS must be an object of scope kinds and backend names");
for (const [kind, value] of Object.entries(values)) {
const parsed = parseScopeId(kind + ":scope").kind;
if (!parsed || parsed !== kind || typeof value !== "string" || !value.trim())
throw new Error("Invalid SANDBOX_SCOPE_BACKENDS entry: " + kind);
legacySandboxScopeDefaults[parsed] = sandboxBackendEnvStrict(value, "SANDBOX_SCOPE_BACKENDS." + kind);
}
}
const superserveSelected = sandboxBackend === "superserve";
if (superserveSelected && !env.SUPERSERVE_TEMPLATE?.trim()) {
throw new Error(
"SANDBOX_BACKEND=superserve requires SUPERSERVE_TEMPLATE, the ready qm-agent-<release> template that carries the agent toolchain.",
);
}
if (env.SANDBOX_SECONDARY_BACKEND?.trim()) {
console.warn(
`[config] SANDBOX_SECONDARY_BACKEND=${JSON.stringify(env.SANDBOX_SECONDARY_BACKEND.trim())} is retired and ignored — every backend whose credential is present is constructed; per-scope routes pick between them. Remove the variable.`,
);
}
const retiredBrainEnv = ["BRAIN", "BRAIN_MCP_URL", "BRAIN_RO_CLIENT_ID", "BRAIN_RW_CLIENT_ID"].filter((name) =>
env[name]?.trim(),
);
if (retiredBrainEnv.length) {
console.warn(
`[config] ${retiredBrainEnv.join(", ")} ${retiredBrainEnv.length === 1 ? "is" : "are"} retired and ignored — the brain integration was removed; point an external knowledge server at MEMORY_PROVIDER_CONFIG (docs/memory-providers.md). Remove the variables.`,
);
}
const retiredScreenEnv = RETIRED_SECURITY_SCREEN_ENV.filter((name) => env[name]?.trim());
const retiredScreenOff =
retiredScreenEnv.length === 1 &&
env.SECURITY_SCREEN_BACKEND?.trim().toLowerCase() === "off" &&
!env.SECURITY_SCREEN?.trim();
if (retiredScreenOff) {
console.warn("[config] SECURITY_SCREEN_BACKEND=off is retired and read as SECURITY_SCREEN=off. Replace it.");
} else if (retiredScreenEnv.length) {
throw new Error(
`${retiredScreenEnv.join(", ")} ${retiredScreenEnv.length === 1 ? "is" : "are"} retired — set SECURITY_SCREEN=off|observe|enforce and SECURITY_SCREEN_CLASSIFIER=model|proxy instead, and remove the old variables.`,
);
}
const securityScreen = choiceEnvStrict("SECURITY_SCREEN", env.SECURITY_SCREEN, SECURITY_SCREEN_MODES);
const securityScreenClassifier = choiceEnvStrict("SECURITY_SCREEN_CLASSIFIER", env.SECURITY_SCREEN_CLASSIFIER, [
"model",
"proxy",
] as const);
const proxyProvider = env.SECURITY_SCREEN_PROXY_PROVIDER?.trim();
const proxyEndpoint = env.SECURITY_SCREEN_PROXY_ENDPOINT?.trim();
const proxyToken = env.SECURITY_SCREEN_PROXY_TOKEN?.trim();
const hasProxyConfig = [proxyProvider, proxyEndpoint, proxyToken].some(Boolean);
if (securityScreenClassifier === "proxy" && (!proxyProvider || !proxyEndpoint || !proxyToken)) {
throw new Error(
"SECURITY_SCREEN_CLASSIFIER=proxy requires SECURITY_SCREEN_PROXY_PROVIDER, SECURITY_SCREEN_PROXY_ENDPOINT, and SECURITY_SCREEN_PROXY_TOKEN",
);
}
if (securityScreenClassifier !== "proxy" && hasProxyConfig) {
throw new Error("SECURITY_SCREEN_PROXY_* requires SECURITY_SCREEN_CLASSIFIER=proxy");
}
if (proxyProvider && (proxyProvider.length > 63 || !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(proxyProvider))) {
throw new Error("SECURITY_SCREEN_PROXY_PROVIDER must be a lowercase DNS label");
}
if (proxyProvider === "surface" || proxyProvider === "origin") {
throw new Error("SECURITY_SCREEN_PROXY_PROVIDER must not collide with a security screen metadata field");
}
if (proxyEndpoint) {
try {
const url = new URL(proxyEndpoint);
if (url.protocol !== "https:" || url.username || url.password || url.hash || url.hostname.endsWith("."))
throw new Error("endpoint");
} catch {
throw new Error(
"SECURITY_SCREEN_PROXY_ENDPOINT must be an HTTPS URL without credentials, a fragment, or a trailing hostname dot",
);
}
}
const securityScreenTimeoutMs =
numEnvStrict("SECURITY_SCREEN_TIMEOUT_MS", env.SECURITY_SCREEN_TIMEOUT_MS) ??
CONFIG_DEFAULTS.securityScreenTimeoutMs;
if (
!Number.isSafeInteger(securityScreenTimeoutMs) ||
securityScreenTimeoutMs <= 0 ||
securityScreenTimeoutMs > 2_147_483_647
) {
throw new Error("SECURITY_SCREEN_TIMEOUT_MS must be a positive integer no greater than 2147483647");
}
const publicApiUrl = env.PUBLIC_API_URL ?? env.AGENT_API_URL;
const publicUrl = env.PUBLIC_WEB_URL || publicApiUrl;
const deployProvider = env.DEPLOY_PROVIDER ?? "docker";
if (
deployProvider !== "aws" &&
deployProvider !== "docker" &&
deployProvider !== "fly" &&
deployProvider !== "porter" &&
deployProvider !== "e2b"
) {
throw new Error(
`DEPLOY_PROVIDER=${JSON.stringify(deployProvider)} is not recognized (expected aws, docker, fly, porter, or e2b)`,
);
}
const providerBaseUrls = providerBaseUrlsFromEnv(env);
const modelGateway = modelGatewayFromEnv(env);
const brokerCredentials = deploymentBrokerCredentialsFromEnv(env);
const claudeProcessEnv = Object.fromEntries(
[
"PATH",
"TMPDIR",
"LANG",
"LC_ALL",
"SSL_CERT_FILE",
"SSL_CERT_DIR",
"NODE_EXTRA_CA_CERTS",
"HTTP_PROXY",
"HTTPS_PROXY",
"NO_PROXY",
"ALL_PROXY",
"ANTHROPIC_API_KEY",
"ANTHROPIC_AUTH_TOKEN",
"CLAUDE_CODE_OAUTH_TOKEN",
].flatMap((name) => (env[name] === undefined ? [] : [[name, env[name]]])),
) as NodeJS.ProcessEnv;
if (providerBaseUrls.anthropic) claudeProcessEnv.ANTHROPIC_BASE_URL = providerBaseUrls.anthropic;
const turnWallClockMs =
(numEnvStrict("TURN_WALL_CLOCK_SEC", env.TURN_WALL_CLOCK_SEC) ?? CONFIG_DEFAULTS.turnWallClockSec) * 1000;
const runMaxAgeMs =
numEnvStrict("RUN_MAX_AGE_MS", env.RUN_MAX_AGE_MS) ??
(turnWallClockMs > 0 ? 2 * turnWallClockMs : CONFIG_DEFAULTS.runMaxAgeMs);
const slack = slackPluginConfigFromEnv(env);
const externalSlackPolicies = Object.fromEntries(
[...(slack ? [slack] : []), ...slackAccountConfigsFromEnv(env)]
.filter((account) => account.externalAccess)
.map((account) => [account.accountId ?? "default", account.externalAccess!]),
);
const slackEventsPort =
env.SLACK_EVENTS_MODE?.trim() === "http" ? numEnvStrict("SLACK_EVENTS_PORT", env.SLACK_EVENTS_PORT) : undefined;
if (
slackEventsPort !== undefined &&
(!Number.isSafeInteger(slackEventsPort) || slackEventsPort <= 0 || slackEventsPort > 65_535)
) {
throw new Error("SLACK_EVENTS_PORT must be an integer from 1 through 65535");
}
const memoryProviderConfig = parseMemoryProviderConfig(env.MEMORY_PROVIDER_CONFIG, env);
return {
suggestedActivitiesEnabled: boolEnvStrict("SUGGESTED_ACTIVITIES_ENABLED", env.SUGGESTED_ACTIVITIES_ENABLED) ?? true,
...(env.SUGGESTED_ACTIVITIES_CONTEXT
? { suggestedActivitiesContext: env.SUGGESTED_ACTIVITIES_CONTEXT.slice(0, 8000) }
: {}),
production: env.NODE_ENV === "production",
allowUnauthenticatedCore: boolEnvStrict("ALLOW_UNAUTHENTICATED_CORE", env.ALLOW_UNAUTHENTICATED_CORE) ?? false,
port: numEnvStrict("PORT", env.PORT) ?? CONFIG_DEFAULTS.port,
dataDir,
orgId: env.ORG_ID ?? DEFAULT_ORG_ID,
...(env.POSTHOG_API_KEY?.trim()
? { productAnalytics: { apiKey: env.POSTHOG_API_KEY.trim(), host: env.POSTHOG_HOST?.trim() } }
: {}),
sessionStore,
...(env.DATABASE_URL ? { databaseUrl: env.DATABASE_URL } : {}),
...(env.DATABASE_POOL_URL ? { databasePoolUrl: env.DATABASE_POOL_URL } : {}),
...(env.DATABASE_POOL_CA_CERT ? { databasePoolCaCert: env.DATABASE_POOL_CA_CERT } : {}),
...(env.DATABASE_POOL_MAX ? { databasePoolMax: numEnvStrict("DATABASE_POOL_MAX", env.DATABASE_POOL_MAX) } : {}),
...(env.DATABASE_DIRECT_POOL_MAX
? { databaseDirectPoolMax: numEnvStrict("DATABASE_DIRECT_POOL_MAX", env.DATABASE_DIRECT_POOL_MAX) }
: {}),
...(env.DATABASE_CA_CERT ? { databaseCaCert: env.DATABASE_CA_CERT } : {}),
...(env.DATABASE_CA_CERT_FILE ? { databaseCaCertFile: env.DATABASE_CA_CERT_FILE } : {}),
harness,
securityPosture: securityPostureEnvStrict(env.HARNESS_SECURITY_POSTURE),
sharingPosture: sharingPostureEnvStrict(env.HARNESS_SHARING_POSTURE),
securityScreen,
securityScreenClassifier,
...(securityScreenClassifier === "proxy"
? { securityScreenProxy: { provider: proxyProvider!, endpoint: proxyEndpoint!, token: proxyToken! } }
: {}),
sandboxBackend,
legacySandboxScopeDefaults,
deployProvider,
...(env.EGRESS_SERVICE_HOSTS
? {
egressServiceHosts: env.EGRESS_SERVICE_HOSTS.split(",")
.map((s) => s.trim())
.filter(Boolean),
}
: {}),
...(orgBrandingFromEnv(env) ? { brandingDefault: orgBrandingFromEnv(env) } : {}),
...(env.PI_MODEL ? { modelId: env.PI_MODEL } : {}),
...(codexAuthFile ? { codexAuthFile } : {}),
...(codexAuthCredential ? { codexAuthCredential } : {}),
...(claudeAuthCredential ? { claudeAuthCredential } : {}),
...(env.CLAUDE_MODEL ? { claudeModel: env.CLAUDE_MODEL } : {}),
...(env.CLAUDE_BIN ? { claudeBinPath: env.CLAUDE_BIN } : {}),
claudeProcessEnv,
...(env.PI_DETECT_MODEL ? { detectModelId: env.PI_DETECT_MODEL } : {}),
...(env.PI_TITLE_MODEL ? { titleModelId: env.PI_TITLE_MODEL } : {}),
...(env.PI_JUDGE_MODEL ? { judgeModelId: env.PI_JUDGE_MODEL } : {}),
...(env.ANTHROPIC_API_KEY ? { anthropicApiKey: env.ANTHROPIC_API_KEY } : {}),
...(env.OPENAI_API_KEY ? { openaiApiKey: env.OPENAI_API_KEY } : {}),
...(env.OPENROUTER_API_KEY ? { openrouterApiKey: env.OPENROUTER_API_KEY } : {}),
...(modelProvider ? { modelProvider } : {}),
providerBaseUrls,
...(modelGateway ? { modelGateway } : {}),
...(brokerCredentials.length ? { brokerCredentials } : {}),
...(env.TRUSTED_OIDC_ADMIN_ISSUER ? { trustedOidcAdminIssuer: env.TRUSTED_OIDC_ADMIN_ISSUER } : {}),
...(env.ADMIN_GRANTS ? { adminGrants: env.ADMIN_GRANTS } : {}),
...(env.AUTH_ALLOWED_EMAILS
? {
emailAuthPrincipals: [
...new Set(
env.AUTH_ALLOWED_EMAILS.split(",")
.map((email) => email.trim().toLowerCase())
.filter(Boolean),
),
],
}
: {}),
...(env.AUTH_ALLOWED_EMAIL_DOMAIN?.trim()
? { emailAuthDomain: env.AUTH_ALLOWED_EMAIL_DOMAIN.trim().toLowerCase() }
: {}),
...(env.RESEND_API_KEY?.trim() ? { resendApiKey: env.RESEND_API_KEY.trim() } : {}),
...(env.AUTH_EMAIL_FROM?.trim() ? { emailFrom: env.AUTH_EMAIL_FROM.trim() } : {}),
piCaptureRequests: boolEnvStrict("PI_CAPTURE_REQUESTS", env.PI_CAPTURE_REQUESTS) ?? true,
piSystemCacheSplit: boolEnvStrict("PI_SYSTEM_CACHE_SPLIT", env.PI_SYSTEM_CACHE_SPLIT) ?? false,
rateLimitPerWindow:
numEnvStrict("RATE_LIMIT_PER_WINDOW", env.RATE_LIMIT_PER_WINDOW) ?? CONFIG_DEFAULTS.rateLimitPerWindow,
rateLimitWindowMs:
numEnvStrict("RATE_LIMIT_WINDOW_MS", env.RATE_LIMIT_WINDOW_MS) ?? CONFIG_DEFAULTS.rateLimitWindowMs,
...(numEnvStrict("BUDGET_USD_PER_WINDOW", env.BUDGET_USD_PER_WINDOW) !== undefined
? { budgetUsdPerWindow: numEnvStrict("BUDGET_USD_PER_WINDOW", env.BUDGET_USD_PER_WINDOW) }
: {}),
...(numEnvStrict("ORG_BUDGET_USD_PER_WINDOW", env.ORG_BUDGET_USD_PER_WINDOW) !== undefined
? { orgBudgetUsdPerWindow: numEnvStrict("ORG_BUDGET_USD_PER_WINDOW", env.ORG_BUDGET_USD_PER_WINDOW) }
: {}),
budgetWindowMs: numEnvStrict("BUDGET_WINDOW_MS", env.BUDGET_WINDOW_MS) ?? CONFIG_DEFAULTS.budgetWindowMs,
...(numEnvStrict("MAX_CONTEXT_TOKENS", env.MAX_CONTEXT_TOKENS) !== undefined
? { maxContextTokens: numEnvStrict("MAX_CONTEXT_TOKENS", env.MAX_CONTEXT_TOKENS) }
: {}),
execTimeoutDefaultMs:
(numEnvStrict("EXEC_TIMEOUT_DEFAULT_SEC", env.EXEC_TIMEOUT_DEFAULT_SEC) ??
CONFIG_DEFAULTS.execTimeoutDefaultSec) * 1000,
execTimeoutMaxMs:
(numEnvStrict("EXEC_TIMEOUT_MAX_SEC", env.EXEC_TIMEOUT_MAX_SEC) ?? CONFIG_DEFAULTS.execTimeoutMaxSec) * 1000,
turnWallClockMs,
swarmsEnabled: boolEnvStrict("SWARMS_ENABLED", env.SWARMS_ENABLED) ?? true,
swarmDefaults,
runMaxAgeMs,
runWaitMs: (turnWallClockMs > 0 ? turnWallClockMs : runMaxAgeMs) + 60_000,
sandboxCapabilityTtlMs: parseSandboxCapabilityTtlMs(env.SANDBOX_CAPABILITY_TTL_HOURS),
backgroundJobTtlMs:
(numEnvStrict("BACKGROUND_JOB_TTL_SEC", env.BACKGROUND_JOB_TTL_SEC) ?? CONFIG_DEFAULTS.backgroundJobTtlSec) *
1000,
backgroundJobTtlMaxMs:
(numEnvStrict("BACKGROUND_JOB_TTL_MAX_SEC", env.BACKGROUND_JOB_TTL_MAX_SEC) ??
CONFIG_DEFAULTS.backgroundJobTtlMaxSec) * 1000,
backgroundWorkEnabled:
boolEnvStrict("BACKGROUND_WORK_ENABLED", env.BACKGROUND_WORK_ENABLED) ?? CONFIG_DEFAULTS.backgroundWorkEnabled,
...(env.BACKGROUND_DEPLOYMENT_ID
? { backgroundDeploymentId: env.BACKGROUND_DEPLOYMENT_ID, deploymentControlSecret: env.DEPLOYMENT_CONTROL_SECRET }
: {}),
...(env.SPEND_EXPORT_TOKEN ? { spendExportToken: env.SPEND_EXPORT_TOKEN } : {}),
...(env.GIT_SHA ? { buildSha: env.GIT_SHA } : {}),
monitorPollMs: numEnvStrict("MONITOR_POLL_MS", env.MONITOR_POLL_MS) ?? CONFIG_DEFAULTS.monitorPollMs,
skillSyncPollMs: numEnvStrict("SKILL_SYNC_POLL_MS", env.SKILL_SYNC_POLL_MS) ?? CONFIG_DEFAULTS.skillSyncPollMs,
monitorHeartbeatMs:
(numEnvStrict("MONITOR_HEARTBEAT_SEC", env.MONITOR_HEARTBEAT_SEC) ?? CONFIG_DEFAULTS.monitorHeartbeatSec) * 1000,
...(env.CORE_SIGNING_SECRET ? { signingSecret: env.CORE_SIGNING_SECRET } : {}),
...((env.CAPABILITY_SECRET ?? env.CORE_SIGNING_SECRET)
? { capabilitySecret: env.CAPABILITY_SECRET ?? env.CORE_SIGNING_SECRET }
: {}),
...((env.PORTAL_IDENTITY_SECRET ?? env.CORE_SIGNING_SECRET)
? { portalIdentitySecret: env.PORTAL_IDENTITY_SECRET ?? env.CORE_SIGNING_SECRET }
: {}),
capabilityTokenCompression:
boolEnvStrict("CAPABILITY_TOKEN_COMPRESSION", env.CAPABILITY_TOKEN_COMPRESSION) ?? false,
requireSignedPortalIdentity: env.REQUIRE_SIGNED_PORTAL_IDENTITY === "1",
...(env.CONNECTOR_SECRET_KEY ? { connectorSecretKey: env.CONNECTOR_SECRET_KEY } : {}),
...(slackEventsPort !== undefined ? { slackEventsPort } : {}),
secretsBackend: secretsBackendEnvStrict(env.SECRETS_BACKEND, env.SECRETS_PREFIX ?? ""),
secretsPrefix: env.SECRETS_PREFIX ?? "",
layerEnv: { ...env },
...(publicApiUrl ? { apiBaseUrl: publicApiUrl } : {}),
...(publicUrl ? { publicUrl } : {}),
...(env.GMAIL_PUBSUB_TOPIC && env.GMAIL_PUBSUB_AUDIENCE && env.GMAIL_PUBSUB_SERVICE_ACCOUNT
? {
gmailPubSub: {
topic: env.GMAIL_PUBSUB_TOPIC,
audience: env.GMAIL_PUBSUB_AUDIENCE,
serviceAccount: env.GMAIL_PUBSUB_SERVICE_ACCOUNT,
},
}
: {}),
...(env.PUBLIC_WEB_URL ? { publicWebUrl: env.PUBLIC_WEB_URL } : {}),
...(env.FLY_APP_NAME ? { flyAppName: env.FLY_APP_NAME } : {}),
...(slack ? { slack } : {}),
externalSlackPolicies,
slackContextSource: parseSlackContextSource(env.SLACK_CONTEXT_SOURCE),
runStore,
...(env.SKILL_SIGNING_SECRET ? { skillSigningSecret: env.SKILL_SIGNING_SECRET } : {}),
seedSkills: boolEnvStrict("SEED_SKILLS", env.SEED_SKILLS) ?? true,
skillsSeedDir: resolve(env.SKILLS_SEED_DIR ?? "./skills-seed"),
pluginSkillDirs: csvPaths(env.PLUGIN_SKILLS_DIRS) ?? defaultPluginSkillDirs(),
...(env.DEPLOYMENT_LAYER ? { deploymentLayerDir: resolve(env.DEPLOYMENT_LAYER) } : {}),
memoryRecall: parseMemoryRecallMode(env.MEMORY_RECALL),
memoryCapture: parseMemoryCaptureMode(env.MEMORY_CAPTURE),
memoryStrategy: parseMemoryStrategyKind(env.MEMORY_STRATEGY),
...(memoryProviderConfig ? { memoryProviderConfig } : {}),
memoryCaptureQuietMs:
numEnvStrict("MEMORY_CAPTURE_QUIET_MS", env.MEMORY_CAPTURE_QUIET_MS) ?? DEFAULT_CAPTURE_QUIET_MS,
...(numEnvStrict("MEMORY_CAPTURE_MAX_TURNS", env.MEMORY_CAPTURE_MAX_TURNS) !== undefined
? { memoryCaptureMaxTurns: numEnvStrict("MEMORY_CAPTURE_MAX_TURNS", env.MEMORY_CAPTURE_MAX_TURNS) }
: {}),
filesDirectUploadsEnabled: boolEnvStrict("FILES_DIRECT_UPLOADS_ENABLED", env.FILES_DIRECT_UPLOADS_ENABLED) ?? false,
snapshotStore: env.SNAPSHOT_STORE === "s3" ? "s3" : "local",
transferStore: env.TRANSFER_STORE === "s3" ? "s3" : "local",
...(env.S3_BUCKET ? { s3Bucket: env.S3_BUCKET } : {}),
...(env.S3_REGION ? { s3Region: env.S3_REGION } : {}),
...(env.S3_PREFIX ? { s3Prefix: env.S3_PREFIX } : {}),
...(numEnvStrict("DEPLOY_IDLE_TTL_MS", env.DEPLOY_IDLE_TTL_MS) !== undefined
? { deployIdleTtlMs: numEnvStrict("DEPLOY_IDLE_TTL_MS", env.DEPLOY_IDLE_TTL_MS) }
: {}),
deployGitDir: env.DEPLOY_GIT_DIR ? resolve(env.DEPLOY_GIT_DIR) : join(dataDir, "deploy-git"),
deployDialTimeoutMs:
numEnvStrict("DEPLOY_DIAL_TIMEOUT_MS", env.DEPLOY_DIAL_TIMEOUT_MS) ?? CONFIG_DEFAULTS.deployDialTimeoutMs,
...deployAppsEnv(env, publicUrl),
deepIdleMachineMs:
numEnvStrict("DEEP_IDLE_MACHINE_MS", env.DEEP_IDLE_MACHINE_MS) ?? CONFIG_DEFAULTS.deepIdleMachineMs,
devIdleMachineMs: numEnvStrict("DEV_IDLE_MACHINE_MS", env.DEV_IDLE_MACHINE_MS) ?? CONFIG_DEFAULTS.devIdleMachineMs,
cronFireConcurrency:
numEnvStrict("CRON_FIRE_CONCURRENCY", env.CRON_FIRE_CONCURRENCY) ?? CONFIG_DEFAULTS.cronFireConcurrency,
workers: numEnvStrict("WORKERS", env.WORKERS) ?? CONFIG_DEFAULTS.workers,
leaseTtlMs: numEnvStrict("LEASE_TTL_MS", env.LEASE_TTL_MS) ?? CONFIG_DEFAULTS.leaseTtlMs,
heartbeatIntervalMs:
numEnvStrict("HEARTBEAT_INTERVAL_MS", env.HEARTBEAT_INTERVAL_MS) ??
Math.max(1_000, Math.floor((numEnvStrict("LEASE_TTL_MS", env.LEASE_TTL_MS) ?? CONFIG_DEFAULTS.leaseTtlMs) / 3)),
reaperIntervalMs: numEnvStrict("REAPER_INTERVAL_MS", env.REAPER_INTERVAL_MS) ?? CONFIG_DEFAULTS.reaperIntervalMs,
shutdownDrainMs: numEnvStrict("SHUTDOWN_DRAIN_MS", env.SHUTDOWN_DRAIN_MS) ?? CONFIG_DEFAULTS.shutdownDrainMs,
maxAttempts: numEnvStrict("MAX_ATTEMPTS", env.MAX_ATTEMPTS) ?? CONFIG_DEFAULTS.maxAttempts,
maxClaims: numEnvStrict("MAX_CLAIMS", env.MAX_CLAIMS) ?? CONFIG_DEFAULTS.maxClaims,
processReaperIntervalMs:
numEnvStrict("PROCESS_REAPER_INTERVAL_MS", env.PROCESS_REAPER_INTERVAL_MS) ??
CONFIG_DEFAULTS.processReaperIntervalMs,
approvalSummaryTimeoutMs:
numEnvStrict("APPROVAL_SUMMARY_TIMEOUT_MS", env.APPROVAL_SUMMARY_TIMEOUT_MS) ??
CONFIG_DEFAULTS.approvalSummaryTimeoutMs,
turnLeaseWaitMs: numEnvStrict("TURN_LEASE_WAIT_MS", env.TURN_LEASE_WAIT_MS) ?? CONFIG_DEFAULTS.turnLeaseWaitMs,
securityScreenTimeoutMs,
scratchExecEnabled: boolEnvStrict("EXECUTE_SCRATCH", env.EXECUTE_SCRATCH) ?? false,
reachExecEnabled: boolEnvStrict("REACH_EXEC", env.REACH_EXEC) ?? false,
surfaceDebugFooter: boolEnvStrict("SURFACE_DEBUG_FOOTER", env.SURFACE_DEBUG_FOOTER) ?? false,
eagerProvisionEnabled: boolEnvStrict("EAGER_PROVISION", env.EAGER_PROVISION) ?? true,
awsSandbox: awsSandboxEnv(env),
localSandbox: localSandboxEnv(env),
spritesSandbox: spritesSandboxEnv(env),
smolmachinesSandbox: smolmachinesSandboxEnv(env),
agent37Sandbox: agent37SandboxEnv(env),
superserveSandbox: superserveSandboxEnv(env),
porterSandbox: porterSandboxEnv(env),
porterDeploy: porterDeployEnv(env),
e2bSandbox: e2bSandboxEnv(env),
managedAgentsSandbox: managedAgentsSandboxEnv(env),
modalSandbox: modalSandboxEnv(env),
awsDeploy: {
...awsDeployEnv(env),
...(env.DEPLOY_APPS_DOMAIN && deployAppsDomain && !env.AWS_DEPLOY_APPS_DOMAIN
? { appsDomain: deployAppsDomain }
: {}),
},
...(deployAppsDomain ? { deployAppsDomain } : {}),
flyDeploy: flyDeployEnv(env),
};
}