PortsService

Sandbox port namespace — what is listening inside the sandbox.

Constructors

Constructor

new PortsService(
   transport: HttpTransport | undefined,
   api?: AxiosInstance,
   sandboxId?: string,
   mintPreviewToken?: (port: number) => Promise<SandboxAccessToken | undefined>): PortsService;

Parameters:

• transport HttpTransport | undefined
• api? AxiosInstance
• sandboxId? string
• mintPreviewToken? (port: number) = > Promise<SandboxAccessToken | undefined>

Returns:

• PortsService

Methods

expireSignedPreviewLink()

expireSignedPreviewLink(port: number, token: string): Promise<void>;

Revoke a signed preview link before its natural expiry.

Parameters:

• port number - TCP port the link was issued for.
• token string - The token field from SignedPreviewLink.

Returns:

• Promise<void>

expose()

expose(port: number, options: ExposePortOptions = {}): Promise<PreviewEndpoint>;

Register a sandbox port as a preview endpoint.

If the port is already exposed, returns the existing endpoint (updating its visibility when options.public differs from the current value). Public endpoints need no credential. Programmatic access to a private one needs the token from previewLink (see PreviewLink) or a signedPreviewLink URL.

Parameters:

• port number - TCP port inside the sandbox (1–65535).
• options ExposePortOptions = {}

Returns:

• Promise<PreviewEndpoint>

isInUse()

isInUse(port: number): Promise<boolean>;

Whether port currently has a listener.

This endpoint accepts 3000-9999 and rejects anything else with BAD_REQUEST, so this deliberately does not clamp or pre-validate: a caller asking about port 80 should see that error rather than a silent false that reads like "nothing is listening there".

Parameters:

• port number

Returns:

• Promise<boolean>

iterEndpoints()

iterEndpoints(options: ListEndpointsOptions = {}): AsyncIterable<PreviewEndpoint>;

Parameters:

• options ListEndpointsOptions = {}

Returns:

• AsyncIterable<PreviewEndpoint>

list()

list(): Promise<ListResult<number>>;

Every TCP port currently listening in the sandbox.

Returns:

• Promise<ListResult<number>>

listEndpoints()

listEndpoints(options: ListEndpointsOptions = {}): Promise<ListResult<PreviewEndpoint>>;

Parameters:

• options ListEndpointsOptions = {}

Returns:

• Promise<ListResult<PreviewEndpoint>>

previewLink()

previewLink(port: number): Promise<PreviewLink>;

Preview URL plus access token for one sandbox port.

Callers send the token in the X-Daytona-Preview-Token header. Public endpoints need no token (token === ''). The returned link exposes expiresAt when the token expiry is knowable. A client that can mint (a project key, no caller-supplied token) gets a short-lived sandbox access token scoped to exactly this port for private endpoints. Otherwise, or if minting fails, the route token is passed through unchanged.

Parameters:

• port number

Returns:

• Promise<PreviewLink>

setPublic()

setPublic(port: number, options: SetPortPublicOptions): Promise<PreviewEndpoint>;

Set the visibility of a port, exposing it first when it is not exposed yet (the same idempotent upsert expose performs).

Public endpoints need no credential. Programmatic access to a private one needs the token from previewLink or a signedPreviewLink URL.

Parameters:

• port number - TCP port inside the sandbox.
• options SetPortPublicOptions

Returns:

• Promise<PreviewEndpoint> - Updated PreviewEndpoint.

signedPreviewLink()

signedPreviewLink(
   port: number,
   options: SignedPreviewLinkOptions = {}): Promise<SignedPreviewLink>;

Return a self-contained signed URL for one sandbox port.

The token is embedded in the hostname, so no extra headers or credentials are needed — the right choice for handing a URL to a browser, a tool, or any client that cannot set request headers.

The default lifetime is 60 seconds. Pass a longer expiresInSeconds for multi-step use (the deployment caps the maximum, typically 7 days). Revoke the link early with expireSignedPreviewLink.

Parameters:

• port number - TCP port inside the sandbox (1–65535).
• options SignedPreviewLinkOptions = {}

Returns:

• Promise<SignedPreviewLink>

Example:

const link = await sandbox.ports.signedPreviewLink(8080, { expiresInSeconds: 300 })
// Hand link.url to a browser or another tool — no headers needed.

unexpose()

unexpose(port: number): Promise<void>;

Parameters:

• port number

Returns:

• Promise<void>

PortMapping

Properties:

• port number
• proto? 'tcp' | 'udp'

ExposePortOptions

Properties:

• public? boolean

ListEndpointsOptions

Properties:

• cursor? string
• limit? number

SignedPreviewLinkOptions

Properties:

• expiresInSeconds? number

SetPortPublicOptions

Properties:

• public boolean

PortInUseResponse

type PortInUseResponse = toolbox.PortInUseResponse

PortListResponse

type PortListResponse = toolbox.PortList