PortsService

Sandbox port namespace — what is listening inside the guest.

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; a browser can also sign in when the deployment has preview login.

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.

The daemon only answers for 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>

list()

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

Every TCP port currently listening in the sandbox.

Returns:

• Promise<ListResult<number>>

listEndpoints()

listEndpoints(): Promise<ListResult<PreviewEndpoint>>;

Returns:

• Promise<ListResult<PreviewEndpoint>>

previewLink()

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

Preview URL plus access token for one in-VM port.

Callers send the token in the X-Daytona-Preview-Token header; a minted sandbox token (a JWT) is also accepted as a Bearer or ?rlp_token=, but the route's HMAC fallback token works ONLY in the header. Public endpoints need no token (token === ''). The returned link also exposes expiresAt when the token expiry is knowable. For private endpoints, a client that can mint (a project key, no caller-supplied token) gets a short-lived sandbox access token scoped to exactly this port (PLAN-SANDBOX-TOKEN-JWT D9), unless the preview-url route already returned a sandbox JWT; otherwise the route token is passed through unchanged.

Parameters:

• port number

Returns:

• Promise<PreviewLink>

setPublic()

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

Change the visibility of an already-exposed port.

Throws a 404 error when the port has not been exposed yet — call expose first. Public endpoints need no credential. Programmatic access to a private one needs the token from previewLink or a signedPreviewLink URL; a browser can also sign in when the deployment has preview login.

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 in-VM 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>

PortRequest

Properties:

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

ExposePortOptions

Properties:

• public? boolean

SignedPreviewLinkOptions

Properties:

• expiresInSeconds? number

SetPortPublicOptions

Properties:

• public boolean

PortInUseResponse

type PortInUseResponse = OptionalizeNullable<Schema<"IsPortInUseResponse">>

PortListResponse

type PortListResponse = toolbox.PortList