{"record":{"id":"ea4457f9ac6f438a","repo":"vercel/ai","slug":"just-bash-sandboxes-run-in-process-and-cannot-expo","errorCode":null,"errorMessage":"just-bash sandboxes run in-process and cannot expose a port URL. Use a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for bridge-backed harness adapters.","messagePattern":"just-bash sandboxes run in-process and cannot expose a port URL\\. Use a hosted sandbox \\(e\\.g\\. @ai-sdk/sandbox-vercel\\) for bridge-backed harness adapters\\.","errorType":"exception","errorClass":"HarnessCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/sandbox-just-bash/src/just-bash-network-sandbox-session.ts","lineNumber":54,"sourceCode":"\n  constructor(input: { sandbox: Sandbox; ownsLifecycle: boolean }) {\n    super(input.sandbox);\n    this.ownsLifecycle = input.ownsLifecycle;\n    this.id = randomUUID();\n    this.defaultWorkingDirectory = input.sandbox.bashEnvInstance.getCwd();\n  }\n\n  readonly ports: ReadonlyArray<number> = [];\n\n  restricted(): SandboxSession {\n    return new JustBashSandboxSession(this.sandbox);\n  }\n\n  getPortEndpoint = async (_options: {\n    port: number;\n    protocol?: 'http' | 'https' | 'ws';\n  }): Promise<HarnessV1PortEndpoint> => {\n    throw new HarnessCapabilityUnsupportedError({\n      harnessId: JUST_BASH_PROVIDER_ID,\n      message:\n        'just-bash sandboxes run in-process and cannot expose a port URL. ' +\n        'Use a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for bridge-backed harness adapters.',\n    });\n  };\n\n  /**\n   * @deprecated Use `getPortEndpoint` instead.\n   */\n  getPortUrl = async (options: {\n    port: number;\n    protocol?: 'http' | 'https' | 'ws';\n  }): Promise<string> => {\n    return (await this.getPortEndpoint(options)).url;\n  };\n\n  stop = async (): Promise<void> => {","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/sandbox-just-bash/src/just-bash-network-sandbox-session.ts#L36-L72","documentation":"The just-bash sandbox runs entirely in-process (a simulated bash environment) and therefore has no networking layer capable of exposing a reachable port URL. getPortEndpoint thus always throws HarnessCapabilityUnsupportedError, directing users to a hosted sandbox provider for port/bridge features.","triggerScenarios":"Calling getPortEndpoint({ port }) on a session created by @ai-sdk/sandbox-just-bash — regardless of options — always throws.","commonSituations":"Harness adapters that assume all sandbox providers support port endpoints; testing code that starts an HTTP server inside just-bash and expects a URL to fetch; swapping sandbox providers without checking capabilities.","solutions":["Use a hosted sandbox such as @ai-sdk/sandbox-vercel when you need port endpoints","Check capability support before calling getPortEndpoint","Keep just-bash for filesystem/command simulation only and run servers elsewhere","Catch HarnessCapabilityUnsupportedError and fall back to a hosted provider"],"exampleFix":"// before\nconst session = justBash({ ... });\nconst endpoint = await session.getPortEndpoint({ port: 3000 });\n// after\nconst session = vercelSandbox({ ... });\nconst endpoint = await session.getPortEndpoint({ port: 3000 });","handlingStrategy":"fallback","validationCode":"const supportsPortEndpoint = providerId !== 'just-bash';\nif (!supportsPortEndpoint) {\n  throw new Error('Select a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for port endpoints');\n}","typeGuard":"function isCapabilityUnsupported(e) {\n  return typeof e === 'object' && e !== null && e.constructor?.name === 'HarnessCapabilityUnsupportedError';\n}","tryCatchPattern":"try {\n  endpoint = await session.getPortEndpoint({ port: 3000 });\n} catch (e) {\n  if (e.constructor?.name === 'HarnessCapabilityUnsupportedError') {\n    session = await createHostedSandbox(); // fallback\n    endpoint = await session.getPortEndpoint({ port: 3000 });\n  } else throw e;\n}","preventionTips":["Treat just-bash as a filesystem/command simulator only — never expect networking","Check harness capabilities before choosing a sandbox provider","Abstract sandbox creation so hosted providers can be swapped in when ports are needed"],"tags":["sandbox","capability-unsupported","port-endpoint","just-bash"],"backgroundTag":"sandbox-capability-unsupported","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}