Skip to content
View as Markdown

PortsService

Section titled “PortsService”

Sandbox port namespace — what is listening inside the guest.

Constructors

Section titled “Constructors”

Constructor

Section titled “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

Section titled “Methods”
Section titled “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()

Section titled “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()

Section titled “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>

iterEndpoints()

Section titled “iterEndpoints()”
iterEndpoints(options: ListEndpointsOptions = {}): AsyncIterable<PreviewEndpoint>;

Parameters:

  • options ListEndpointsOptions = {}

Returns:

  • AsyncIterable<PreviewEndpoint>

list()

Section titled “list()”
list(): Promise<ListResult<number>>;

Every TCP port currently listening in the sandbox.

Returns:

  • Promise<ListResult<number>>

listEndpoints()

Section titled “listEndpoints()”
listEndpoints(options: ListEndpointsOptions = {}): Promise<ListResult<PreviewEndpoint>>;

Parameters:

  • options ListEndpointsOptions = {}

Returns:

  • Promise<ListResult<PreviewEndpoint>>
Section titled “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()

Section titled “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; 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.
Section titled “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()

Section titled “unexpose()”
unexpose(port: number): Promise<void>;

Parameters:

  • port number

Returns:

  • Promise<void>

PortMapping

Section titled “PortMapping”

Properties:

  • port number
  • proto? ‘tcp’ | ‘udp’

ExposePortOptions

Section titled “ExposePortOptions”

Properties:

  • public? boolean

ListEndpointsOptions

Section titled “ListEndpointsOptions”

Properties:

  • cursor? string
  • limit? number

SignedPreviewLinkOptions

Section titled “SignedPreviewLinkOptions”

Properties:

  • expiresInSeconds? number

SetPortPublicOptions

Section titled “SetPortPublicOptions”

Properties:

  • public boolean

PortInUseResponse

Section titled “PortInUseResponse”
type PortInUseResponse = toolbox.PortInUseResponse

PortListResponse

Section titled “PortListResponse”
type PortListResponse = toolbox.PortList