@codesoul-co/hypha-core / contracts/sandbox

• Package index: @codesoul-co/hypha-core
• Source: packages/core/src/contracts/sandbox.ts
• Exports: 20

Using this module

Use the Sandbox module for declaring and runtime-validating contracts. It exports 19 interfaces, 1 type.

Import from the package entrypoint

import type {
  ExecutionEnvironmentSpec,
  ExecutionImageSpec,
  ExecutionLoggingPolicySpec,
  NetworkPolicySpec,
  ProcessPolicySpec,
  ResourceLimitSpec,
  SandboxCleanupRequest,
  SandboxCreateRequest,
} from '@codesoul-co/hypha-core';

// The complete export list is documented below.

Usage patterns

• Use the 20 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.

Public exports

Symbol	Kind	Signature	Description
ExecutionEnvironmentSpec	interface	interface ExecutionEnvironmentSpec extends VersionedSpec, SpecMetadata	Execution Environment Spec interface with 23 public fields or methods.
ExecutionImageSpec	interface	interface ExecutionImageSpec	Execution Image Spec interface with 8 public fields or methods.
ExecutionLoggingPolicySpec	interface	interface ExecutionLoggingPolicySpec	Execution Logging Policy Spec interface with 7 public fields or methods.
NetworkPolicySpec	interface	interface NetworkPolicySpec	Network Policy Spec interface with 16 public fields or methods.
ProcessPolicySpec	interface	interface ProcessPolicySpec	Process Policy Spec interface with 17 public fields or methods.
ResourceLimitSpec	interface	interface ResourceLimitSpec	Resource Limit Spec interface with 19 public fields or methods.
SandboxCleanupRequest	interface	interface SandboxCleanupRequest	Sandbox Cleanup Request interface with 6 public fields or methods.
SandboxCreateRequest	interface	interface SandboxCreateRequest	Sandbox Create Request interface with 12 public fields or methods.
SandboxFilesystemPolicySpec	interface	interface SandboxFilesystemPolicySpec	Sandbox Filesystem Policy Spec interface with 10 public fields or methods.
SandboxLifecyclePolicySpec	interface	interface SandboxLifecyclePolicySpec	Sandbox Lifecycle Policy Spec interface with 12 public fields or methods.
SandboxMountSpec	interface	interface SandboxMountSpec	Sandbox Mount Spec interface with 8 public fields or methods.
SandboxProviderCapabilities	interface	interface SandboxProviderCapabilities	Sandbox Provider Capabilities interface with 12 public fields or methods.
SandboxRecord	interface	interface SandboxRecord	Sandbox Record interface with 26 public fields or methods.
SandboxSecurityPolicySpec	interface	interface SandboxSecurityPolicySpec	Sandbox Security Policy Spec interface with 20 public fields or methods.
SandboxStartRequest	interface	interface SandboxStartRequest	Sandbox Start Request interface with 5 public fields or methods.
SandboxStatusRequest	interface	interface SandboxStatusRequest	Sandbox Status Request interface with 2 public fields or methods.
SandboxTerminateRequest	interface	interface SandboxTerminateRequest	Sandbox Terminate Request interface with 6 public fields or methods.
SandboxTmpfsSpec	interface	interface SandboxTmpfsSpec	Sandbox Tmpfs Spec interface with 6 public fields or methods.
SecretInjectionPolicySpec	interface	interface SecretInjectionPolicySpec	Secret Injection Policy Spec interface with 8 public fields or methods.
SandboxStatus	type	type SandboxStatus = 'creating' | 'created' | 'starting' | 'ready' | 'busy' | 'stopping' | 'stopped' | 'terminating' | 'terminated' | 'cleaning' | 'cleaned' | 'failed'	Public type alias for Sandbox Status; the declaration contains its complete type expression.

ExecutionEnvironmentSpec

Execution Environment Spec interface with 23 public fields or methods.

