Getting started

Let's install the Ocean CLI, scaffold a custom-coded Ocean integration, and run it against your Port organization.

Requirements

• Python 3.12 or later.
• Port API credentials (client ID and client secret).

Install the Ocean CLI

python -m venv .venv
source .venv/bin/activate
pip install "port-ocean[cli]"

Scaffold a custom-coded Ocean integration

ocean new scaffolds a custom-coded Ocean integration by default (an integration you maintain outside the Ocean monorepo, including a Dockerfile).

ocean new

The CLI prompts for the integration name, description, your Port credentials, and region. Accept the default custom-coded Ocean integration option unless you intend to contribute to the Ocean monorepo.

After scaffolding:

cd ./<your_integration_slug>
make install
source .venv/bin/activate
cp .env.example .env

Update .env with your Port credentials and any integration-specific settings from .port/spec.yaml. See test and run locally for the environment variable naming convention.

Project structure

A private scaffold typically looks like this:

my-integration/
├── Dockerfile
├── pyproject.toml
├── Makefile
├── main.py
├── .env.example
├── debug.py
├── tests/
└── .port/
    ├── spec.yaml
    └── resources/
        ├── blueprints.json
        └── port-app-config.yaml

Path	Role
main.py	Resync handlers, startup hooks, and live event / action registration.
.port/spec.yaml	Integration type, supported kinds, and user-facing config schema.
.port/resources/	Default blueprints and mapping created when the integration starts (if enabled).
Dockerfile	Image build for private deployment.
Makefile	make install, make run, and lint helpers.

Run locally

make run

You can also run ocean sail from the integration directory. Ocean connects to Port, creates default resources if configured, starts the event listener (default POLLING), and runs a resync when needed.

Interactive API docs

While the integration is running, open http://localhost:8000/docs for the built-in Swagger UI, or http://localhost:8000/redoc for ReDoc.

Next steps

• Write your own Ocean integration - replace the sample resync logic with your API client, kinds, and deploy.