Core concepts

A handful of terms recur throughout the API and the configuration. Getting them straight early saves a lot of confusion later, because two of them are spelled similarly and mean different things.

Executions and sessions

Every call to /v1/exec is one execution. The service mints a fresh session_id for it and returns that id in the response.

That id does double duty:

1. It identifies the execution.
2. It is the storage prefix for any files the run produced.

So when you want to download an artifact from a run, the session_id you got back from /v1/exec is the path segment you use:

GET /v1/download/{session_id}/{fileId}

session_id versus storage_session_id

These are different, and the distinction matters when you pass files into a run.

A file you uploaded earlier lives under the storage_session_id the upload returned. When you reference it on a later /exec call, you pass that value: not the id of the execution you are about to start.

The sessionKey, and why you never send one

Storage is namespaced by a value called the sessionKey. You never construct it, never send it, and never see it.

The service derives it server-side from the authenticated principal and the resource a file belongs to. Since it is derived rather than supplied, a caller cannot address another caller's namespace by guessing or forging an id: there is no field in which to forge it. It is also bound into the signed execution manifest, so the sandbox cannot widen its own access after the fact.

File kinds

Every file belongs to a resource, and the kind field says which. This is what decides the namespace the sessionKey derives:

version is required when kind is skill and rejected for the other kinds. Because a skill's version counter is monotonic, editing a skill naturally invalidates the previous cache entry: the new version derives a different sessionKey.

Outputs are always user-scoped, regardless of the kinds of the inputs. A run that reads a shared skill bundle still writes its results into the requesting user's private namespace.

The workspace

Inside the sandbox, code runs in /mnt/data. That directory is:

• Fresh for every execution by default: created, used, destroyed.
• Writable, unlike almost everything else in the sandbox.
• Where input files are staged, under the name you gave them.
• Where output files are collected from when the run finishes.

If you enable persistent sessions, /mnt/data carries over between runs for the same caller instead of being discarded.

Principals and identity

A principal is the authenticated caller. Depending on how you configure authentication, it comes from:

• the verified claims of a LibreChat-signed JWT (the production path), or
• the User-Id header, then the body's user_id, then anonymous, when CODEAPI_AUTH_PROVIDER=none, or
• a fixed local principal, when LOCAL_MODE=true.

The principal is what the sessionKey derives from, so it is the boundary between one user's files and another's.

What "isolated" means here

Isolation is layered, and how much you get depends on one setting.

In both modes the sandbox has no network access. Everything it needs from the outside (reading input files, writing outputs, calling tools) goes through the egress gateway, which enforces a signed, scoped capability naming exactly which objects that specific run may touch.

Components at a glance

The stack is several independently scalable services rather than one process:

Plus Redis (job queue and session pointers) and S3-compatible storage (MinIO locally). See Architecture for how they fit together.