Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🛂 feat: Add Configurable BYOM Enrollment Policy (#15673)

Danny Avila8f6efaf6edf7
diff --git a/librechat.example.yaml b/librechat.example.yaml
index 843a6dfd81..1ae4800d4e 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -566,6 +566,14 @@ endpoints:
# # (optional) Limit the workspace scopes users may select. Omit to allow all three.
# statefulCodeSessions:
# allowedEnvironments: ["user", "agent-user", "conversation"]
+ # # Personal BYOM enrollment. Requires allowPrincipalWorkers on a control plane.
+ # # Omitted values default to enabled and five registered environments per user.
+ # # Principal config overrides may tighten, but cannot raise, this ceiling.
+ # # Lowering the limit, or disabling enrollment, does not revoke existing machines.
+ # # This counts registered environments across control planes, not online workers.
+ # principalWorkers:
+ # enabled: true
+ # maxPerUser: 25
# # Route an agent to an operator-managed Code API or to a Code API whose
# # `remote-bridge` backend leases work to an outbound @librechat/code worker.
# environments:
diff --git a/packages/api/src/code/enrollment.spec.ts b/packages/api/src/code/enrollment.spec.ts
new file mode 100644
index 0000000000..1b216c1b44
--- /dev/null
+++ b/packages/api/src/code/enrollment.spec.ts
@@ -0,0 +1,27 @@
+import { resolveCodeWorkerEnrollmentLimit } from './enrollment';
+
+describe('personal worker enrollment policy', () => {
+ test.each([
+ [undefined, undefined, 5],
+ [{ maxPerUser: 100 }, undefined, 100],
+ [{ maxPerUser: 100 }, { maxPerUser: 20 }, 20],
+ [{ maxPerUser: 10 }, { maxPerUser: 100 }, 10],
+ [undefined, { maxPerUser: 100 }, 5],
+ [{ enabled: false }, { enabled: true }, 0],
+ [{ enabled: true }, { enabled: false }, 0],
+ [{ maxPerUser: 0 }, { maxPerUser: 100 }, 0],
+ [{ maxPerUser: 100 }, { maxPerUser: 0 }, 0],
+ [{ maxPerUser: -1 }, undefined, 0],
+ [{ maxPerUser: Infinity }, undefined, 0],
+ [undefined, { maxPerUser: NaN }, 0],
+ [undefined, { maxPerUser: 1.5 }, 0],
+ [{ maxPerUser: Number.MAX_SAFE_INTEGER + 1 }, undefined, 0],
+ ])('resolves deployment %j and principal %j to %i', (deployment, effective, expected) => {
+ expect(resolveCodeWorkerEnrollmentLimit(deployment, effective)).toBe(expected);
+ });
+
+ test('supports a caller fallback without replacing an explicit deployment policy', () => {
+ expect(resolveCodeWorkerEnrollmentLimit(undefined, undefined, 3)).toBe(3);
+ expect(resolveCodeWorkerEnrollmentLimit({ maxPerUser: 10 }, undefined, 3)).toBe(10);
+ });
+});
diff --git a/packages/api/src/code/enrollment.ts b/packages/api/src/code/enrollment.ts
new file mode 100644
index 0000000000..86f1bf8aec
--- /dev/null
+++ b/packages/api/src/code/enrollment.ts
@@ -0,0 +1,26 @@
+import type { CodeWorkerEnrollmentPolicy } from 'librechat-data-provider';
+
+/** A principal override can restrict enrollment, never expand deployment authority.
+ * Missing effective fields inherit the deployment policy. Invalid programmatic
+ * limits fail closed, even when the caller did not pass through config validation.
+ */
+export function resolveCodeWorkerEnrollmentLimit(
+ deployment?: CodeWorkerEnrollmentPolicy,
+ effective?: CodeWorkerEnrollmentPolicy,
+ fallback = 5,
+): number {
+ if (deployment?.enabled === false || effective?.enabled === false) {
+ return 0;
+ }
+ const ceiling = deployment?.maxPerUser ?? fallback;
+ const requested = effective?.maxPerUser ?? ceiling;
+ if (
+ !Number.isSafeInteger(ceiling) ||
+ !Number.isSafeInteger(requested) ||
+ ceiling < 0 ||
+ requested < 0
+ ) {
+ return 0;
+ }
+ return Math.min(ceiling, requested);
+}
diff --git a/packages/api/src/code/environments.integration.spec.ts b/packages/api/src/code/environments.integration.spec.ts
index 4672c1a30c..e869a35a12 100644
--- a/packages/api/src/code/environments.integration.spec.ts
+++ b/packages/api/src/code/environments.integration.spec.ts
@@ -280,39 +280,45 @@ describe('code environment registry', () => {
singleSpy.mockRestore();
});
- test('atomically limits concurrent environment registrations for one owner', async () => {
- await mongoose.models.CodeEnvironment.createCollection();
- await expect(mongoose.models.CodeEnvironment.collection.indexes()).resolves.toEqual([
- expect.objectContaining({ name: '_id_' }),
- ]);
- const registry = createCodeEnvironmentRegistry(mongoose);
- const ownerId = new Types.ObjectId();
-
- const results = await Promise.allSettled(
- ['quota-one', 'quota-two', 'quota-three'].map((id) =>
- registry.register({
- actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
- environment: {
- id,
- name: id,
- type: 'attached',
- baseURL: 'https://code.example.com',
- controlPlaneId: 'shared-code-api',
- },
- maxOwned: 2,
- } as never),
- ),
- );
+ test.each([2, 12])(
+ 'atomically limits concurrent registrations to %i across replicas',
+ async (maxOwned) => {
+ await mongoose.models.CodeEnvironment.createCollection();
+ await expect(mongoose.models.CodeEnvironment.collection.indexes()).resolves.toEqual([
+ expect.objectContaining({ name: '_id_' }),
+ ]);
+ const registries = [
+ createCodeEnvironmentRegistry(mongoose),
+ createCodeEnvironmentRegistry(mongoose),
+ ];
+ const ownerId = new Types.ObjectId();
+
+ const results = await Promise.allSettled(
+ Array.from({ length: maxOwned + 4 }, (_, index) =>
+ registries[index % registries.length].register({
+ actor: { userId: ownerId, role: 'USER', idOnTheSource: null },
+ environment: {
+ id: `quota-${index}`,
+ name: `quota-${index}`,
+ type: 'attached',
+ baseURL: 'https://code.example.com',
+ controlPlaneId: 'shared-code-api',
+ },
+ maxOwned,
+ } as never),
+ ),
+ );
- expect(results.filter(({ status }) => status === 'fulfilled')).toHaveLength(2);
- expect(results.filter(({ status }) => status === 'rejected')).toHaveLength(1);
- expect(results.find(({ status }) => status === 'rejected')).toMatchObject({
- reason: { name: 'CodeEnvironmentLimitError' },
- });
- await expect(
- mongoose.models.CodeEnvironment.countDocuments({ createdBy: ownerId }),
- ).resolves.toBe(2);
- });
+ expect(results.filter(({ status }) => status === 'fulfilled')).toHaveLength(maxOwned);
+ expect(results.filter(({ status }) => status === 'rejected')).toHaveLength(4);
+ expect(results.find(({ status }) => status === 'rejected')).toMatchObject({
+ reason: { name: 'CodeEnvironmentLimitError' },
+ });
+ await expect(
+ mongoose.models.CodeEnvironment.countDocuments({ createdBy: ownerId }),
+ ).resolves.toBe(maxOwned);
+ },
+ );
test('keeps a user-bound worker private even if its ACL is granted to a role', async () => {
const registry = createCodeEnvironmentRegistry(mongoose);
diff --git a/packages/api/src/code/http.spec.ts b/packages/api/src/code/http.spec.ts
index b0a16caffe..33b1eb0ddb 100644
--- a/packages/api/src/code/http.spec.ts
+++ b/packages/api/src/code/http.spec.ts
@@ -330,109 +330,151 @@ describe('code environment HTTP handlers', () => {
});
});
- test('pairs a generated worker to the authenticated user and persists its private route', async () => {
- const register = jest.fn().mockResolvedValue({
- resourceId: '68b2f0c498f24c1e78fa0111',
- id: 'code-generated',
- name: 'Personal VM',
- type: 'attached',
- });
- const fetchImpl = jest.fn().mockResolvedValue({
- ok: true,
- json: jest.fn().mockResolvedValue({
- protocolVersion: 1,
- workerId: 'code-generated',
- code: 'a'.repeat(32),
- expiresAt: new Date(Date.now() + 60_000).toISOString(),
- }),
- });
- const appConfig = {
- endpoints: {
- [EModelEndpoint.agents]: {
- statefulCodeSessions: {
- allowedEnvironments: ['user'],
- environments: [
- {
- id: 'shared-code-api',
- name: 'Shared Code API',
- type: 'attached',
- baseURL: 'https://code.librechat.example/v1',
- owner: 'deployment',
- pairing: {
- allowPrincipalWorkers: true,
- tokenEnv: 'CODE_ADMIN_TOKEN',
+ test.each([
+ [undefined, undefined, 5],
+ [{ maxPerUser: 100 }, { maxPerUser: 100 }, 100],
+ [{ maxPerUser: 100 }, { maxPerUser: 20 }, 20],
+ [{ maxPerUser: 10 }, { maxPerUser: 100 }, 10],
+ [{ enabled: false }, { enabled: true }, 0],
+ [{ maxPerUser: 10 }, { maxPerUser: 0 }, 0],
+ ])(
+ 'pairs with deployment %j and effective policy %j (limit %i)',
+ async (deployment, effective, limit) => {
+ const register = jest.fn().mockResolvedValue({
+ resourceId: '68b2f0c498f24c1e78fa0111',
+ id: 'code-generated',
+ name: 'Personal VM',
+ type: 'attached',
+ });
+ const fetchImpl = jest.fn().mockResolvedValue({
+ ok: true,
+ json: jest.fn().mockResolvedValue({
+ protocolVersion: 1,
+ workerId: 'code-generated',
+ code: 'a'.repeat(32),
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ }),
+ });
+ const appConfig = {
+ endpoints: {
+ [EModelEndpoint.agents]: {
+ statefulCodeSessions: {
+ allowedEnvironments: ['user'],
+ environments: [
+ {
+ id: 'shared-code-api',
+ name: 'Shared Code API',
+ type: 'attached',
+ baseURL: 'https://code.librechat.example/v1',
+ owner: 'deployment',
+ pairing: {
+ allowPrincipalWorkers: true,
+ tokenEnv: 'CODE_ADMIN_TOKEN',
+ },
},
- },
- ],
+ ],
+ },
},
},
- },
- } as AppConfig;
- const handlers = createCodeEnvironmentHttpHandlers({
- getAppConfig: jest.fn().mockResolvedValue(appConfig),
- registry: { register, listAccessible: jest.fn(), remove: jest.fn() },
- createEnvironmentId: () => 'code-generated',
- readSecret: jest.fn(() => 'administrator-token'),
- resolveTenantId: jest.fn(() => 'tenant-1'),
- principalAuthEnabled: jest.fn(() => true),
- principalAuthReady: jest.fn(),
- fetchImpl,
- });
- const req = {
- user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
- body: {
- name: 'Personal VM',
- controlPlaneId: 'shared-code-api',
- workerId: 'attacker-worker',
- baseURL: 'https://attacker.example',
- },
- };
- const res = response();
-
- await handlers.pair(req as never, res as never);
-
- expect(res.statusCode).toBe(201);
- expect(fetchImpl).toHaveBeenCalledWith(
- 'https://code.librechat.example/v1/bridge/pairings',
- expect.objectContaining({
- method: 'POST',
- headers: expect.objectContaining({ Authorization: 'Bearer administrator-token' }),
- body: JSON.stringify({
+ } as AppConfig;
+ const handlers = createCodeEnvironmentHttpHandlers({
+ getAppConfig: jest.fn(
+ async (options) =>
+ ({
+ ...appConfig,
+ endpoints: {
+ ...appConfig.endpoints,
+ agents: {
+ ...appConfig.endpoints?.agents,
+ statefulCodeSessions: {
+ ...appConfig.endpoints?.agents?.statefulCodeSessions,
+ principalWorkers: options?.baseOnly ? deployment : effective,
+ },
+ },
+ },
+ }) as AppConfig,
+ ),
+ registry: {
+ register,
+ listAccessible: jest.fn().mockResolvedValue([{ id: 'existing-machine' }]),
+ remove: jest.fn(),
+ },
+ createEnvironmentId: () => 'code-generated',
+ readSecret: jest.fn(() => 'administrator-token'),
+ resolveTenantId: jest.fn(() => 'tenant-1'),
+ principalAuthEnabled: jest.fn(() => true),
+ principalAuthReady: jest.fn(),
+ fetchImpl,
+ });
+ const req = {
+ user: { id: '68b2f0c498f24c1e78fa0001', role: 'USER' },
+ body: {
+ name: 'Personal VM',
+ controlPlaneId: 'shared-code-api',
+ workerId: 'attacker-worker',
+ baseURL: 'https://attacker.example',
+ },
+ };
+ const res = response();
+
+ await handlers.pair(req as never, res as never);
+
+ if (limit === 0) {
+ expect(res.statusCode).toBe(403);
+ expect(fetchImpl).not.toHaveBeenCalled();
+ expect(register).not.toHaveBeenCalled();
+ const discovery = response();
+ await handlers.list(req as never, discovery as never);
+ expect(discovery.statusCode).toBe(200);
+ expect(discovery.body).toEqual({
+ environments: [{ id: 'existing-machine' }],
+ controlPlanes: [],
+ });
+ return;
+ }
+ expect(res.statusCode).toBe(201);
+ expect(fetchImpl).toHaveBeenCalledWith(
+ 'https://code.librechat.example/v1/bridge/pairings',
+ expect.objectContaining({
+ method: 'POST',
+ headers: expect.objectContaining({ Authorization: 'Bearer administrator-token' }),
+ body: JSON.stringify({
+ workerId: 'code-generated',
+ binding: {
+ tenantId: 'tenant-1',
+ principal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
+ },
+ }),
+ }),
+ );
+ expect(register).toHaveBeenCalledWith({
+ actor: {
+ userId: '68b2f0c498f24c1e78fa0001',
+ role: 'USER',
+ idOnTheSource: null,
+ },
+ maxOwned: limit,
+ environment: {
+ id: 'code-generated',
+ name: 'Personal VM',
+ type: 'attached' as const,
+ baseURL: 'https://code.librechat.example/v1',
workerId: 'code-generated',
- binding: {
- tenantId: 'tenant-1',
- principal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
- },
+ controlPlaneId: 'shared-code-api',
+ revocationTokenEnv: 'CODE_ADMIN_TOKEN',
+ workerPrincipal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
+ },
+ });
+ expect(res.body).toEqual({
+ environment: expect.objectContaining({ id: 'code-generated' }),
+ pairing: expect.objectContaining({
+ workerId: 'code-generated',
+ code: 'a'.repeat(32),
+ endpoint: 'https://code.librechat.example/v1',
}),
- }),
- );
- expect(register).toHaveBeenCalledWith({
- actor: {
- userId: '68b2f0c498f24c1e78fa0001',
- role: 'USER',
- idOnTheSource: null,
- },
- maxOwned: 5,
- environment: {
- id: 'code-generated',
- name: 'Personal VM',
- type: 'attached' as const,
- baseURL: 'https://code.librechat.example/v1',
- workerId: 'code-generated',
- controlPlaneId: 'shared-code-api',
- revocationTokenEnv: 'CODE_ADMIN_TOKEN',
- workerPrincipal: { type: 'user', id: '68b2f0c498f24c1e78fa0001' },
- },
- });
- expect(res.body).toEqual({
- environment: expect.objectContaining({ id: 'code-generated' }),
- pairing: expect.objectContaining({
- workerId: 'code-generated',
- code: 'a'.repeat(32),
- endpoint: 'https://code.librechat.example/v1',
- }),
- });
- });
+ });
+ },
+ );
test('revokes an upstream pairing when the atomic owner quota is exhausted', async () => {
const fetchImpl = jest.fn(
diff --git a/packages/api/src/code/http.ts b/packages/api/src/code/http.ts
index 3c99ed3364..1c1610e331 100644
--- a/packages/api/src/code/http.ts
+++ b/packages/api/src/code/http.ts
@@ -37,6 +37,7 @@ import {
CodeEnvironmentSettingsValidationError,
validateCodeEnvironmentUserSettings,
} from './settings';
+import { resolveCodeWorkerEnrollmentLimit } from './enrollment';
import { getAppConfigOptionsFromUser } from '~/app/service';
type Registry = {
@@ -196,7 +197,6 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
const principalAuthEnabled = deps.principalAuthEnabled ?? isCodeApiJwtAuthEnabled;
const principalAuthReady = deps.principalAuthReady ?? assertCodeApiJwtSigningReady;
const principalIsActive = deps.principalIsActive ?? (async () => true);
- const maxPrincipalEnvironments = deps.maxPrincipalEnvironments ?? 5;
async function list(req: ServerRequest, res: Response): Promise<Response> {
const principal = actor(req);
@@ -205,10 +205,11 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
}
let details: AccessibleCodeEnvironmentDetails;
let appConfig: AppConfig;
+ let deploymentConfig: AppConfig;
try {
const principals = await deps.registry.resolvePrincipals?.(principal);
const resolvedPrincipal = principals == null ? principal : { ...principal, principals };
- [details, appConfig] = await Promise.all([
+ [details, appConfig, deploymentConfig] = await Promise.all([
deps.registry.listAccessibleDetails?.(resolvedPrincipal) ??
Promise.all([
deps.registry.listAccessible(resolvedPrincipal),
@@ -220,6 +221,7 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
failClosed: true,
skipRuntimeAugmentation: true,
}),
+ deps.getAppConfig({ baseOnly: true }),
]);
} catch (error) {
logger.error('[codeEnvironments] discovery policy resolution failed:', error);
@@ -241,7 +243,15 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
settings: configuration?.settings,
};
}),
- controlPlanes: principalAuthEnabled() ? principalControlPlanes(appConfig) : [],
+ controlPlanes:
+ principalAuthEnabled() &&
+ resolveCodeWorkerEnrollmentLimit(
+ deploymentConfig.endpoints?.agents?.statefulCodeSessions?.principalWorkers,
+ appConfig.endpoints?.agents?.statefulCodeSessions?.principalWorkers,
+ deps.maxPrincipalEnvironments,
+ ) > 0
+ ? principalControlPlanes(appConfig)
+ : [],
});
}
@@ -395,6 +405,14 @@ export function createCodeEnvironmentHttpHandlers(deps: CodeEnvironmentHttpDeps)
if (authorizedControlPlane == null || controlPlane == null) {
return res.status(404).json({ error: 'Principal code control plane was not found' });
}
+ const maxPrincipalEnvironments = resolveCodeWorkerEnrollmentLimit(
+ deploymentConfig.endpoints?.agents?.statefulCodeSessions?.principalWorkers,
+ effectiveConfig.endpoints?.agents?.statefulCodeSessions?.principalWorkers,
+ deps.maxPrincipalEnvironments,
+ );
+ if (maxPrincipalEnvironments === 0) {
+ return res.status(403).json({ error: 'Personal code worker enrollment is disabled' });
+ }
const tokenEnv = controlPlane.pairing?.tokenEnv;
const token = tokenEnv != null ? readSecret(tokenEnv)?.trim() : undefined;
if (!token) {
diff --git a/packages/data-provider/specs/config-schemas.spec.ts b/packages/data-provider/specs/config-schemas.spec.ts
index 4e6eb14049..d9f14ead77 100644
--- a/packages/data-provider/specs/config-schemas.spec.ts
+++ b/packages/data-provider/specs/config-schemas.spec.ts
@@ -449,6 +449,28 @@ describe('agentsEndpointSchema', () => {
expect(result.success).toBe(true);
});
+ it.each([0, 5, 1000])('accepts a personal worker ceiling of %i', (maxPerUser) => {
+ const principalWorkers = { enabled: true, maxPerUser };
+ const result = agentsEndpointSchema.parse({
+ statefulCodeSessions: { allowedEnvironments: ['user'], principalWorkers },
+ });
+ expect(result.statefulCodeSessions?.principalWorkers).toEqual(principalWorkers);
+ });
+
+ it.each([-1, 0.5, Infinity, Number.MAX_SAFE_INTEGER + 1])(
+ 'rejects invalid personal worker ceiling %s',
+ (maxPerUser) => {
+ expect(
+ agentsEndpointSchema.safeParse({
+ statefulCodeSessions: {
+ allowedEnvironments: ['user'],
+ principalWorkers: { maxPerUser },
+ },
+ }).success,
+ ).toBe(false);
+ },
+ );
+
it('accepts uniquely named execution environments with exactly one default', () => {
const result = agentsEndpointSchema.safeParse({
statefulCodeSessions: {
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index f7a7989e49..89b3865cae 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -1147,6 +1147,10 @@ export const codeEnvironmentUserSettingsSchema = z
export type CodeEnvironmentUserSettings = z.infer<typeof codeEnvironmentUserSettingsSchema>;
+export type CodeWorkerEnrollmentPolicy = NonNullable<
+ NonNullable<z.infer<typeof agentsEndpointSchema>['statefulCodeSessions']>['principalWorkers']
+>;
+
export const agentsEndpointSchema = baseEndpointSchema
.omit({ baseURL: true })
.merge(
@@ -1187,6 +1191,15 @@ export const agentsEndpointSchema = baseEndpointSchema
statefulCodeSessions: z
.object({
allowedEnvironments: z.array(z.enum(STATEFUL_CODE_ENVIRONMENTS)).min(1),
+ /** Server-only personal worker enrollment policy. Effective principal
+ * policy may tighten, but never raise, the deployment ceiling. */
+ principalWorkers: z
+ .object({
+ enabled: z.boolean().optional(),
+ /** Defaults to five. Zero disables enrollment; existing machines remain usable. */
+ maxPerUser: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
+ })
+ .optional(),
/** Operator-managed execution environments. Attached entries route to a
* Code API deployment backed by an outbound librechat-code worker. */
environments: z