Skip to main content
pdd connect is the recommended entry point for PDD. It starts a local FastAPI server and opens a browser-based interface where you can run any PDD command visually, browse and edit your prompt and code files, and optionally access the session remotely via PDD Cloud.

​
Usage

pdd [GLOBAL OPTIONS] connect [OPTIONS]

​
Options

​
--port
integer
default:"9876"
Port for the local server to listen on. If the default port is in use, PDD automatically scans ports 9876–9899 for an available one.
​
--host
string
default:"127.0.0.1"
Host to bind to. Defaults to localhost only. Changing this without --allow-remote will display a security warning.
​
--allow-remote
boolean
default:"false"
Allow non-localhost connections. When set, the server binds to 0.0.0.0. Using this flag without --token shows a security warning and requires confirmation.
​
--token
string
Bearer token for authentication. Recommended when using --allow-remote.
​
--no-browser
boolean
default:"false"
Do not open the browser automatically when the server starts.
​
--frontend-url
string
Custom frontend URL to open in the browser instead of the default local address.
​
--local-only
boolean
default:"false"
Skip registration with PDD Cloud. The session will not be accessible remotely. The server still runs fully locally.
​
--session-name
string
A custom name for this session. Useful for identifying sessions when running multiple instances.

​
What the web interface provides

  • Command execution — Run pdd change, pdd bug, pdd fix, pdd sync, and all other PDD commands with real-time visual feedback.
  • File browser — View and edit prompt files, generated code, tests, and examples directly in the browser.
  • Remote access — When authenticated with PDD Cloud, your session is automatically registered, allowing access from any browser. Use --local-only to disable this.
  • REST API — A programmatic API is also available at http://localhost:9876, with interactive documentation at http://localhost:9876/docs.

​
Remote session registration

By default, pdd connect registers your session with PDD Cloud when you are authenticated (see pdd auth login). This allows you to access the interface from any browser without port-forwarding. The session is automatically deregistered when you stop the server with Ctrl+C. If you are not authenticated, the server runs in local-only mode automatically and prompts you to run pdd auth login to enable remote access.

​
Examples

# Start with default settings (opens browser automatically)
pdd connect

# Start on a custom port without opening the browser
pdd connect --port 8080 --no-browser

# Allow remote connections with authentication
pdd connect --allow-remote --token "your-secret-token"

# Run in local-only mode (no cloud registration)
pdd connect --local-only

# Start with a custom session name
pdd connect --session-name "my-dev-server"
When using --allow-remote without --token, anyone on your network could execute code on your machine. Always pair --allow-remote with a --token for authenticated access.
  • pdd auth — Authenticate with PDD Cloud to enable remote session access.
  • pdd sessions — List and manage your registered remote sessions.
  • pdd setup — Configure API keys and agentic CLI tools before using connect.

Build docs developers (and LLMs) love

Get started for freeTalk to us