Add ports option to docker() sandbox provider

[OthmanAdi]

Problem

When an agent starts a web server inside the sandbox container, the container is created without port mappings. The host cannot reach the service on any port the agent opens.

The workaround is a manual socat sidecar:

docker run -d --name port-forward -p 3000:3000 alpine/socat TCP-LISTEN:3000,fork,reuseaddr TCP:172.17.0.2:3000

This is not a viable option for end users.

Solution

Add a ports option to the docker() sandbox provider. Each declared port is mapped as -p <port>:<port> in the docker run command, making the port reachable from the host.

import { docker } from "@ai-hero/sandcastle/sandboxes/docker";

await run({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: docker({ ports: [3000, 5173] }),
  promptFile: ".sandcastle/prompt.md",
});

Changes

File	Change
src/DockerLifecycle.ts	Add ports?: readonly number[] to StartContainerOptions, generate -p <port>:<port> flags
src/sandboxes/docker.ts	Add ports?: readonly number[] to DockerOptions, pass through to startContainer
src/DockerLifecycle.test.ts	3 tests: single port, multiple ports, omitted
src/sandboxes/docker.test.ts	2 acceptance tests
.changeset/docker-ports-option.md	Patch changeset

Test plan

• npm test -- src/DockerLifecycle.test.ts src/sandboxes/docker.test.ts — 26/26 pass
• All new tests pass, no regressions in the Docker test files
• Type check: no new errors beyond the pre-existing @daytona/sdk peer dep issue

[vercel]

@OthmanAdi is attempting to deploy a commit to the Matt Pocock's projects Team on Vercel.

A member of the Team first needs to authorize it.