> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dedaluslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ports

> Expose a port on a Dedalus Machine over a public HTTPS URL

<Warning>
  `ports` is the unreleased control-plane name. The CLI v0.5.0 and SDKs v0.4.0
  ship this resource as `previews` and do not provide `machines.ports`. The
  examples below use the released namespace.
</Warning>

<CodeGroup>
  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  dedalus machines previews create \
    --machine-id <machine_id> \
    --port 3000 \
    --protocol https \
    --visibility public
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  p = client.machines.previews.create(
      machine_id="<machine_id>",
      port=3000,
      protocol="https",
      visibility="public",
  )
  print(p.preview_id)
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const p = await client.machines.previews.create({
    machine_id: "<machine_id>",
    port: 3000,
    protocol: "https",
    visibility: "public",
  });
  console.log(p.preview_id);
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  p, _ := client.Machines.Previews.New(ctx, dedalus.MachinePreviewNewParams{
      MachineID: machineID,
      PreviewCreateParams: dedalus.PreviewCreateParams{
          Port:       3000,
          Protocol:   dedalus.PreviewCreateParamsProtocolHTTPS,
          Visibility: dedalus.PreviewCreateParamsVisibilityPublic,
      },
  })
  fmt.Println(p.PreviewID)
  ```
</CodeGroup>

Creates a URL that proxies to a port inside the machine. Creation can return `wake_in_progress`; retrieve the preview by `preview_id` until its status is `ready`, then use the API-returned `url`. Treat `closed`, `expired`, and `failed` as terminal errors.

<Accordion title="Parameters">
  <ParamField path="machine_id" type="string" required>
    The machine that runs the service.
  </ParamField>

  <ParamField body="port" type="integer" required>
    The internal port your service listens on.
  </ParamField>

  <ParamField body="protocol" type="string">
    Public protocol for the exposed URL.
  </ParamField>

  <ParamField body="visibility" type="string">
    Who can use the URL: `public`, `org`, or `private`.
  </ParamField>
</Accordion>

## Manage exposed ports

<CodeGroup>
  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  dedalus machines previews list --machine-id <machine_id>
  dedalus machines previews retrieve --machine-id <machine_id> --preview-id <preview_id>
  dedalus machines previews delete --machine-id <machine_id> --preview-id <preview_id>
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  client.machines.previews.list(machine_id="<machine_id>")
  client.machines.previews.retrieve(
      machine_id="<machine_id>",
      preview_id="<preview_id>",
  )
  client.machines.previews.delete(
      machine_id="<machine_id>",
      preview_id="<preview_id>",
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  await client.machines.previews.list({ machine_id: "<machine_id>" });
  await client.machines.previews.retrieve({
    machine_id: "<machine_id>",
    preview_id: "<preview_id>",
  });
  await client.machines.previews.delete({
    machine_id: "<machine_id>",
    preview_id: "<preview_id>",
  });
  ```

  ```go Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  client.Machines.Previews.List(ctx, dedalus.MachinePreviewListParams{
      MachineID: machineID,
  })
  client.Machines.Previews.Get(ctx, dedalus.MachinePreviewGetParams{
      MachineID:  machineID,
      PreviewID: "<preview_id>",
  })
  client.Machines.Previews.Delete(ctx, dedalus.MachinePreviewDeleteParams{
      MachineID:  machineID,
      PreviewID: "<preview_id>",
  })
  ```
</CodeGroup>

<Accordion title="Parameters">
  <ParamField path="machine_id" type="string" required>
    The machine that owns the exposed port.
  </ParamField>

  <ParamField path="preview_id" type="string" required>
    The preview resource to retrieve or delete.
  </ParamField>
</Accordion>