-
Notifications
You must be signed in to change notification settings - Fork 55
feat: add outbound stateful code bridge #66
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
+2,285
−54
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,6 @@ | ||
| data/ | ||
| node_modules | ||
| packages/*/dist/ | ||
| .env | ||
| .git | ||
| .npmrc | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| #include <errno.h> | ||
| #include <limits.h> | ||
| #include <stdio.h> | ||
| #include <stdlib.h> | ||
| #include <string.h> | ||
| #include <sys/mount.h> | ||
| #include <sys/stat.h> | ||
| #include <unistd.h> | ||
|
|
||
| static int bind_mount(const char *source, const char *target, int read_only) { | ||
| if (mount(source, target, NULL, MS_BIND | MS_REC, NULL) != 0) { | ||
| fprintf(stderr, "bind %s -> %s failed: %s\n", source, target, strerror(errno)); | ||
| return -1; | ||
| } | ||
|
|
||
| if (read_only && | ||
| mount(NULL, target, NULL, MS_BIND | MS_REMOUNT | MS_RDONLY, NULL) != 0) { | ||
| fprintf(stderr, "read-only remount of %s failed: %s\n", target, strerror(errno)); | ||
| return -1; | ||
| } | ||
|
|
||
| return 0; | ||
| } | ||
|
|
||
| static int bind_rootfs_path(const char *rootfs, const char *path) { | ||
| char source[PATH_MAX]; | ||
| int written = snprintf(source, sizeof(source), "%s%s", rootfs, path); | ||
| if (written < 0 || (size_t)written >= sizeof(source)) { | ||
| fprintf(stderr, "rootfs path is too long: %s%s\n", rootfs, path); | ||
| return -1; | ||
| } | ||
|
|
||
| return bind_mount(source, path, 1); | ||
| } | ||
|
|
||
| int main(int argc, char **argv) { | ||
| if (argc < 2) { | ||
| fprintf(stderr, "usage: sandbox-rootfs-setup ROOTFS [COMMAND ...]\n"); | ||
| return 2; | ||
| } | ||
|
|
||
| const char *rootfs = argv[1]; | ||
| if (rootfs[0] != '/') { | ||
| fprintf(stderr, "rootfs must be an absolute path\n"); | ||
| return 2; | ||
| } | ||
|
|
||
| if (mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL) != 0) { | ||
| fprintf(stderr, "making the mount namespace private failed: %s\n", strerror(errno)); | ||
| return 1; | ||
| } | ||
|
|
||
| if ((mkdir("/sandbox_api", 0755) != 0 && errno != EEXIST) || | ||
| (mkdir("/pkgs", 0755) != 0 && errno != EEXIST)) { | ||
| fprintf(stderr, "creating rootfs mount targets failed: %s\n", strerror(errno)); | ||
| return 1; | ||
| } | ||
|
|
||
| /* | ||
| * Keep this process statically linked: the final /usr mount replaces | ||
| * the Fedora launcher's dynamic userspace with the Debian sandbox rootfs. | ||
| * A shell cannot safely perform this sequence because its next command may | ||
| * try to load a host binary against guest libraries (or vice versa). | ||
| */ | ||
| const char *paths[] = {"/sandbox_api", "/pkgs"}; | ||
| for (size_t i = 0; i < sizeof(paths) / sizeof(paths[0]); i++) { | ||
| if (bind_rootfs_path(rootfs, paths[i]) != 0) { | ||
| return 1; | ||
| } | ||
| } | ||
|
|
||
| if (access("/host-packages", F_OK) == 0 && | ||
| bind_mount("/host-packages", "/pkgs", 0) != 0) { | ||
| fprintf(stderr, "warning: sandbox will run without host packages\n"); | ||
| } | ||
|
|
||
| /* Bind all guest userspace last, then immediately enter it. */ | ||
| if (bind_rootfs_path(rootfs, "/usr") != 0) { | ||
| return 1; | ||
| } | ||
|
|
||
| setenv("PATH", "/root/.bun/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", 1); | ||
| setenv("LD_LIBRARY_PATH", "/usr/lib/aarch64-linux-gnu:/usr/lib/x86_64-linux-gnu", 1); | ||
|
|
||
| setenv("NSJAIL_PATH", "/usr/sbin/nsjail", 1); | ||
|
|
||
| char *default_argv[] = {"/sandbox_api/entrypoint.sh", NULL}; | ||
| char **command_argv = argc > 2 ? &argv[2] : default_argv; | ||
| execv(command_argv[0], command_argv); | ||
| fprintf(stderr, "starting sandbox entrypoint failed: %s\n", strerror(errno)); | ||
| return 1; | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| # Remote Code Bridge | ||
|
|
||
| Remote Code Bridge makes an operator-owned VM a stateful Code API execution | ||
| environment without exposing that VM to inbound internet traffic. | ||
|
|
||
| ```text | ||
| LibreChat -> Code API -> Redis assignment | ||
| ^ | | ||
| | outbound v | ||
| @librechat/code -> local sandbox | ||
| ``` | ||
|
|
||
| Code API remains the public authentication, policy, manifest, timeout, and | ||
| result-normalization boundary. The bridge worker has a separate operator | ||
| credential and never accepts end-user bearer tokens directly. | ||
|
|
||
| ## Code API configuration | ||
|
|
||
| Run this as an isolated stateful Code API deployment: | ||
|
|
||
| ```dotenv | ||
| CODEAPI_SANDBOX_BACKEND=remote-bridge | ||
| CODEAPI_EXECUTION_PROFILE=stateful | ||
| CODEAPI_RUNTIME_SESSION_MODE=affinity | ||
| CODEAPI_BRIDGE_WORKER_ID=my-vm | ||
| CODEAPI_BRIDGE_TOKEN=<strong-random-secret> | ||
| ``` | ||
|
|
||
| Use `strict` instead of `affinity` if every request must include a runtime | ||
| session hint. In hardened mode, startup requires the bridge token to be at least | ||
| 32 bytes. `PTC_MODE=blocking` is rejected; replay mode is required because a | ||
| remote execution cannot retain an open Code API process across tool callbacks. | ||
|
|
||
| Start the CLI beside a sandbox using the same worker ID and secret; see | ||
| [`@librechat/code`](../../packages/code/README.md). | ||
| Stateful deployments must also set `LIBRECHAT_CODE_STATEFUL_WORKSPACE=true` | ||
| and route the CLI's `{runtimeSessionId}` endpoint template to an isolated, | ||
| persistent local runner per session. A single sandbox endpoint is stateless and | ||
| is rejected for runtime-session assignments. | ||
|
|
||
| ## LibreChat configuration | ||
|
|
||
| Expose the Code API deployment as an environment under the Agents endpoint: | ||
|
|
||
| ```yaml | ||
| endpoints: | ||
| agents: | ||
| statefulCodeSessions: | ||
| environments: | ||
| - id: my-vm | ||
| name: My VM | ||
| type: attached | ||
| baseURL: https://code.example.com/v1 | ||
| default: true | ||
| ``` | ||
|
|
||
| Agents may select this environment with `code_environment_id: my-vm`. | ||
| LibreChat derives a stable per-conversation runtime session ID, so commands in | ||
| later turns reuse the same workspace. Attached environments deliberately skip | ||
| background prewarming: the single worker lease is reserved for explicit user | ||
| execution. | ||
|
|
||
| ## Lifecycle and fencing | ||
|
|
||
| - Registration is ephemeral in Redis and must be refreshed by the worker. | ||
| - Code API permits one active assignment per configured worker. | ||
| - Each assignment has an absolute deadline, generation, and random lease token. | ||
| - Settlements with the wrong worker, generation, token, or expired deadline are | ||
| rejected. | ||
| - Request cancellation is polled by the worker and aborts the local sandbox | ||
| request. | ||
| - The sandbox receives the stable runtime session ID separately from the lease; | ||
| workspace state belongs to that session, not to a transient assignment. | ||
|
|
||
| ## Security boundaries | ||
|
|
||
| The bridge removes inbound VM exposure; it does not replace sandbox isolation. | ||
| For internet-facing LibreChat deployments, use the hardened microVM/NsJail | ||
| stack, default-deny sandbox egress, signed execution manifests, least-privilege | ||
| host credentials, resource limits, and host/network monitoring. Bind the local | ||
| sandbox endpoint to loopback or a private container network. Rotate a leaked | ||
| bridge token immediately; the initial protocol intentionally uses a static | ||
| operator secret and supports one configured worker per Code API deployment. | ||
|
|
||
| The next control-plane layer can add short-lived pairing credentials and a | ||
| multi-worker directory without changing the execution protocol or moving code | ||
| tools into the Agents SDK. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| FROM node:24-alpine AS build | ||
| WORKDIR /app | ||
| COPY package.json package-lock.json tsconfig.json ./ | ||
| RUN npm ci | ||
| COPY src ./src | ||
| RUN npm run build | ||
|
|
||
| FROM node:24-alpine | ||
| ENV NODE_ENV=production | ||
| RUN addgroup -S librechat-code && adduser -S librechat-code -G librechat-code | ||
| WORKDIR /app | ||
| COPY --from=build /app/package.json ./package.json | ||
| COPY --from=build /app/dist ./dist | ||
| USER librechat-code | ||
| ENTRYPOINT ["node", "dist/cli.js"] |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.