• Kind: interface
• Import: import type { ExecutionEnvironmentSpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface ExecutionEnvironmentSpec extends VersionedSpec, SpecMetadata {
    revision?: string;
    provider: 'mock' | 'local_process' | 'docker' | 'remote_sandbox' | 'custom';
    providerRef?: string;
    image?: ExecutionImageSpec;
    process: ProcessPolicySpec;
    resources: ResourceLimitSpec;
    filesystem: SandboxFilesystemPolicySpec;
    network: NetworkPolicySpec;
    security: SandboxSecurityPolicySpec;
    secrets: SecretInjectionPolicySpec;
    logging: ExecutionLoggingPolicySpec;
    lifecycle: SandboxLifecyclePolicySpec;
    workingDirectoryPolicy: 'workspace_only' | 'configured_paths';
    defaultTimeoutMs: number;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
createdAt	property	createdAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
defaultTimeoutMs	property	defaultTimeoutMs: number	Public property; its type, readonly modifier and optionality are shown in the signature.
description	property	description?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
filesystem	property	filesystem: SandboxFilesystemPolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
image	property	image?: ExecutionImageSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
lifecycle	property	lifecycle: SandboxLifecyclePolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
logging	property	logging: ExecutionLoggingPolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
name	property	name?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
network	property	network: NetworkPolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
owner	property	owner?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
process	property	process: ProcessPolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
provider	property	provider: "mock" | "local_process" | "docker" | "remote_sandbox" | "custom"	Public property; its type, readonly modifier and optionality are shown in the signature.
providerRef	property	providerRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
resources	property	resources: ResourceLimitSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
revision	property	revision?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
secrets	property	secrets: SecretInjectionPolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
security	property	security: SandboxSecurityPolicySpec	Public property; its type, readonly modifier and optionality are shown in the signature.
tags	property	tags?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
updatedAt	property	updatedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
version	property	version: string	Public property; its type, readonly modifier and optionality are shown in the signature.
workingDirectoryPolicy	property	workingDirectoryPolicy: "workspace_only" | "configured_paths"	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionImageSpec

Execution Image Spec interface with 8 public fields or methods.

• Kind: interface
• Import: import type { ExecutionImageSpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface ExecutionImageSpec {
    reference: string;
    digest?: string;
    platform?: string;
    pullPolicy?: 'never' | 'if_not_present' | 'always';
    trustedRegistryRefs?: string[];
    requireDigestPin?: boolean;
    sbomRef?: string;
    signaturePolicyRef?: string;
}

Contract members

Member	Kind	Signature	Description
digest	property	digest?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
platform	property	platform?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
pullPolicy	property	pullPolicy?: "never" | "if_not_present" | "always"	Public property; its type, readonly modifier and optionality are shown in the signature.
reference	property	reference: string	Public property; its type, readonly modifier and optionality are shown in the signature.
requireDigestPin	property	requireDigestPin?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
sbomRef	property	sbomRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
signaturePolicyRef	property	signaturePolicyRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
trustedRegistryRefs	property	trustedRegistryRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.

ExecutionLoggingPolicySpec

Execution Logging Policy Spec interface with 7 public fields or methods.

• Kind: interface
• Import: import type { ExecutionLoggingPolicySpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface ExecutionLoggingPolicySpec {
    captureStdout: boolean;
    captureStderr: boolean;
    streamOutput?: boolean;
    includeTimestamps?: boolean;
    maxLineBytes?: number;
    redactPatterns?: string[];
    persistOutputAsArtifact?: boolean;
}

Contract members

Member	Kind	Signature	Description
captureStderr	property	captureStderr: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
captureStdout	property	captureStdout: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
includeTimestamps	property	includeTimestamps?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
maxLineBytes	property	maxLineBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
persistOutputAsArtifact	property	persistOutputAsArtifact?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
redactPatterns	property	redactPatterns?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
streamOutput	property	streamOutput?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

NetworkPolicySpec

Network Policy Spec interface with 16 public fields or methods.

• Kind: interface
• Import: import type { NetworkPolicySpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface NetworkPolicySpec {
    mode: 'disabled' | 'restricted' | 'enabled' | 'task_authorized';
    allowedDomains?: string[];
    deniedDomains?: string[];
    allowedCidrs?: string[];
    deniedCidrs?: string[];
    allowedPorts?: number[];
    allowedProtocols?: Array<'tcp' | 'udp' | 'http' | 'https' | 'dns'>;
    dnsPolicy?: 'disabled' | 'system' | 'managed';
    proxyRef?: string;
    blockPrivateNetworks?: boolean;
    blockMetadataEndpoints?: boolean;
    resolveAndPinDns?: boolean;
    taskAuthorizationTtlSeconds?: number;
    maxConnections?: number;
    maxBytesSent?: number;
    maxBytesReceived?: number;
}

Contract members

Member	Kind	Signature	Description
allowedCidrs	property	allowedCidrs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
allowedDomains	property	allowedDomains?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
allowedPorts	property	allowedPorts?: number[]	Public property; its type, readonly modifier and optionality are shown in the signature.
allowedProtocols	property	allowedProtocols?: ("tcp" | "udp" | "http" | "https" | "dns")[]	Public property; its type, readonly modifier and optionality are shown in the signature.
blockMetadataEndpoints	property	blockMetadataEndpoints?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
blockPrivateNetworks	property	blockPrivateNetworks?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
deniedCidrs	property	deniedCidrs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
deniedDomains	property	deniedDomains?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
dnsPolicy	property	dnsPolicy?: "system" | "managed" | "disabled"	Public property; its type, readonly modifier and optionality are shown in the signature.
maxBytesReceived	property	maxBytesReceived?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxBytesSent	property	maxBytesSent?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxConnections	property	maxConnections?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
mode	property	mode: "disabled" | "restricted" | "enabled" | "task_authorized"	Public property; its type, readonly modifier and optionality are shown in the signature.
proxyRef	property	proxyRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
resolveAndPinDns	property	resolveAndPinDns?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
taskAuthorizationTtlSeconds	property	taskAuthorizationTtlSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ProcessPolicySpec

Process Policy Spec interface with 17 public fields or methods.

• Kind: interface
• Import: import type { ProcessPolicySpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface ProcessPolicySpec {
    shellEnabled: boolean;
    allowedShells?: string[];
    allowedExecutables?: string[];
    deniedExecutables?: string[];
    executableResolution: 'absolute_allowlist' | 'path_allowlist' | 'container_path';
    maxProcesses?: number;
    maxThreads?: number;
    maxOpenFiles?: number;
    allowBackgroundProcesses?: boolean;
    allowDaemonization?: boolean;
    killProcessTreeOnExit: boolean;
    environmentAllowList?: string[];
    environmentDenyList?: string[];
    inheritHostEnvironment?: boolean;
    defaultUmask?: string;
    locale?: string;
    timezone?: string;
}

Contract members

Member	Kind	Signature	Description
allowBackgroundProcesses	property	allowBackgroundProcesses?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
allowDaemonization	property	allowDaemonization?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
allowedExecutables	property	allowedExecutables?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
allowedShells	property	allowedShells?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
defaultUmask	property	defaultUmask?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
deniedExecutables	property	deniedExecutables?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
environmentAllowList	property	environmentAllowList?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
environmentDenyList	property	environmentDenyList?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
executableResolution	property	executableResolution: "absolute_allowlist" | "path_allowlist" | "container_path"	Public property; its type, readonly modifier and optionality are shown in the signature.
inheritHostEnvironment	property	inheritHostEnvironment?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
killProcessTreeOnExit	property	killProcessTreeOnExit: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
locale	property	locale?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
maxOpenFiles	property	maxOpenFiles?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxProcesses	property	maxProcesses?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxThreads	property	maxThreads?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
shellEnabled	property	shellEnabled: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
timezone	property	timezone?: string	Public property; its type, readonly modifier and optionality are shown in the signature.

ResourceLimitSpec

Resource Limit Spec interface with 19 public fields or methods.

• Kind: interface
• Import: import type { ResourceLimitSpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface ResourceLimitSpec {
    cpuCores?: number;
    cpuQuotaMicros?: number;
    cpuPeriodMicros?: number;
    cpuShares?: number;
    maxCpuSeconds?: number;
    memoryMb?: number;
    memorySwapMb?: number;
    oomKillDisable?: boolean;
    diskBytes?: number;
    tempBytes?: number;
    maxWriteBytes?: number;
    blockIoWeight?: number;
    pidsLimit?: number;
    maxOpenFiles?: number;
    maxStdoutBytes?: number;
    maxStderrBytes?: number;
    maxCombinedOutputBytes?: number;
    maxExecutionSeconds?: number;
    maxIdleSeconds?: number;
}

Contract members

Member	Kind	Signature	Description
blockIoWeight	property	blockIoWeight?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
cpuCores	property	cpuCores?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
cpuPeriodMicros	property	cpuPeriodMicros?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
cpuQuotaMicros	property	cpuQuotaMicros?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
cpuShares	property	cpuShares?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
diskBytes	property	diskBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxCombinedOutputBytes	property	maxCombinedOutputBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxCpuSeconds	property	maxCpuSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxExecutionSeconds	property	maxExecutionSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxIdleSeconds	property	maxIdleSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxOpenFiles	property	maxOpenFiles?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxStderrBytes	property	maxStderrBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxStdoutBytes	property	maxStdoutBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxWriteBytes	property	maxWriteBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
memoryMb	property	memoryMb?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
memorySwapMb	property	memorySwapMb?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
oomKillDisable	property	oomKillDisable?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
pidsLimit	property	pidsLimit?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
tempBytes	property	tempBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxCleanupRequest

Sandbox Cleanup Request interface with 6 public fields or methods.

• Kind: interface
• Import: import type { SandboxCleanupRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxCleanupRequest {
    operationId: string;
    sandboxId: string;
    principal: ExecutionPrincipal;
    expectedRevision: number;
    reason?: string;
    idempotencyKey?: string;
}

Contract members

Member	Kind	Signature	Description
expectedRevision	property	expectedRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxCreateRequest

Sandbox Create Request interface with 12 public fields or methods.

• Kind: interface
• Import: import type { SandboxCreateRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxCreateRequest {
    operationId: string;
    principal: ExecutionPrincipal;
    environment: ExecutionEnvironmentSpec;
    environmentRevision: string;
    userId: string;
    tenantId?: string;
    workspaceId: string;
    sessionId?: string;
    runId: string;
    agentId?: string;
    idempotencyKey?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
agentId	property	agentId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
environment	property	environment: ExecutionEnvironmentSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
environmentRevision	property	environmentRevision: string	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
runId	property	runId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sessionId	property	sessionId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
tenantId	property	tenantId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
workspaceId	property	workspaceId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxFilesystemPolicySpec

Sandbox Filesystem Policy Spec interface with 10 public fields or methods.

• Kind: interface
• Import: import type { SandboxFilesystemPolicySpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxFilesystemPolicySpec {
    rootFilesystem: 'read_only' | 'writable';
    mounts: SandboxMountSpec[];
    tmpfs?: SandboxTmpfsSpec[];
    maskPaths?: string[];
    readonlyPaths?: string[];
    writablePaths?: string[];
    allowDeviceAccess?: boolean;
    allowedDevices?: string[];
    allowHostPathMounts?: boolean;
    maxMounts?: number;
}

Contract members

Member	Kind	Signature	Description
allowDeviceAccess	property	allowDeviceAccess?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
allowedDevices	property	allowedDevices?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
allowHostPathMounts	property	allowHostPathMounts?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
maskPaths	property	maskPaths?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
maxMounts	property	maxMounts?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
mounts	property	mounts: SandboxMountSpec[]	Public property; its type, readonly modifier and optionality are shown in the signature.
readonlyPaths	property	readonlyPaths?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
rootFilesystem	property	rootFilesystem: "read_only" | "writable"	Public property; its type, readonly modifier and optionality are shown in the signature.
tmpfs	property	tmpfs?: SandboxTmpfsSpec[]	Public property; its type, readonly modifier and optionality are shown in the signature.
writablePaths	property	writablePaths?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxLifecyclePolicySpec

Sandbox Lifecycle Policy Spec interface with 12 public fields or methods.

• Kind: interface
• Import: import type { SandboxLifecyclePolicySpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxLifecyclePolicySpec {
    reuse: 'never' | 'run' | 'session' | 'pool';
    idleTtlSeconds?: number;
    maxLifetimeSeconds?: number;
    maxExecutions?: number;
    createTimeoutMs?: number;
    startTimeoutMs?: number;
    stopTimeoutMs?: number;
    cleanupTimeoutMs?: number;
    snapshotOnFailure?: boolean;
    cleanupOnSuccess?: boolean;
    cleanupOnFailure?: boolean;
    retainForDebugSeconds?: number;
}

Contract members

Member	Kind	Signature	Description
cleanupOnFailure	property	cleanupOnFailure?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
cleanupOnSuccess	property	cleanupOnSuccess?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
cleanupTimeoutMs	property	cleanupTimeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
createTimeoutMs	property	createTimeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idleTtlSeconds	property	idleTtlSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxExecutions	property	maxExecutions?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
maxLifetimeSeconds	property	maxLifetimeSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
retainForDebugSeconds	property	retainForDebugSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
reuse	property	reuse: "session" | "run" | "never" | "pool"	Public property; its type, readonly modifier and optionality are shown in the signature.
snapshotOnFailure	property	snapshotOnFailure?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
startTimeoutMs	property	startTimeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
stopTimeoutMs	property	stopTimeoutMs?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxMountSpec

Sandbox Mount Spec interface with 8 public fields or methods.

• Kind: interface
• Import: import type { SandboxMountSpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxMountSpec {
    sourceRef: string;
    targetPath: string;
    mode: 'ro' | 'rw';
    type: 'bind' | 'volume' | 'artifact' | 'workspace' | 'tmpfs';
    propagation?: 'private' | 'rprivate';
    noExec?: boolean;
    noSuid?: boolean;
    noDev?: boolean;
}

Contract members

Member	Kind	Signature	Description
mode	property	mode: "ro" | "rw"	Public property; its type, readonly modifier and optionality are shown in the signature.
noDev	property	noDev?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
noExec	property	noExec?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
noSuid	property	noSuid?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
propagation	property	propagation?: "private" | "rprivate"	Public property; its type, readonly modifier and optionality are shown in the signature.
sourceRef	property	sourceRef: string	Public property; its type, readonly modifier and optionality are shown in the signature.
targetPath	property	targetPath: string	Public property; its type, readonly modifier and optionality are shown in the signature.
type	property	type: "artifact" | "workspace" | "bind" | "volume" | "tmpfs"	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxProviderCapabilities

Sandbox Provider Capabilities interface with 12 public fields or methods.

• Kind: interface
• Import: import type { SandboxProviderCapabilities } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxProviderCapabilities {
    processIsolation: boolean;
    filesystemIsolation: boolean;
    networkIsolation: boolean;
    cpuLimits: boolean;
    memoryLimits: boolean;
    diskLimits: boolean;
    pidsLimit: boolean;
    cancellation: boolean;
    processTreeKill: boolean;
    snapshots: boolean;
    imageDigestPinning: boolean;
    remoteExecution: boolean;
}

Contract members

Member	Kind	Signature	Description
cancellation	property	cancellation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
cpuLimits	property	cpuLimits: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
diskLimits	property	diskLimits: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
filesystemIsolation	property	filesystemIsolation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
imageDigestPinning	property	imageDigestPinning: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
memoryLimits	property	memoryLimits: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
networkIsolation	property	networkIsolation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
pidsLimit	property	pidsLimit: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
processIsolation	property	processIsolation: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
processTreeKill	property	processTreeKill: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
remoteExecution	property	remoteExecution: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
snapshots	property	snapshots: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxRecord

Sandbox Record interface with 26 public fields or methods.

• Kind: interface
• Import: import type { SandboxRecord } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxRecord {
    id: string;
    revision: number;
    providerId: string;
    environmentRef: SpecRef;
    environmentRevision: string;
    tenantId?: string;
    userId: string;
    workspaceId: string;
    sessionId?: string;
    runId: string;
    agentId?: string;
    status: SandboxStatus;
    providerSandboxRef?: string;
    imageDigest?: string;
    activeExecutionIds: string[];
    resourceLimits: ResourceLimitSpec;
    networkPolicyHash: string;
    mountPolicyHash: string;
    createdAt: string;
    readyAt?: string;
    lastUsedAt?: string;
    expiresAt?: string;
    terminatedAt?: string;
    cleanedAt?: string;
    error?: NormalizedExecutionError;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
activeExecutionIds	property	activeExecutionIds: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
agentId	property	agentId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
cleanedAt	property	cleanedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
createdAt	property	createdAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
environmentRef	property	environmentRef: SpecRef	Public property; its type, readonly modifier and optionality are shown in the signature.
environmentRevision	property	environmentRevision: string	Public property; its type, readonly modifier and optionality are shown in the signature.
error	property	error?: NormalizedExecutionError	Public property; its type, readonly modifier and optionality are shown in the signature.
expiresAt	property	expiresAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
id	property	id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
imageDigest	property	imageDigest?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
lastUsedAt	property	lastUsedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
mountPolicyHash	property	mountPolicyHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
networkPolicyHash	property	networkPolicyHash: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
providerSandboxRef	property	providerSandboxRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
readyAt	property	readyAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
resourceLimits	property	resourceLimits: ResourceLimitSpec	Public property; its type, readonly modifier and optionality are shown in the signature.
revision	property	revision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
runId	property	runId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sessionId	property	sessionId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status: SandboxStatus	Public property; its type, readonly modifier and optionality are shown in the signature.
tenantId	property	tenantId?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
terminatedAt	property	terminatedAt?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
userId	property	userId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
workspaceId	property	workspaceId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxSecurityPolicySpec

Sandbox Security Policy Spec interface with 20 public fields or methods.

• Kind: interface
• Import: import type { SandboxSecurityPolicySpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxSecurityPolicySpec {
    runAsUser?: string;
    runAsGroup?: string;
    nonRootRequired: boolean;
    noNewPrivileges: boolean;
    privileged: boolean;
    dropCapabilities?: string[];
    addCapabilities?: string[];
    seccompProfileRef?: string;
    appArmorProfileRef?: string;
    selinuxLabelRef?: string;
    userNamespace?: boolean;
    pidNamespace?: boolean;
    networkNamespace?: boolean;
    ipcNamespace?: boolean;
    utsNamespace?: boolean;
    readOnlyProc?: boolean;
    maskHostProc?: boolean;
    preventPtrace?: boolean;
    allowNestedContainers?: boolean;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
addCapabilities	property	addCapabilities?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
allowNestedContainers	property	allowNestedContainers?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
appArmorProfileRef	property	appArmorProfileRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
dropCapabilities	property	dropCapabilities?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
ipcNamespace	property	ipcNamespace?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
maskHostProc	property	maskHostProc?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
metadata	property	metadata?: Record<string, unknown>	Public property; its type, readonly modifier and optionality are shown in the signature.
networkNamespace	property	networkNamespace?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
noNewPrivileges	property	noNewPrivileges: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
nonRootRequired	property	nonRootRequired: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
pidNamespace	property	pidNamespace?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
preventPtrace	property	preventPtrace?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
privileged	property	privileged: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
readOnlyProc	property	readOnlyProc?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
runAsGroup	property	runAsGroup?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
runAsUser	property	runAsUser?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
seccompProfileRef	property	seccompProfileRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
selinuxLabelRef	property	selinuxLabelRef?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
userNamespace	property	userNamespace?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
utsNamespace	property	utsNamespace?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxStartRequest

Sandbox Start Request interface with 5 public fields or methods.

• Kind: interface
• Import: import type { SandboxStartRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxStartRequest {
    operationId: string;
    sandboxId: string;
    principal: ExecutionPrincipal;
    expectedRevision: number;
    idempotencyKey?: string;
}

Contract members

Member	Kind	Signature	Description
expectedRevision	property	expectedRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxStatusRequest

Sandbox Status Request interface with 2 public fields or methods.

• Kind: interface
• Import: import type { SandboxStatusRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxStatusRequest {
    sandboxId: string;
    principal: ExecutionPrincipal;
}

Contract members

Member	Kind	Signature	Description
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxTerminateRequest

Sandbox Terminate Request interface with 6 public fields or methods.

• Kind: interface
• Import: import type { SandboxTerminateRequest } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxTerminateRequest {
    operationId: string;
    sandboxId: string;
    principal: ExecutionPrincipal;
    expectedRevision: number;
    reason?: string;
    idempotencyKey?: string;
}

Contract members

Member	Kind	Signature	Description
expectedRevision	property	expectedRevision: number	Public property; its type, readonly modifier and optionality are shown in the signature.
idempotencyKey	property	idempotencyKey?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operationId	property	operationId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
principal	property	principal: ExecutionPrincipal	Public property; its type, readonly modifier and optionality are shown in the signature.
reason	property	reason?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
sandboxId	property	sandboxId: string	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxTmpfsSpec

Sandbox Tmpfs Spec interface with 6 public fields or methods.

• Kind: interface
• Import: import type { SandboxTmpfsSpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SandboxTmpfsSpec {
    targetPath: string;
    sizeBytes?: number;
    mode?: number;
    noExec?: boolean;
    noSuid?: boolean;
    noDev?: boolean;
}

Contract members

Member	Kind	Signature	Description
mode	property	mode?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
noDev	property	noDev?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
noExec	property	noExec?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
noSuid	property	noSuid?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
sizeBytes	property	sizeBytes?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
targetPath	property	targetPath: string	Public property; its type, readonly modifier and optionality are shown in the signature.

SecretInjectionPolicySpec

Secret Injection Policy Spec interface with 8 public fields or methods.

• Kind: interface
• Import: import type { SecretInjectionPolicySpec } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export interface SecretInjectionPolicySpec {
    allowedSecretRefs?: string[];
    injectionMode: 'none' | 'environment' | 'file' | 'brokered';
    exposeNamesOnly?: boolean;
    redactFromOutput: boolean;
    redactFromEvents: boolean;
    ttlSeconds?: number;
    revokeOnExecutionEnd?: boolean;
    allowChildProcessInheritance?: boolean;
}

Contract members

Member	Kind	Signature	Description
allowChildProcessInheritance	property	allowChildProcessInheritance?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
allowedSecretRefs	property	allowedSecretRefs?: string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
exposeNamesOnly	property	exposeNamesOnly?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
injectionMode	property	injectionMode: "none" | "environment" | "file" | "brokered"	Public property; its type, readonly modifier and optionality are shown in the signature.
redactFromEvents	property	redactFromEvents: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
redactFromOutput	property	redactFromOutput: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
revokeOnExecutionEnd	property	revokeOnExecutionEnd?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
ttlSeconds	property	ttlSeconds?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

SandboxStatus

Public type alias for Sandbox Status; the declaration contains its complete type expression.

• Kind: type
• Import: import type { SandboxStatus } from '@codesoul-co/hypha-core';
• Source module: contracts/sandbox

Declaration

export type SandboxStatus = 'creating' | 'created' | 'starting' | 'ready' | 'busy' | 'stopping' | 'stopped' | 'terminating' | 'terminated' | 'cleaning' | 'cleaned' | 'failed';