Docs

OpenDock docs

Learn how OpenDock reads a dock package, submits registry readme content, applies file mappings, runs lifecycle steps, and keeps project setup current.

Install guide Open Hub

What a dock contains

A dock is a small project setup package. It has a dock.yml manifest, an optional registry readme, source files or directories referenced by files[].from, and lifecycle steps for install, update, and doctor.

Directory layoutdock

codex/
  dock.yml
  DOCK.md
  files/
    .agents/
    AGENTS.md
    DESIGN.md
    README.md
    .gitignore

Write dock.yml

Start with the manifest version, a stable dock id, a version, optional registry readme, file mappings, and lifecycle steps. OpenDock only applies source paths that are explicitly listed in files.

dock.ymlStarter manifest

opendock: 1
id: opendock/codex
version: 0.1.0
summary: Codex CLI setup with managed workspace files.
readme: DOCK.md

files:
  - from: files/.agents
    to: .agents
    update: managed_file

  - from: files/DESIGN.md
    to: DESIGN.md
    update: managed_block

  - from: files/README.md
    to: README.md
    update: manual_review

  - from: files/.gitignore
    to: .gitignore
    update: append_unique

lifecycle:
  install:
    - id: install-codex-cli
      check: codex --version
      version: ">=0.0.0"
      run: npm install --global @openai/codex@latest

  update:
    - id: update-codex-cli
      run: npm install --global @openai/codex@latest

  doctor:
    - id: codex-cli
      check: codex --version

Field	Required	Meaning
`opendock`	Yes	`1` is the supported manifest version.
`id`	Yes	The dock id in `owner/name` form. It must match the install reference.
`name`, `summary`	No	Human-facing metadata. It does not change runtime behavior.
`version`	Recommended	The dock version. If omitted, the CLI treats it as `0.1.0`.
`readme`	No	Safe relative path to a Markdown file, such as `DOCK.md`. `opendock deploy` includes it as registry detail content.
`files`	No	Explicit file mappings applied before lifecycle commands.
`lifecycle`	No	Install, update, and doctor step groups.
`needs`	No	Parsed for compatibility only. Express real checks and installs with lifecycle steps.

Files syntax

files maps source files or directories inside the dock to target paths in the project. Directory sources are expanded recursively. files/ is only the recommended folder name; OpenDock follows the path in from.

Field	Required	Meaning
`from`	Yes	Source file or directory path relative to the dock root, such as `files/.agents` or `files/AGENTS.md`.
`to`	Yes	Target path relative to the project root, such as `AGENTS.md`.
`update`	Yes	One of `managed_file`, `managed_block`, `manual_review`, or `append_unique`.

The top-level readme is registry documentation only. It is not copied into the installed project unless the same file is also listed under files.

Update policies

Choose a policy based on how much of the target file OpenDock should own during install and update.

Policy	Use	Update behavior
`managed_file`	`.agents/`, generated harness files	Replace or delete only when the target hash still matches the last OpenDock-applied hash. Edited files require review unless forced.
`managed_block`	`AGENTS.md`, `DESIGN.md`	Replace the OpenDock-managed block while leaving user text outside the block alone.
`manual_review`	`README.md`	Prepare the new content for review instead of silently replacing project prose.
`append_unique`	`.gitignore`	Append missing lines once, without duplicating existing ignore entries.

Lifecycle steps

Lifecycle steps are grouped by command. Each group runs from top to bottom. A step may declare a check, a version range, a command, a timeout, or platform-specific overrides.

Field	Required	Meaning
`install`	No	Runs during first install after file mappings are applied.
`update`	No	Runs during maintenance updates after file policies are re-applied.
`doctor`	No	Checks the current project state and reports failures without immediately repairing them.

Field	Required	Meaning
`id`	Yes	Step identifier shown in logs and doctor output.
`check`	No	Command used to detect whether the step is already ready.
`run`	No	Command run when install or update needs to change state.
`version`	No	Semver range checked against the first x.y.z version found in command output.
`timeout_ms`	No	Positive command timeout in milliseconds. Doctor defaults to 30000ms.
`platforms`	No	macOS, Windows, or Linux overrides for the same logical step id.
`interactive`	No	TTY or scripted input mode for commands that ask questions.

dock.ymlStep order

lifecycle:
  install:
    - id: install-node
      check: node --version
      version: ">=22.0.0 <25.0.0"
      platforms:
        macos:
          run: brew install node
        windows:
          run: winget install --id OpenJS.NodeJS.LTS --exact

  update:
    - id: update-codex-cli
      run: npm install --global @openai/codex@latest

  doctor:
    - id: check-node
      check: node --version

Platform selection

OpenDock auto-detects the host platform during install unless --platform is provided. The selected platform is written into .opendock/dock.lock.yml and reused by update and doctor.

CLIExplicit platform

opendock install opendock/codex --platform windows
opendock update
opendock doctor

Interactive steps

Use interactive mode only when a lifecycle command genuinely needs a terminal UI or a small approved key sequence.

dock.ymlTTY and scripted input

lifecycle:
  install:
    - id: open-codex-login
      run: codex
      interactive: user
      timeout_ms: 600000

    - id: scripted-choice
      run: codex
      interactive:
        mode: scripted
        inputs:
          - key: tab
            repeat: 3
          - key: enter
      timeout_ms: 600000

Next steps

Use the install guide to try the Codex dock in a temporary project. When you are ready to publish a dock, sign in and submit it through OpenDock Hub review.

TerminalOpenDock

opendock install opendock/codex
opendock doctor
opendock auth login
opendock deploy codex