Secure, Fast, and Extensible Sandbox runtime for AI agents.
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
import {
PoolDestroyedException,
PoolStateStoreUnavailableException,
} from "./core/exceptions.js";
import {
PoolDestroyState,
type IdleEntry,
type PoolStateStore,
type ReapResult,
type StoreCounters,
type TakeIdleResult,
} from "./poolTypes.js";
/** Minimal surface implemented by node-redis and compatible Redis clients. */
export interface RedisPoolClient {
sendCommand(command: string[]): Promise<unknown>;
}
export interface RedisPoolStateStoreOptions {
client: RedisPoolClient;
keyPrefix?: string;
}
const DEFAULT_IDLE_TTL_MILLIS = 24 * 60 * 60 * 1000;
const FENCED_WRITE_REJECTED = -1;
/** Redis-backed distributed pool state. The caller owns the Redis client lifecycle. */
export class RedisPoolStateStore implements PoolStateStore {
static readonly DEFAULT_KEY_PREFIX = "opensandbox:pool";
private readonly client: RedisPoolClient;
private readonly keyPrefix: string;
constructor(options: RedisPoolStateStoreOptions) {
if (!options?.client) throw new Error("client is required");
this.client = options.client;
this.keyPrefix = options.keyPrefix ?? RedisPoolStateStore.DEFAULT_KEY_PREFIX;
}
async tryTakeIdle(poolName: string): Promise<string | undefined> {
return (await this.tryTakeIdleWithMinTtl(poolName, 0)).sandboxId;
}
async tryTakeIdleWithMinTtl(
poolName: string,
minRemainingTtlSeconds: number,
): Promise<TakeIdleResult> {
requireNonNegative(minRemainingTtlSeconds, "minRemainingTtlSeconds");
return await this.execute("tryTakeIdle", poolName, async () => {
const result = await this.eval(
TAKE_IDLE_SCRIPT,
[this.key(poolName, "idle:list"), this.key(poolName, "idle:expires")],
[String(Math.max(0, Math.floor(minRemainingTtlSeconds * 1000)))],
);
return decodeTakeIdleResult(result);
});
}
async putIdle(poolName: string, sandboxId: string): Promise<void> {
if (!sandboxId.trim()) throw new Error("sandboxId must not be blank");
await this.execute("putIdle", poolName, async () => {
const ttlRaw = await this.client.sendCommand(["GET", this.key(poolName, "idleTtlMillis")]);
const ttlMillis = parseInteger(ttlRaw) ?? DEFAULT_IDLE_TTL_MILLIS;
await this.evalFencedWrite(
"putIdle",
poolName,
PUT_IDLE_SCRIPT,
[
this.key(poolName, "idle:list"),
this.key(poolName, "idle:expires"),
this.key(poolName, "destroy:state"),
],
[sandboxId, String(Math.max(1, ttlMillis))],
);
});
}
async removeIdle(poolName: string, sandboxId: string): Promise<void> {
await this.execute("removeIdle", poolName, async () => {
await this.client.sendCommand(["HDEL", this.key(poolName, "idle:expires"), sandboxId]);
await this.client.sendCommand(["LREM", this.key(poolName, "idle:list"), "0", sandboxId]);
});
}
async tryAcquirePrimaryLock(poolName: string, ownerId: string, ttlSeconds: number): Promise<boolean> {
validateOwnerAndTtl(ownerId, ttlSeconds);
return await this.execute("tryAcquirePrimaryLock", poolName, async () =>
isOne(await this.eval(
ACQUIRE_LOCK_SCRIPT,
[this.key(poolName, "lock"), this.key(poolName, "destroy:state")],
[ownerId, String(Math.max(1, Math.floor(ttlSeconds * 1000)))],
)),
);
}
async renewPrimaryLock(poolName: string, ownerId: string, ttlSeconds: number): Promise<boolean> {
validateOwnerAndTtl(ownerId, ttlSeconds);
return await this.execute("renewPrimaryLock", poolName, async () =>
isOne(await this.eval(
RENEW_LOCK_SCRIPT,
[this.key(poolName, "lock"), this.key(poolName, "destroy:state")],
[ownerId, String(Math.max(1, Math.floor(ttlSeconds * 1000)))],
)),
);
}
async releasePrimaryLock(poolName: string, ownerId: string): Promise<void> {
await this.execute("releasePrimaryLock", poolName, async () => {
await this.eval(RELEASE_LOCK_SCRIPT, [this.key(poolName, "lock")], [ownerId]);
});
}
async reapExpiredIdle(poolName: string, _now: Date): Promise<void> {
await this.reapExpiredIdleWithMinTtl(poolName, _now, 0);
}
async reapExpiredIdleWithMinTtl(
poolName: string,
_now: Date,
minRemainingTtlSeconds: number,
): Promise<ReapResult> {
requireNonNegative(minRemainingTtlSeconds, "minRemainingTtlSeconds");
return await this.execute("reapExpiredIdle", poolName, async () => {
const result = await this.eval(
REAP_EXPIRED_SCRIPT,
[this.key(poolName, "idle:list"), this.key(poolName, "idle:expires")],
[String(Math.max(0, Math.floor(minRemainingTtlSeconds * 1000)))],
);
return { discardedAliveSandboxIds: asArray(result).map(asString) };
});
}
async snapshotCounters(poolName: string): Promise<StoreCounters> {
return await this.execute("snapshotCounters", poolName, async () => ({
idleCount: parseInteger(await this.client.sendCommand(["HLEN", this.key(poolName, "idle:expires")])) ?? 0,
}));
}
async snapshotIdleEntries(poolName: string): Promise<IdleEntry[]> {
return await this.execute("snapshotIdleEntries", poolName, async () => {
const ids = asArray(await this.client.sendCommand(["LRANGE", this.key(poolName, "idle:list"), "0", "-1"]))
.map(asString);
const rawExpires = asArray(await this.client.sendCommand(["HGETALL", this.key(poolName, "idle:expires")]));
const expires = new Map<string, number>();
for (let index = 0; index + 1 < rawExpires.length; index += 2) {
const value = parseInteger(rawExpires[index + 1]);
if (value !== undefined) expires.set(asString(rawExpires[index]), value);
}
return ids.flatMap((sandboxId) => {
const expiresAt = expires.get(sandboxId);
return expiresAt === undefined ? [] : [{ sandboxId, expiresAt: new Date(expiresAt) }];
});
});
}
async getMaxIdle(poolName: string): Promise<number | undefined> {
return await this.execute("getMaxIdle", poolName, async () =>
parseInteger(await this.client.sendCommand(["GET", this.key(poolName, "maxIdle")])),
);
}
async setMaxIdle(poolName: string, maxIdle: number): Promise<void> {
if (!Number.isInteger(maxIdle) || maxIdle < 0) throw new Error("maxIdle must be a non-negative integer");
await this.execute("setMaxIdle", poolName, async () => {
await this.evalFencedWrite(
"setMaxIdle",
poolName,
SET_VALUE_SCRIPT,
[this.key(poolName, "maxIdle"), this.key(poolName, "destroy:state")],
[String(maxIdle)],
);
});
}
async setIdleEntryTtl(poolName: string, ttlSeconds: number): Promise<void> {
requirePositive(ttlSeconds, "ttlSeconds");
await this.execute("setIdleEntryTtl", poolName, async () => {
await this.evalFencedWrite(
"setIdleEntryTtl",
poolName,
SET_VALUE_SCRIPT,
[this.key(poolName, "idleTtlMillis"), this.key(poolName, "destroy:state")],
[String(Math.max(1, Math.floor(ttlSeconds * 1000)))],
);
});
}
async getDestroyState(poolName: string): Promise<PoolDestroyState> {
return await this.execute("getDestroyState", poolName, async () => {
const state = asOptionalString(await this.client.sendCommand(["GET", this.key(poolName, "destroy:state")]));
if (state === PoolDestroyState.DESTROYING) return PoolDestroyState.DESTROYING;
if (state === PoolDestroyState.DESTROYED) return PoolDestroyState.DESTROYED;
return PoolDestroyState.ACTIVE;
});
}
async beginDestroy(poolName: string, ownerId: string): Promise<void> {
if (!ownerId.trim()) throw new Error("ownerId must not be blank");
await this.execute("beginDestroy", poolName, async () => {
const result = await this.eval(
BEGIN_DESTROY_SCRIPT,
[this.key(poolName, "destroy:state"), this.key(poolName, "destroy:owner")],
[PoolDestroyState.DESTROYING, PoolDestroyState.DESTROYED, ownerId],
);
if (parseInteger(result) === FENCED_WRITE_REJECTED) {
throw new PoolDestroyedException(poolName, PoolDestroyState.DESTROYED);
}
});
}
async clearPoolState(poolName: string): Promise<void> {
await this.execute("clearPoolState", poolName, async () => {
await this.client.sendCommand([
"DEL",
this.key(poolName, "idle:list"),
this.key(poolName, "idle:expires"),
this.key(poolName, "lock"),
this.key(poolName, "maxIdle"),
this.key(poolName, "idleTtlMillis"),
]);
});
}
async markDestroyed(
poolName: string,
ownerId: string,
tombstoneTtlSeconds?: number | null,
): Promise<void> {
if (!ownerId.trim()) throw new Error("ownerId must not be blank");
if (tombstoneTtlSeconds != null) requirePositive(tombstoneTtlSeconds, "tombstoneTtlSeconds");
await this.execute("markDestroyed", poolName, async () => {
const stateCommand = ["SET", this.key(poolName, "destroy:state"), PoolDestroyState.DESTROYED];
const ownerCommand = ["SET", this.key(poolName, "destroy:owner"), ownerId];
if (tombstoneTtlSeconds != null) {
const ttlMillis = String(Math.max(1, Math.floor(tombstoneTtlSeconds * 1000)));
stateCommand.push("PX", ttlMillis);
ownerCommand.push("PX", ttlMillis);
}
await this.client.sendCommand(stateCommand);
await this.client.sendCommand(ownerCommand);
});
}
private async eval(script: string, keys: string[], args: string[]): Promise<unknown> {
return await this.client.sendCommand(["EVAL", script, String(keys.length), ...keys, ...args]);
}
private async evalFencedWrite(
operation: string,
poolName: string,
script: string,
keys: string[],
args: string[],
): Promise<void> {
const result = await this.eval(script, keys, args);
if (parseInteger(result) === FENCED_WRITE_REJECTED) {
throw new PoolDestroyedException(poolName, await this.getDestroyState(poolName));
}
void operation;
}
private key(poolName: string, suffix: string): string {
if (!poolName.trim()) throw new Error("poolName must not be blank");
const bytes = new TextEncoder().encode(poolName);
const encoded = btoa(String.fromCharCode(...bytes))
.replaceAll("+", "-")
.replaceAll("/", "_")
.replace(/=+$/, "");
return `${this.keyPrefix}:{${encoded}}:${suffix}`;
}
private async execute<T>(operation: string, poolName: string, call: () => Promise<T>): Promise<T> {
try {
return await call();
} catch (cause) {
if (cause instanceof PoolDestroyedException || cause instanceof PoolStateStoreUnavailableException) throw cause;
throw new PoolStateStoreUnavailableException(`${operation} poolName=${poolName}`, cause);
}
}
}
function decodeTakeIdleResult(value: unknown): TakeIdleResult {
if (value == null) return { discardedAliveSandboxIds: [] };
if (!Array.isArray(value)) return { sandboxId: asString(value), discardedAliveSandboxIds: [] };
const taken = value.length > 0 ? asString(value[0]) : "";
const discarded = value.length > 1 ? asArray(value[1]).map(asString) : [];
return { sandboxId: taken || undefined, discardedAliveSandboxIds: discarded };
}
function asArray(value: unknown): unknown[] {
return Array.isArray(value) ? value : [];
}
function asOptionalString(value: unknown): string | undefined {
return value == null ? undefined : asString(value);
}
function asString(value: unknown): string {
if (typeof value === "string") return value;
if (value instanceof Uint8Array) return new TextDecoder().decode(value);
return String(value);
}
function parseInteger(value: unknown): number | undefined {
if (value == null) return undefined;
const parsed = Number(asString(value));
return Number.isSafeInteger(parsed) ? parsed : undefined;
}
function isOne(value: unknown): boolean {
return parseInteger(value) === 1;
}
function validateOwnerAndTtl(ownerId: string, ttlSeconds: number): void {
if (!ownerId.trim()) throw new Error("ownerId must not be blank");
requirePositive(ttlSeconds, "ttlSeconds");
}
function requireNonNegative(value: number, name: string): void {
if (!Number.isFinite(value) || value < 0) throw new Error(`${name} must be non-negative`);
}
function requirePositive(value: number, name: string): void {
if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be positive`);
}
const TAKE_IDLE_SCRIPT = `
local redis_time = redis.call('TIME')
local now_ms = tonumber(redis_time[1]) * 1000 + math.floor(tonumber(redis_time[2]) / 1000)
local min_remaining_ttl_ms = tonumber(ARGV[1]) or 0
local cutoff_ms = now_ms + min_remaining_ttl_ms
local discarded_alive = {}
while true do
local sandbox_id = redis.call('LPOP', KEYS[1])
if not sandbox_id then
if #discarded_alive == 0 then return nil end
return {'', discarded_alive}
end
local expires_at = redis.call('HGET', KEYS[2], sandbox_id)
if expires_at then
redis.call('HDEL', KEYS[2], sandbox_id)
local exp = tonumber(expires_at)
if exp > cutoff_ms then return {sandbox_id, discarded_alive} end
if exp > now_ms then table.insert(discarded_alive, sandbox_id) end
end
end`;
const PUT_IDLE_SCRIPT = `
if redis.call('GET', KEYS[3]) then return -1 end
local redis_time = redis.call('TIME')
local now_ms = tonumber(redis_time[1]) * 1000 + math.floor(tonumber(redis_time[2]) / 1000)
local expires_at = now_ms + tonumber(ARGV[2])
local current_expires_at = redis.call('HGET', KEYS[2], ARGV[1])
if current_expires_at and tonumber(current_expires_at) > now_ms then return 0 end
if not current_expires_at then redis.call('RPUSH', KEYS[1], ARGV[1]) end
redis.call('HSET', KEYS[2], ARGV[1], expires_at)
return 1`;
const ACQUIRE_LOCK_SCRIPT = `
if redis.call('GET', KEYS[2]) then return 0 end
if redis.call('SET', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then return 1 end
if redis.call('GET', KEYS[1]) == ARGV[1] then
redis.call('PEXPIRE', KEYS[1], ARGV[2])
return 1
end
return 0`;
const RENEW_LOCK_SCRIPT = `
if redis.call('GET', KEYS[2]) then return 0 end
if redis.call('GET', KEYS[1]) == ARGV[1] then
redis.call('PEXPIRE', KEYS[1], ARGV[2])
return 1
end
return 0`;
const SET_VALUE_SCRIPT = `
if redis.call('GET', KEYS[2]) then return -1 end
redis.call('SET', KEYS[1], ARGV[1])
return 1`;
const BEGIN_DESTROY_SCRIPT = `
local destroy_state = redis.call('GET', KEYS[1])
if destroy_state == ARGV[2] then return -1 end
redis.call('SET', KEYS[1], ARGV[1])
redis.call('SET', KEYS[2], ARGV[3])
return 1`;
const RELEASE_LOCK_SCRIPT = `
if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end
return 0`;
const REAP_EXPIRED_SCRIPT = `
local redis_time = redis.call('TIME')
local now_ms = tonumber(redis_time[1]) * 1000 + math.floor(tonumber(redis_time[2]) / 1000)
local min_remaining_ttl_ms = tonumber(ARGV[1]) or 0
local cutoff_ms = now_ms + min_remaining_ttl_ms
local discarded_alive = {}
local entries = redis.call('HGETALL', KEYS[2])
for i = 1, #entries, 2 do
local sandbox_id = entries[i]
local exp = tonumber(entries[i + 1])
if exp <= cutoff_ms then
redis.call('HDEL', KEYS[2], sandbox_id)
redis.call('LREM', KEYS[1], 0, sandbox_id)
if exp > now_ms then table.insert(discarded_alive, sandbox_id) end
end
end
return discarded_alive`;