---
title: "Expose a port the agent's local server listens on [write]"
method: PUT
path: "/sessions/{id}/ports/{port}"
---

# Expose a port the agent's local server listens on \[write\]

`PUT /sessions/{id}/ports/{port}`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/sessions/{id}/ports/{port}`
- Auth: HTTP bearer

Create-or-get: the port gets a stable origin `https://app-<id>.agentsky.dev/` relayed to the pod (HTTP and WebSocket) while the pod runs; calling again returns the same record, and a `visibility` in the body replaces the stored one in place. `port` is 1024–65535 and never the pod's own (400 invalid_request). A private port (the default) admits a browser only through an entry link from `POST …/grants`; a public port admits anyone with the address. A parked pod answers a paused page and is never woken by a visit. An archived session answers 400 session_archived.

## Path parameters

- `id` string, required
- `port` integer, required

## Request body

- SessionPortRequest
  - `visibility` 'private' | 'public': Omitted = keep the stored value (private for a new port)

## Response `200`

OK

- SessionPort
  - `port` integer, required: What the app listens on inside the pod
  - `id` string, required: Names the origin; not a credential
  - `url` string, required: https://app-<id>.agentsky.dev/ — stable for the port's life
  - `visibility` 'private' | 'public', required
  - `created_at` string, date-time, required

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 4 info
  - added the optional property `error/request_id` to the response with the `default` status
  - the response property `error` became required for the status `default`
  - the response property `error/code` became required for the status `default`
  - the response property `error/message` became required for the status `default`

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/:id/ports/:port/put.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)